Live

API reference

A clean, read-only REST API over the entire multilingual catalog — games, expansions, publishers, designers, illustrators, themes, and mechanics. Responses are JSON. Access requires an API key.

Get an API key Interactive docs

Base URL

All endpoints are versioned and live under a single base URL. The current version is v1.

https://boardgamebase.com/api/v1

Authentication

Authenticate every request with your secret API key in the Authorization header as a Bearer token. Requests without a valid key are rejected with 401.

curl

curl https://boardgamebase.com/api/v1/games \
  -H "Authorization: Bearer bgb_live_xxxxxxxxxxxxxxxx"

API keys are free to create — sign in to the developer dashboard to generate one.

Localization

Localized fields (name, description) are returned as an object with one entry per language. Your client chooses which language to display.

GET /games/azul

{
  "id": "azul",
  "name": { "en": "Azul", "fr": "Azul" },
  "description": {
    "en": "Compose beautiful tiled walls…",
    "fr": "Composez de superbes murs de tuiles…"
  },
  "languages": ["en", "fr", "de", "es", "it"]
}

Supported: en, fr, de, es, it

Pagination

List endpoints use cursor pagination. Pass limit (max 50) and the cursor from the previous response's pagination.nextCursor; hasMore tells you when more pages remain.

{
  "data": [ /* … */ ],
  "pagination": { "nextCursor": "azul", "hasMore": true }
}

Errors

Errors use standard HTTP status codes and return an RFC 9457 problem+json body with a machine-readable code.

Parameter	Type	Description
200	OK	The request succeeded.
400	Bad Request	An invalid query parameter was supplied.
401	Unauthorized	Missing, invalid, or revoked API key.
404	Not Found	No resource matches the given slug.
429	Too Many Requests	Rate limit or monthly quota exceeded.

application/problem+json

{
  "type": "https://boardgamebase.com/docs/errors/not_found",
  "code": "not_found",
  "title": "Not found",
  "status": 404,
  "detail": "No game matches \"unknown-game\"."
}

Endpoints

GET/v1/games

List, search, and filter games.

Parameter	Type	Description
q	string	Full-text, typo-tolerant search over the title.
year	integer	Exact year of publication.
language	string	ISO 639-1 code the game is published in.
mechanic	string	Mechanic slug.
category	string	Category (theme) slug.
publisher	string	Publisher slug.
players	integer	Games playable with exactly this player count.
cursor	string	Cursor from the previous response's pagination.nextCursor.
limit	integer	Items per page (default 20, max 50).

Request

curl "https://boardgamebase.com/api/v1/games?players=4&mechanic=deck-building&limit=20" \
  -H "Authorization: Bearer bgb_live_xxxxxxxxxxxxxxxx"

Response

{
  "data": [
    {
      "id": "dominion",
      "name": { "en": "Dominion" },
      "yearPublished": 2008,
      "publisher": "Rio Grande Games",
      "players": { "min": 2, "max": 4 },
      "mechanics": ["deck-bag-and-pool-building"]
    }
  ],
  "pagination": { "nextCursor": "dominion", "hasMore": true }
}

GET/v1/games/{slug}

Retrieve a single game by its id, with its expansions.

Request

curl "https://boardgamebase.com/api/v1/games/brass-birmingham" \
  -H "Authorization: Bearer bgb_live_xxxxxxxxxxxxxxxx"

Response

{ "data": {
    "id": "brass-birmingham",
    "name": { "en": "Brass: Birmingham", "fr": "Brass: Birmingham" },
    "description": {
      "en": "Build canals and rail across the industrial Midlands…",
      "fr": "Développez canaux et rails dans les Midlands industrielles…"
    },
    "yearPublished": 2018,
    "editions": 3,
    "players": { "min": 2, "max": 4 },
    "playtime": { "min": 60, "max": 120 },
    "minAge": 14,
    "languages": ["en", "fr", "de"],
    "publisher": "Roxley",
    "designers": ["Gavan Brown", "Matt Tolman", "Martin Wallace"],
    "illustrators": ["Lina Cossette", "David Forest"],
    "categories": ["economic"],
    "mechanics": ["network-building", "hand-management"],
    "expansions": []
  } }

GET/v1/games/{slug}/expansions

Every expansion of a single game.

GET/v1/expansions

List expansions across the catalog.

Parameter	Type	Description
baseGame	string	Base game slug.
year	integer	Exact year of publication.
language	string	ISO 639-1 code the expansion is published in.
cursor	string	Pagination cursor.
limit	integer	Items per page (default 20, max 50).

Response

{
  "data": [
    {
      "id": "brass-birmingham-blackpool",
      "name": { "en": "Brass: Birmingham – Blackpool" },
      "yearPublished": 2022,
      "languages": ["en"],
      "baseGame": "brass-birmingham"
    }
  ],
  "pagination": { "nextCursor": null, "hasMore": false }
}

GET/v1/mechanics · /v1/categories

List all mechanics or categories with their localized labels.

Response

{
  "data": [
    { "id": "economic", "label": { "en": "Economic", "fr": "Économie" } },
    { "id": "abstract", "label": { "en": "Abstract", "fr": "Abstrait" } }
  ],
  "pagination": { "nextCursor": "abstract", "hasMore": true }
}

GET/v1/publishers

List publishers.

Parameter	Type	Description
q	string	Name search.
cursor	string	Pagination cursor.
limit	integer	Items per page (default 20, max 50).

Response

{
  "data": [ { "id": "roxley", "name": "Roxley" } ],
  "pagination": { "nextCursor": "roxley", "hasMore": true }
}

GET/v1/people

List designers and illustrators.

Parameter	Type	Description
q	string	Name search.
role	designer \| illustrator	Filter by credited role.
cursor	string	Pagination cursor.
limit	integer	Items per page (default 20, max 50).

Response

{
  "data": [ { "id": "martin-wallace", "name": "Martin Wallace" } ],
  "pagination": { "nextCursor": "martin-wallace", "hasMore": true }
}

The game object

Every game returned by the API has the following shape. Internal identifiers are never exposed.

Parameter	Type	Description
id	string	Stable, URL-friendly identifier (slug).
name	localized	Title as an object keyed by language code.
description	localized	Short description per language.
yearPublished	integer	Year of first publication.
editions	integer	Number of editions released.
players	{ min, max }	Supported player count.
playtime	{ min, max }	Typical play time in minutes.
minAge	integer	Recommended minimum age.
languages	string[]	ISO 639-1 codes the game is published in.
publisher	string \| null	Publishing company.
designers	string[]	Game designers.
illustrators	string[]	Box and component illustrators.
categories	string[]	Category (theme) slugs.
mechanics	string[]	Mechanic slugs.
expansions	object[]	Expansions for this game.

Get an API key

Create a free developer account to generate a key and start building. The free tier is generous — paid plans unlock higher limits.

Developers OpenAPI spec