What's new

Amalgadon now has a public API. Whether you're building a bot, a spreadsheet, or just want to automate sharing your boards, there are three endpoints to help you do it.

Full documentation is at /developers.

Endpoints at a glance

Endpoint	Auth	What it does
`GET /api/cards`	None	Full Battlegrounds card database
`GET /api/lookup`	Bearer token	Resolve a card name or ID to its details
`POST /api/encode`	Bearer token	Encode a board and get back share/remix/embed URLs

`GET /api/cards`

Returns the full Battlegrounds card database — every minion, hero, trinket, and spell. No authentication required. Useful as a reference or for building your own lookup UI.

`GET /api/lookup`

Resolve a card name or ID to its full details: stats, card text, tribe, tier, and a link to the card's detail page on Amalgadon.

GET /api/lookup?q=Brann+Bronzebeard
GET /api/lookup?q=Murloc+Tidecaller&type=minion

Requires a Bearer token. Useful for validating card names before calling /api/encode.

`POST /api/encode`

The main integration endpoint. Send a board as a human-readable JSON description — using card names rather than internal IDs — and get back a share permalink, remix link, and embed URL in one step.

{
  "hero": "Patches the Pirate",
  "slots": [
    { "name": "Murloc Tidecaller" },
    { "name": "Brann Bronzebeard", "golden": true }
  ],
  "lesserTrinket": "Rock Buddy",
  "title": "My Murloc Build"
}

Requires a Bearer token. Rate-limited to 30 requests per 60 seconds per IP.

No card IDs required

The API is designed to work with card names rather than internal Hearthstone IDs. Names are fuzzy-matched, so minor typos and capitalisation differences are handled automatically. The response always includes a resolved block confirming exactly which cards were matched — always check this during development to catch unexpected fuzzy matches.

Authentication

Private endpoints require a Bearer token in the Authorization header:

Authorization: Bearer amgd_<40 hex characters>

Keys are free and generated instantly — no approval required. Request one at the bottom of the developer docs →

Skipping the API entirely

If you already have card IDs from /api/cards and just need a deep-link, you can encode a board client-side with no API call at all. Compress the board JSON with pako (deflate, level 9), base64url-encode it, and prepend p. Full details in the manual encoding section of the docs.

Deep links

Once you have a build code or short ID:

URL	Behaviour
`/board-builder?remix=<code>`	Opens the builder with the board pre-loaded
`/build/<id>`	Read-only permalink with voting and remix
`/embed/<id>`	Minimal view for `<iframe>` embeds

The Discord bot is built on this same API — its source is a good real-world reference if you're looking for an integration example.

Build on Amalgadon: the Developer API