Saltar al contenido

API

API reference

Esta referencia solo está en inglés.

Version 1.0.0. Base address https://api.thebgdb.org/v1. This page is built from the OpenAPI description, which is published with every release.

Read the catalog of board games: facts about each game, the people and companies behind it, how it is classified and what it won.

Reading needs no key and no account. Every answer is JSON. Successful answers put their payload under data; failures return { "error": "…", "code": "…" }: error is a sentence in English written for people, code a stable name for the refusal (listed under the Error schema) that a program can act on or translate.

Accounts are created on the website, where members add photos, playlists and rulebooks and keep lists. A member can create a personal API token on their account page and send it as Authorization: Bearer <token>.

Members' input. Ratings, complexity, ranks, recommended age, player counts, language dependence on a game all come from this site's own members, through the routes described here. A game nobody has rated or voted on has null (or an empty list) there, never a guess.

Limits. Without a token: 300 requests a minute per address. With a personal API token (Authorization: Bearer bgdb_…, created on the website's account page): 1 200 a minute, or 6 000 on the paid plan. Beyond the limit the API answers 429. Catalog answers are cached for up to five minutes, so a change can take that long to show.

Slugs are stable: once a game or a credit has a slug, it does not change.

Credits. Some descriptions come from Wikipedia and some covers from Wikimedia Commons, under licences that ask for credit: GET /v1/credits lists them, with their source, licence and author.

Games

Look games up, list them, search them.

List games, a page at a time

GET/games

Games, ordered and filtered as asked. To read everything, call again with cursor set to the nextCursor you received, until nextCursor is null.

ParameterTypeMeaning
limit optionalintegerHow many games to return. min 1, max 100, default 20
cursor optionalstringThe nextCursor of the previous page. Omit for the first page.
order optional"added" | "new" | "name" | "year" | "oldest" | "hot" | "rating" | "complexity" | "random"added oldest entry first, new newest entry first, name alphabetical, year most recent game first, oldest oldest game first (games with no known year are left out), hot highest hotness first (see GET /hot), rating highest weighted rating first, complexity heaviest first, random shuffled by seed. With rating and complexity, games nobody has rated or voted on come last. default "added"
seed optionalintegerWith order=random: any whole number. The same seed gives the same order, so pass it with every page to go through the list without seeing a game twice. Without it the order changes every hour. Other orders ignore it. min 0, max 2147483646
kind optional"game" | "expansion" | "accessory"Only entries of this type: game a stand-alone game, expansion one that needs another game, accessory something that is not played (sleeves, an insert, a playmat). Without it, all three are listed.
players optionalintegerOnly games that can be played by this many players. min 1, max 99
players_from optionalintegerWith players_to: only games that can be played at every count from players_from to players_to. Alone, the same as players. min 1, max 99
players_to optionalintegerUpper end of the range started by players_from. min 1, max 99
year_from optionalintegerOnly games published in this year or later.
year_to optionalintegerOnly games published in this year or earlier.
time_max optionalintegerOnly games that can be finished within this many minutes. min 1
age optionalintegerOnly games suitable for someone of this age. min 0, max 99
illustrated optional"1"Set to 1 for only games that have a cover image.
cover optional"ok" | "needs_work" | "unreviewed" | "none"Only games whose cover is in this state. ok: a good cover (imageAcceptable true). needs_work: a cover found not good (not the box front, a person in it, or imageQuality below 3), so a better one is wanted. unreviewed: a cover nothing has looked at yet. none: no cover at all. A cover that was not looked at is neither ok nor needs_work.
complexity_min optionalnumberOnly games whose average complexity is at least this. Games nobody has voted on are left out. min 1, max 5
complexity_max optionalnumberOnly games whose average complexity is at most this. Games nobody has voted on are left out. min 1, max 5
rating_min optionalnumberOnly games whose average rating is at least this. Games nobody has rated are left out. min 1, max 10
lang optionalstringA language code (BCP 47) such as "fr", "ja" or "pt-BR". A game that has a name in that language is returned with it as name, and its main name as originalName; a regional code falls back on its language ("fr-CA" on "fr"), a language with no name of its own takes a regional one ("pt" shows a name the game only has in "pt-BR"), and a game with no name in the language keeps its main name. Only names are localised: descriptions and summaries stay in English.

Answers

200objectA page of games.
400cursor, order, lang or a filter is not an accepted value.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of GameSummary
totalintegerHow many games match, across all pages.
nextCursorstring or nullPass as cursor to get the next page. Null on the last page.

For example:

{
  "data": [
    {
      "id": "5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77",
      "slug": "catan",
      "name": "Catan",
      "originalName": null,
      "kind": "game",
      "yearPublished": 1995,
      "players": {
        "min": 3,
        "max": 4
      },
      "image": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=600",
      "thumbnail": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=200",
      "rating": {
        "average": 7.42,
        "count": 318,
        "weighted": 7.31
      },
      "complexity": {
        "average": 2.29,
        "votes": 121
      }
    }
  ],
  "total": 21925,
  "nextCursor": "20"
}
curl "https://api.thebgdb.org/v1/games"

List every game's slug, cover and last change

GET/sitemap/games

A compact listing meant for sitemaps and mirrors: up to 10 000 games per call, in the order they entered the catalog.

ParameterTypeMeaning
limit optionalinteger min 1, max 10000, default 10000
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectA page of slugs.
400cursor is not a value this API issued.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of object
data[].slugstring
data[].namestring
data[].updatedAtstring (date-time)
data[].imagestring or nullThe cover, as on the game: a full address, or a path on this API for a member's photo. Null when the game has none.
nextCursorstring or null
curl "https://api.thebgdb.org/v1/sitemap/games"

Count games by first letter and by year

GET/index/games/counts

The table of contents of the games index: how many names start with each letter, and how many games came out each year. Games whose year is unknown are in no year.

Answers

200objectThe counts.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataobject
data.lettersarray of object
data.yearsarray of object

For example:

{
  "data": {
    "letters": [
      {
        "letter": "0",
        "games": 212
      },
      {
        "letter": "A",
        "games": 1340
      }
    ],
    "years": [
      {
        "year": 1995,
        "games": 210
      },
      {
        "year": 1996,
        "games": 198
      }
    ]
  }
}
curl "https://api.thebgdb.org/v1/index/games/counts"

List game names by first letter or by year

GET/index/games

Names only, in alphabetical order, up to 500 per call: what an A to Z index or a list of a year's games needs. Use /games for full summaries. With lang, each game is shown under its name in that language, but the letter and the order stay those of the main name (originalName): a game is under one letter, the same in every language.

ParameterTypeMeaning
lang optionalstringA language code (BCP 47) such as "fr", "ja" or "pt-BR". A game that has a name in that language is returned with it as name, and its main name as originalName; a regional code falls back on its language ("fr-CA" on "fr"), a language with no name of its own takes a regional one ("pt" shows a name the game only has in "pt-BR"), and a game with no name in the language keeps its main name. Only names are localised: descriptions and summaries stay in English.
letter optionalstringOnly games whose main name starts with this letter (A to Z, case ignored). 0 gives the names that start with anything else.
year optionalintegerOnly games first published this year. min -4000, max 2100
limit optionalinteger min 1, max 500, default 500
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectA page of names.
400letter, year or cursor is not valid.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of object
data[].idstring (uuid)
data[].slugstring
data[].namestringThe name in the language asked for with lang, when the game has one; its main name otherwise.
data[].originalNamestring or nullThe main name, which decides the letter and the order, when name is a translation of it.
data[].yearPublishedinteger or null
totalintegerHow many games match in all.
nextCursorstring or nullPass as cursor to get the next page. Null on the last page.

For example:

{
  "data": [
    {
      "id": "6c45ac28-4841-43f5-a1b3-59ea01e63f16",
      "slug": "catan",
      "name": "Catan",
      "originalName": null,
      "yearPublished": 1995
    }
  ],
  "total": 1,
  "nextCursor": null
}
curl "https://api.thebgdb.org/v1/index/games"

Get one game

GET/games/{id}

Everything the catalog knows about a game: its facts, its names in every language, its credits by kind, its photos, what members made of it (rating, complexity, ranks, poll results), and how many playlists and rulebooks it has. Answers are cached, so a vote can take up to five minutes to show here.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.
lang optionalstringA language code (BCP 47) such as "fr", "ja" or "pt-BR". A game that has a name in that language is returned with it as name, and its main name as originalName; a regional code falls back on its language ("fr-CA" on "fr"), a language with no name of its own takes a regional one ("pt" shows a name the game only has in "pt-BR"), and a game with no name in the language keeps its main name. Only names are localised: descriptions and summaries stay in English.

Answers

200objectThe game.
404No game has this id.
410The entry was withdrawn because it is not a game (a series, a kind of game, an app); reason says what it is.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataGame

Search games by name

GET/search

Returns games one of whose names contains every word of q, in any order: the main name or any alternate name, in any language. A game is returned once, with matchedName saying which alternate name was found when it was not the main one. Case, accents and punctuation are ignored (catan! finds Catan). Words shorter than three characters are ignored unless the query has no longer word, in which case names starting with the query are returned (alternate names then have to start with it exactly as written). Misspellings: when fewer than limit games match the query as written, games with a name close to it are added after them, marked approximate: true (cattan finds Catan, brass birmigham finds Brass: Birmingham). Close means one slip (a character added, dropped or replaced, or two neighbours swapped) for a query of 4 to 8 characters, two up to 16, three beyond; the query may be close to a whole name or to consecutive words of one. A query of up to three characters is never corrected, and one of four or five only when nothing matches it as written. A single word of four or five characters that shares no run of three characters with any name (kahn for Khan, uzno for UNO) is compared with the names of about its length (one character shorter or longer at most) that start with the same letter; a slip in the first letter of such a word is not corrected.

ParameterTypeMeaning
q requiredstringWhat to look for. at least 2 characters, at most 100 characters
limit optionalinteger min 1, max 50, default 20
lang optionalstringA language code (BCP 47) such as "fr", "ja" or "pt-BR". A game that has a name in that language is returned with it as name, and its main name as originalName; a regional code falls back on its language ("fr-CA" on "fr"), a language with no name of its own takes a regional one ("pt" shows a name the game only has in "pt-BR"), and a game with no name in the language keeps its main name. Only names are localised: descriptions and summaries stay in English.

Answers

200objectMatching games, best match first: games whose main name starts with the query, then other main names, then alternate names; then the approximate matches, closest first.
400q is shorter than 2 or longer than 100 characters, or lang is not a language code.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
querystring
dataarray of SearchResult

For example:

{
  "query": "colons de catane",
  "data": [
    {
      "id": "5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77",
      "slug": "catan",
      "name": "Catan",
      "originalName": null,
      "kind": "game",
      "yearPublished": 1995,
      "players": {
        "min": 3,
        "max": 4
      },
      "image": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=600",
      "thumbnail": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=200",
      "rating": {
        "average": 7.42,
        "count": 318,
        "weighted": 7.31
      },
      "complexity": {
        "average": 2.29,
        "votes": 121
      },
      "matchedName": {
        "name": "Les Colons de Catane",
        "language": "fr"
      },
      "approximate": false
    }
  ]
}
curl "https://api.thebgdb.org/v1/search?q=catan"

Texts and images to credit

GET/credits

The descriptions and covers that come from other sources: descriptions taken from a page (Wikipedia, CC BY-SA; a publisher's own page, with no licence on record) and covers from Wikimedia Commons under a licence asking for credit (CC BY, CC BY-SA). One entry per text or image, ordered by the game's main name; a game with both has its text first. Show the source, the licence and the author wherever you reuse them. The website lists the same at https://thebgdb.org/credits.

ParameterTypeMeaning
kind optional"text" | "image"Only texts, or only images. Both when absent.
limit optionalinteger min 1, max 100, default 100
cursor optionalstringThe nextCursor of the previous page.
lang optionalstringA language code (BCP 47) such as "fr", "ja" or "pt-BR". A game that has a name in that language is returned with it as name, and its main name as originalName; a regional code falls back on its language ("fr-CA" on "fr"), a language with no name of its own takes a regional one ("pt" shows a name the game only has in "pt-BR"), and a game with no name in the language keeps its main name. Only names are localised: descriptions and summaries stay in English.

Answers

200objectA page of credits.
400kind or cursor is not an accepted value, or lang is not a language code.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of object
data[].kind"text" | "image"text: the game's description. image: the game's cover from its source.
data[].gameobject
data[].sourceUrlstring or null (uri)The page the text was taken from, or the page that documents the image. Null when no such page is on record.
data[].sourceTitlestring or nullThe Wikipedia article's title or the image's file name. Null when the address does not give one.
data[].licensestringThe licence, by its short name. "None on record" for a text taken from a page that states none, such as a publisher's own page.
data[].licenseUrlstring or null (uri)The licence's deed. Null when the short name does not say which version.
data[].authorstring or nullThe author to name, as the source names them. Null when the source names nobody (Wikipedia texts are credited to the article): credit the source itself.
totalintegerHow many credits match.
nextCursorstring or nullPass as cursor to get the next page. Null on the last page.

For example:

{
  "data": [
    {
      "kind": "text",
      "game": {
        "id": "5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77",
        "slug": "catan",
        "name": "Catan"
      },
      "sourceUrl": "https://en.wikipedia.org/wiki/Catan",
      "sourceTitle": "Catan",
      "license": "CC BY-SA 4.0",
      "licenseUrl": "https://creativecommons.org/licenses/by-sa/4.0/",
      "author": null
    }
  ],
  "total": 1,
  "nextCursor": null
}
curl "https://api.thebgdb.org/v1/credits"

Games with a round birthday this year

GET/anniversaries

Games whose age this year is a multiple of five, at most 100. The catalog records publication years, not days.

ParameterTypeMeaning
order optional"oldest" | "youngest"oldest: the oldest game first (the largest age). youngest: the youngest first (the smallest age, such as 5 years). Games of the same age come in alphabetical order. With more than 100 anniversaries, the order also decides which 100 are returned. default "oldest"
lang optionalstringA language code (BCP 47) such as "fr", "ja" or "pt-BR". A game that has a name in that language is returned with it as name, and its main name as originalName; a regional code falls back on its language ("fr-CA" on "fr"), a language with no name of its own takes a regional one ("pt" shows a name the game only has in "pt-BR"), and a game with no name in the language keeps its main name. Only names are localised: descriptions and summaries stay in English.

Answers

200objectThis year's anniversaries, in the order asked for.
400order is not an accepted value.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
yearinteger
dataarray of GameSummary + object
curl "https://api.thebgdb.org/v1/anniversaries"

Games with the most recent award wins

GET/honours/recent

The games that won an award most recently, newest year first, one entry per game with the prize that put it there. Wins with no stated year are left out.

ParameterTypeMeaning
limit optionalinteger min 1, max 30, default 10
lang optionalstringA language code (BCP 47) such as "fr", "ja" or "pt-BR". A game that has a name in that language is returned with it as name, and its main name as originalName; a regional code falls back on its language ("fr-CA" on "fr"), a language with no name of its own takes a regional one ("pt" shows a name the game only has in "pt-BR"), and a game with no name in the language keeps its main name. Only names are localised: descriptions and summaries stay in English.

Answers

200objectWinning games, most recent first.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of object
data[].gameGameSummary
data[].honourobject

For example:

{
  "data": [
    {
      "game": {
        "id": "5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77",
        "slug": "catan",
        "name": "Catan",
        "originalName": null,
        "kind": "game",
        "yearPublished": 1995,
        "players": {
          "min": 3,
          "max": 4
        },
        "image": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=600",
        "thumbnail": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=200",
        "rating": {
          "average": 7.42,
          "count": 318,
          "weighted": 7.31
        },
        "complexity": {
          "average": 2.29,
          "votes": 121
        }
      },
      "honour": {
        "award": {
          "slug": "spiel-des-jahres",
          "name": "Spiel des Jahres"
        },
        "category": null,
        "year": 1995,
        "result": "winner"
      }
    }
  ]
}
curl "https://api.thebgdb.org/v1/honours/recent"

The games people are looking at now

GET/hot

Games by hotness, highest first; games with none are left out. Hotness is recomputed every hour from views over the last 7 days (the game's page opened on the website, or the game read with GET /games/{id}; programs that announce themselves are not counted), the game's weighted rating and the number of ratings given in the last 30 days. **The formula is provisional and will change**; rely on the order, not on a value. The same order is available on any list of games with order=hot.

ParameterTypeMeaning
limit optionalinteger min 1, max 100, default 20
lang optionalstringA language code (BCP 47) such as "fr", "ja" or "pt-BR". A game that has a name in that language is returned with it as name, and its main name as originalName; a regional code falls back on its language ("fr-CA" on "fr"), a language with no name of its own takes a regional one ("pt" shows a name the game only has in "pt-BR"), and a game with no name in the language keeps its main name. Only names are localised: descriptions and summaries stay in English.

Answers

200objectThe hottest games, hottest first.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of GameSummary

For example:

{
  "data": [
    {
      "id": "5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77",
      "slug": "catan",
      "name": "Catan",
      "originalName": null,
      "kind": "game",
      "yearPublished": 1995,
      "players": {
        "min": 3,
        "max": 4
      },
      "image": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=600",
      "thumbnail": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=200",
      "rating": {
        "average": 7.42,
        "count": 318,
        "weighted": 7.31
      },
      "complexity": {
        "average": 2.29,
        "votes": 121
      }
    }
  ]
}
curl "https://api.thebgdb.org/v1/hot"

Designers

People who design games.

List designers

GET/designers

The designers in the catalog with the number of games linked to each, a page at a time.

ParameterTypeMeaning
order optional"name" | "games"name alphabetical, games most games first. default "name"
prefix optionalstringOnly names starting with this text. Case is ignored. at most 40 characters
limit optionalinteger min 1, max 500, default 100
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectA page of designers.
400cursor or order is not an accepted value.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of TermCount
totalintegerHow many match, across all pages.
nextCursorstring or null

For example:

{
  "data": [
    {
      "slug": "klaus-teuber",
      "name": "Klaus Teuber",
      "games": 2
    }
  ],
  "total": 1,
  "nextCursor": null
}
curl "https://api.thebgdb.org/v1/designers"

Get one designer and its games

GET/designers/{slug}

The designer and the games linked to it, a page at a time, optionally filtered and ordered. total counts the games that pass the filters.

ParameterTypeMeaning
slug in the addressstringThe designer's slug, as returned by the API.
order optional"added" | "new" | "name" | "year" | "oldest" | "hot" | "rating" | "complexity" | "random"added oldest entry first, new newest entry first, name alphabetical, year most recent game first, oldest oldest game first (games with no known year are left out), hot highest hotness first (see GET /hot), rating highest weighted rating first, complexity heaviest first, random shuffled by seed. With rating and complexity, games nobody has rated or voted on come last. Without it: most recently added first.
seed optionalintegerWith order=random: any whole number. The same seed gives the same order, so pass it with every page to go through the list without seeing a game twice. Without it the order changes every hour. Other orders ignore it. min 0, max 2147483646
kind optional"game" | "expansion" | "accessory"Only entries of this type: game a stand-alone game, expansion one that needs another game, accessory something that is not played (sleeves, an insert, a playmat). Without it, all three are listed.
players optionalintegerOnly games that can be played by this many players. min 1, max 99
players_from optionalintegerWith players_to: only games that can be played at every count from players_from to players_to. Alone, the same as players. min 1, max 99
players_to optionalintegerUpper end of the range started by players_from. min 1, max 99
year_from optionalintegerOnly games published in this year or later.
year_to optionalintegerOnly games published in this year or earlier.
time_max optionalintegerOnly games that can be finished within this many minutes. min 1
age optionalintegerOnly games suitable for someone of this age. min 0, max 99
illustrated optional"1"Set to 1 for only games that have a cover image.
cover optional"ok" | "needs_work" | "unreviewed" | "none"Only games whose cover is in this state. ok: a good cover (imageAcceptable true). needs_work: a cover found not good (not the box front, a person in it, or imageQuality below 3), so a better one is wanted. unreviewed: a cover nothing has looked at yet. none: no cover at all. A cover that was not looked at is neither ok nor needs_work.
complexity_min optionalnumberOnly games whose average complexity is at least this. Games nobody has voted on are left out. min 1, max 5
complexity_max optionalnumberOnly games whose average complexity is at most this. Games nobody has voted on are left out. min 1, max 5
rating_min optionalnumberOnly games whose average rating is at least this. Games nobody has rated are left out. min 1, max 10
lang optionalstringA language code (BCP 47) such as "fr", "ja" or "pt-BR". A game that has a name in that language is returned with it as name, and its main name as originalName; a regional code falls back on its language ("fr-CA" on "fr"), a language with no name of its own takes a regional one ("pt" shows a name the game only has in "pt-BR"), and a game with no name in the language keeps its main name. Only names are localised: descriptions and summaries stay in English.
limit optionalinteger min 1, max 100, default 60
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectThe designer with its games.
404No designer has this slug.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataTermWithGames

For example:

{
  "data": {
    "slug": "klaus-teuber",
    "name": "Klaus Teuber",
    "total": 1,
    "games": [
      {
        "id": "5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77",
        "slug": "catan",
        "name": "Catan",
        "originalName": null,
        "kind": "game",
        "yearPublished": 1995,
        "players": {
          "min": 3,
          "max": 4
        },
        "image": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=600",
        "thumbnail": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=200",
        "rating": {
          "average": 7.42,
          "count": 318,
          "weighted": 7.31
        },
        "complexity": {
          "average": 2.29,
          "votes": 121
        }
      }
    ],
    "nextCursor": null
  }
}

Artists

People who illustrate games.

List artists

GET/artists

The artists in the catalog with the number of games linked to each, a page at a time.

ParameterTypeMeaning
order optional"name" | "games"name alphabetical, games most games first. default "name"
prefix optionalstringOnly names starting with this text. Case is ignored. at most 40 characters
limit optionalinteger min 1, max 500, default 100
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectA page of artists.
400cursor or order is not an accepted value.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of TermCount
totalintegerHow many match, across all pages.
nextCursorstring or null

For example:

{
  "data": [
    {
      "slug": "beth-sobel",
      "name": "Beth Sobel",
      "games": 2
    }
  ],
  "total": 1,
  "nextCursor": null
}
curl "https://api.thebgdb.org/v1/artists"

Get one artist and its games

GET/artists/{slug}

The artist and the games linked to it, a page at a time, optionally filtered and ordered. total counts the games that pass the filters.

ParameterTypeMeaning
slug in the addressstringThe artist's slug, as returned by the API.
order optional"added" | "new" | "name" | "year" | "oldest" | "hot" | "rating" | "complexity" | "random"added oldest entry first, new newest entry first, name alphabetical, year most recent game first, oldest oldest game first (games with no known year are left out), hot highest hotness first (see GET /hot), rating highest weighted rating first, complexity heaviest first, random shuffled by seed. With rating and complexity, games nobody has rated or voted on come last. Without it: most recently added first.
seed optionalintegerWith order=random: any whole number. The same seed gives the same order, so pass it with every page to go through the list without seeing a game twice. Without it the order changes every hour. Other orders ignore it. min 0, max 2147483646
kind optional"game" | "expansion" | "accessory"Only entries of this type: game a stand-alone game, expansion one that needs another game, accessory something that is not played (sleeves, an insert, a playmat). Without it, all three are listed.
players optionalintegerOnly games that can be played by this many players. min 1, max 99
players_from optionalintegerWith players_to: only games that can be played at every count from players_from to players_to. Alone, the same as players. min 1, max 99
players_to optionalintegerUpper end of the range started by players_from. min 1, max 99
year_from optionalintegerOnly games published in this year or later.
year_to optionalintegerOnly games published in this year or earlier.
time_max optionalintegerOnly games that can be finished within this many minutes. min 1
age optionalintegerOnly games suitable for someone of this age. min 0, max 99
illustrated optional"1"Set to 1 for only games that have a cover image.
cover optional"ok" | "needs_work" | "unreviewed" | "none"Only games whose cover is in this state. ok: a good cover (imageAcceptable true). needs_work: a cover found not good (not the box front, a person in it, or imageQuality below 3), so a better one is wanted. unreviewed: a cover nothing has looked at yet. none: no cover at all. A cover that was not looked at is neither ok nor needs_work.
complexity_min optionalnumberOnly games whose average complexity is at least this. Games nobody has voted on are left out. min 1, max 5
complexity_max optionalnumberOnly games whose average complexity is at most this. Games nobody has voted on are left out. min 1, max 5
rating_min optionalnumberOnly games whose average rating is at least this. Games nobody has rated are left out. min 1, max 10
lang optionalstringA language code (BCP 47) such as "fr", "ja" or "pt-BR". A game that has a name in that language is returned with it as name, and its main name as originalName; a regional code falls back on its language ("fr-CA" on "fr"), a language with no name of its own takes a regional one ("pt" shows a name the game only has in "pt-BR"), and a game with no name in the language keeps its main name. Only names are localised: descriptions and summaries stay in English.
limit optionalinteger min 1, max 100, default 60
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectThe artist with its games.
404No artist has this slug.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataTermWithGames

For example:

{
  "data": {
    "slug": "beth-sobel",
    "name": "Beth Sobel",
    "total": 1,
    "games": [
      {
        "id": "5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77",
        "slug": "catan",
        "name": "Catan",
        "originalName": null,
        "kind": "game",
        "yearPublished": 1995,
        "players": {
          "min": 3,
          "max": 4
        },
        "image": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=600",
        "thumbnail": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=200",
        "rating": {
          "average": 7.42,
          "count": 318,
          "weighted": 7.31
        },
        "complexity": {
          "average": 2.29,
          "votes": 121
        }
      }
    ],
    "nextCursor": null
  }
}

Publishers

Companies that publish games.

List publishers

GET/publishers

The publishers in the catalog with the number of games linked to each, a page at a time.

ParameterTypeMeaning
order optional"name" | "games"name alphabetical, games most games first. default "name"
prefix optionalstringOnly names starting with this text. Case is ignored. at most 40 characters
limit optionalinteger min 1, max 500, default 100
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectA page of publishers.
400cursor or order is not an accepted value.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of TermCount
totalintegerHow many match, across all pages.
nextCursorstring or null

For example:

{
  "data": [
    {
      "slug": "kosmos",
      "name": "Kosmos",
      "games": 2
    }
  ],
  "total": 1,
  "nextCursor": null
}
curl "https://api.thebgdb.org/v1/publishers"

Get one publisher and its games

GET/publishers/{slug}

The publisher and the games linked to it, a page at a time, optionally filtered and ordered. total counts the games that pass the filters.

ParameterTypeMeaning
slug in the addressstringThe publisher's slug, as returned by the API.
order optional"added" | "new" | "name" | "year" | "oldest" | "hot" | "rating" | "complexity" | "random"added oldest entry first, new newest entry first, name alphabetical, year most recent game first, oldest oldest game first (games with no known year are left out), hot highest hotness first (see GET /hot), rating highest weighted rating first, complexity heaviest first, random shuffled by seed. With rating and complexity, games nobody has rated or voted on come last. Without it: most recently added first.
seed optionalintegerWith order=random: any whole number. The same seed gives the same order, so pass it with every page to go through the list without seeing a game twice. Without it the order changes every hour. Other orders ignore it. min 0, max 2147483646
kind optional"game" | "expansion" | "accessory"Only entries of this type: game a stand-alone game, expansion one that needs another game, accessory something that is not played (sleeves, an insert, a playmat). Without it, all three are listed.
players optionalintegerOnly games that can be played by this many players. min 1, max 99
players_from optionalintegerWith players_to: only games that can be played at every count from players_from to players_to. Alone, the same as players. min 1, max 99
players_to optionalintegerUpper end of the range started by players_from. min 1, max 99
year_from optionalintegerOnly games published in this year or later.
year_to optionalintegerOnly games published in this year or earlier.
time_max optionalintegerOnly games that can be finished within this many minutes. min 1
age optionalintegerOnly games suitable for someone of this age. min 0, max 99
illustrated optional"1"Set to 1 for only games that have a cover image.
cover optional"ok" | "needs_work" | "unreviewed" | "none"Only games whose cover is in this state. ok: a good cover (imageAcceptable true). needs_work: a cover found not good (not the box front, a person in it, or imageQuality below 3), so a better one is wanted. unreviewed: a cover nothing has looked at yet. none: no cover at all. A cover that was not looked at is neither ok nor needs_work.
complexity_min optionalnumberOnly games whose average complexity is at least this. Games nobody has voted on are left out. min 1, max 5
complexity_max optionalnumberOnly games whose average complexity is at most this. Games nobody has voted on are left out. min 1, max 5
rating_min optionalnumberOnly games whose average rating is at least this. Games nobody has rated are left out. min 1, max 10
lang optionalstringA language code (BCP 47) such as "fr", "ja" or "pt-BR". A game that has a name in that language is returned with it as name, and its main name as originalName; a regional code falls back on its language ("fr-CA" on "fr"), a language with no name of its own takes a regional one ("pt" shows a name the game only has in "pt-BR"), and a game with no name in the language keeps its main name. Only names are localised: descriptions and summaries stay in English.
limit optionalinteger min 1, max 100, default 60
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectThe publisher with its games.
404No publisher has this slug.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataTermWithGames

For example:

{
  "data": {
    "slug": "kosmos",
    "name": "Kosmos",
    "total": 1,
    "games": [
      {
        "id": "5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77",
        "slug": "catan",
        "name": "Catan",
        "originalName": null,
        "kind": "game",
        "yearPublished": 1995,
        "players": {
          "min": 3,
          "max": 4
        },
        "image": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=600",
        "thumbnail": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=200",
        "rating": {
          "average": 7.42,
          "count": 318,
          "weighted": 7.31
        },
        "complexity": {
          "average": 2.29,
          "votes": 121
        }
      }
    ],
    "nextCursor": null
  }
}

Categories

What a game is about.

List categories

GET/categories

The categories in the catalog with the number of games linked to each, a page at a time.

ParameterTypeMeaning
order optional"name" | "games"name alphabetical, games most games first. default "name"
prefix optionalstringOnly names starting with this text. Case is ignored. at most 40 characters
limit optionalinteger min 1, max 500, default 100
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectA page of categories.
400cursor or order is not an accepted value.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of TermCount
totalintegerHow many match, across all pages.
nextCursorstring or null

For example:

{
  "data": [
    {
      "slug": "family",
      "name": "Family",
      "games": 2
    }
  ],
  "total": 1,
  "nextCursor": null
}
curl "https://api.thebgdb.org/v1/categories"

Get one category and its games

GET/categories/{slug}

The category and the games linked to it, a page at a time, optionally filtered and ordered. total counts the games that pass the filters.

ParameterTypeMeaning
slug in the addressstringThe category's slug, as returned by the API.
order optional"added" | "new" | "name" | "year" | "oldest" | "hot" | "rating" | "complexity" | "random"added oldest entry first, new newest entry first, name alphabetical, year most recent game first, oldest oldest game first (games with no known year are left out), hot highest hotness first (see GET /hot), rating highest weighted rating first, complexity heaviest first, random shuffled by seed. With rating and complexity, games nobody has rated or voted on come last. Without it: most recently added first.
seed optionalintegerWith order=random: any whole number. The same seed gives the same order, so pass it with every page to go through the list without seeing a game twice. Without it the order changes every hour. Other orders ignore it. min 0, max 2147483646
kind optional"game" | "expansion" | "accessory"Only entries of this type: game a stand-alone game, expansion one that needs another game, accessory something that is not played (sleeves, an insert, a playmat). Without it, all three are listed.
players optionalintegerOnly games that can be played by this many players. min 1, max 99
players_from optionalintegerWith players_to: only games that can be played at every count from players_from to players_to. Alone, the same as players. min 1, max 99
players_to optionalintegerUpper end of the range started by players_from. min 1, max 99
year_from optionalintegerOnly games published in this year or later.
year_to optionalintegerOnly games published in this year or earlier.
time_max optionalintegerOnly games that can be finished within this many minutes. min 1
age optionalintegerOnly games suitable for someone of this age. min 0, max 99
illustrated optional"1"Set to 1 for only games that have a cover image.
cover optional"ok" | "needs_work" | "unreviewed" | "none"Only games whose cover is in this state. ok: a good cover (imageAcceptable true). needs_work: a cover found not good (not the box front, a person in it, or imageQuality below 3), so a better one is wanted. unreviewed: a cover nothing has looked at yet. none: no cover at all. A cover that was not looked at is neither ok nor needs_work.
complexity_min optionalnumberOnly games whose average complexity is at least this. Games nobody has voted on are left out. min 1, max 5
complexity_max optionalnumberOnly games whose average complexity is at most this. Games nobody has voted on are left out. min 1, max 5
rating_min optionalnumberOnly games whose average rating is at least this. Games nobody has rated are left out. min 1, max 10
lang optionalstringA language code (BCP 47) such as "fr", "ja" or "pt-BR". A game that has a name in that language is returned with it as name, and its main name as originalName; a regional code falls back on its language ("fr-CA" on "fr"), a language with no name of its own takes a regional one ("pt" shows a name the game only has in "pt-BR"), and a game with no name in the language keeps its main name. Only names are localised: descriptions and summaries stay in English.
limit optionalinteger min 1, max 100, default 60
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectThe category with its games.
404No category has this slug.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataTermWithGames

For example:

{
  "data": {
    "slug": "family",
    "name": "Family",
    "total": 1,
    "games": [
      {
        "id": "5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77",
        "slug": "catan",
        "name": "Catan",
        "originalName": null,
        "kind": "game",
        "yearPublished": 1995,
        "players": {
          "min": 3,
          "max": 4
        },
        "image": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=600",
        "thumbnail": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=200",
        "rating": {
          "average": 7.42,
          "count": 318,
          "weighted": 7.31
        },
        "complexity": {
          "average": 2.29,
          "votes": 121
        }
      }
    ],
    "nextCursor": null
  }
}

Mechanics

How a game plays.

List mechanics

GET/mechanics

The mechanics in the catalog with the number of games linked to each, a page at a time.

ParameterTypeMeaning
order optional"name" | "games"name alphabetical, games most games first. default "name"
prefix optionalstringOnly names starting with this text. Case is ignored. at most 40 characters
limit optionalinteger min 1, max 500, default 100
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectA page of mechanics.
400cursor or order is not an accepted value.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of TermCount
totalintegerHow many match, across all pages.
nextCursorstring or null

For example:

{
  "data": [
    {
      "slug": "tile-placement",
      "name": "Tile placement",
      "games": 2
    }
  ],
  "total": 1,
  "nextCursor": null
}
curl "https://api.thebgdb.org/v1/mechanics"

Get one mechanic and its games

GET/mechanics/{slug}

The mechanic and the games linked to it, a page at a time, optionally filtered and ordered. total counts the games that pass the filters.

ParameterTypeMeaning
slug in the addressstringThe mechanic's slug, as returned by the API.
order optional"added" | "new" | "name" | "year" | "oldest" | "hot" | "rating" | "complexity" | "random"added oldest entry first, new newest entry first, name alphabetical, year most recent game first, oldest oldest game first (games with no known year are left out), hot highest hotness first (see GET /hot), rating highest weighted rating first, complexity heaviest first, random shuffled by seed. With rating and complexity, games nobody has rated or voted on come last. Without it: most recently added first.
seed optionalintegerWith order=random: any whole number. The same seed gives the same order, so pass it with every page to go through the list without seeing a game twice. Without it the order changes every hour. Other orders ignore it. min 0, max 2147483646
kind optional"game" | "expansion" | "accessory"Only entries of this type: game a stand-alone game, expansion one that needs another game, accessory something that is not played (sleeves, an insert, a playmat). Without it, all three are listed.
players optionalintegerOnly games that can be played by this many players. min 1, max 99
players_from optionalintegerWith players_to: only games that can be played at every count from players_from to players_to. Alone, the same as players. min 1, max 99
players_to optionalintegerUpper end of the range started by players_from. min 1, max 99
year_from optionalintegerOnly games published in this year or later.
year_to optionalintegerOnly games published in this year or earlier.
time_max optionalintegerOnly games that can be finished within this many minutes. min 1
age optionalintegerOnly games suitable for someone of this age. min 0, max 99
illustrated optional"1"Set to 1 for only games that have a cover image.
cover optional"ok" | "needs_work" | "unreviewed" | "none"Only games whose cover is in this state. ok: a good cover (imageAcceptable true). needs_work: a cover found not good (not the box front, a person in it, or imageQuality below 3), so a better one is wanted. unreviewed: a cover nothing has looked at yet. none: no cover at all. A cover that was not looked at is neither ok nor needs_work.
complexity_min optionalnumberOnly games whose average complexity is at least this. Games nobody has voted on are left out. min 1, max 5
complexity_max optionalnumberOnly games whose average complexity is at most this. Games nobody has voted on are left out. min 1, max 5
rating_min optionalnumberOnly games whose average rating is at least this. Games nobody has rated are left out. min 1, max 10
lang optionalstringA language code (BCP 47) such as "fr", "ja" or "pt-BR". A game that has a name in that language is returned with it as name, and its main name as originalName; a regional code falls back on its language ("fr-CA" on "fr"), a language with no name of its own takes a regional one ("pt" shows a name the game only has in "pt-BR"), and a game with no name in the language keeps its main name. Only names are localised: descriptions and summaries stay in English.
limit optionalinteger min 1, max 100, default 60
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectThe mechanic with its games.
404No mechanic has this slug.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataTermWithGames

For example:

{
  "data": {
    "slug": "tile-placement",
    "name": "Tile placement",
    "total": 1,
    "games": [
      {
        "id": "5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77",
        "slug": "catan",
        "name": "Catan",
        "originalName": null,
        "kind": "game",
        "yearPublished": 1995,
        "players": {
          "min": 3,
          "max": 4
        },
        "image": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=600",
        "thumbnail": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=200",
        "rating": {
          "average": 7.42,
          "count": 318,
          "weighted": 7.31
        },
        "complexity": {
          "average": 2.29,
          "votes": 121
        }
      }
    ],
    "nextCursor": null
  }
}

Awards

Awards, and the games each honoured, year by year: winners, nominees and other distinctions.

List awards

GET/awards

The awards in the catalog with the number of games linked to each, a page at a time.

ParameterTypeMeaning
order optional"name" | "games"name alphabetical, games most games first. default "name"
prefix optionalstringOnly names starting with this text. Case is ignored. at most 40 characters
limit optionalinteger min 1, max 500, default 100
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectA page of awards.
400cursor or order is not an accepted value.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of TermCount
totalintegerHow many match, across all pages.
nextCursorstring or null

For example:

{
  "data": [
    {
      "slug": "spiel-des-jahres",
      "name": "Spiel des Jahres",
      "games": 2
    }
  ],
  "total": 1,
  "nextCursor": null
}
curl "https://api.thebgdb.org/v1/awards"

Get one award and its games

GET/awards/{slug}

The award, the games it honoured a page at a time (optionally filtered and ordered; total counts the games that pass the filters), and its years: every year newest first, each with the games honoured that year by category and result. years holds the 500 most recent honours and does not follow the filters or the paging. A prize that used to be listed as an award of its own (kennerspiel-des-jahres) answers with a redirect to its award.

ParameterTypeMeaning
slug in the addressstringThe award's slug, as returned by the API.
order optional"added" | "new" | "name" | "year" | "oldest" | "hot" | "rating" | "complexity" | "random"added oldest entry first, new newest entry first, name alphabetical, year most recent game first, oldest oldest game first (games with no known year are left out), hot highest hotness first (see GET /hot), rating highest weighted rating first, complexity heaviest first, random shuffled by seed. With rating and complexity, games nobody has rated or voted on come last. Without it: most recently added first.
seed optionalintegerWith order=random: any whole number. The same seed gives the same order, so pass it with every page to go through the list without seeing a game twice. Without it the order changes every hour. Other orders ignore it. min 0, max 2147483646
kind optional"game" | "expansion" | "accessory"Only entries of this type: game a stand-alone game, expansion one that needs another game, accessory something that is not played (sleeves, an insert, a playmat). Without it, all three are listed.
players optionalintegerOnly games that can be played by this many players. min 1, max 99
players_from optionalintegerWith players_to: only games that can be played at every count from players_from to players_to. Alone, the same as players. min 1, max 99
players_to optionalintegerUpper end of the range started by players_from. min 1, max 99
year_from optionalintegerOnly games published in this year or later.
year_to optionalintegerOnly games published in this year or earlier.
time_max optionalintegerOnly games that can be finished within this many minutes. min 1
age optionalintegerOnly games suitable for someone of this age. min 0, max 99
illustrated optional"1"Set to 1 for only games that have a cover image.
cover optional"ok" | "needs_work" | "unreviewed" | "none"Only games whose cover is in this state. ok: a good cover (imageAcceptable true). needs_work: a cover found not good (not the box front, a person in it, or imageQuality below 3), so a better one is wanted. unreviewed: a cover nothing has looked at yet. none: no cover at all. A cover that was not looked at is neither ok nor needs_work.
complexity_min optionalnumberOnly games whose average complexity is at least this. Games nobody has voted on are left out. min 1, max 5
complexity_max optionalnumberOnly games whose average complexity is at most this. Games nobody has voted on are left out. min 1, max 5
rating_min optionalnumberOnly games whose average rating is at least this. Games nobody has rated are left out. min 1, max 10
lang optionalstringA language code (BCP 47) such as "fr", "ja" or "pt-BR". A game that has a name in that language is returned with it as name, and its main name as originalName; a regional code falls back on its language ("fr-CA" on "fr"), a language with no name of its own takes a regional one ("pt" shows a name the game only has in "pt-BR"), and a game with no name in the language keeps its main name. Only names are localised: descriptions and summaries stay in English.
limit optionalinteger min 1, max 100, default 60
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectThe award with its games.
301The slug is a prize that now belongs to an award: Location is that award's address.
404No award has this slug.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataAwardWithGames

For example:

{
  "data": {
    "slug": "spiel-des-jahres",
    "name": "Spiel des Jahres",
    "total": 1,
    "games": [
      {
        "id": "5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77",
        "slug": "catan",
        "name": "Catan",
        "originalName": null,
        "kind": "game",
        "yearPublished": 1995,
        "players": {
          "min": 3,
          "max": 4
        },
        "image": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=600",
        "thumbnail": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=200",
        "rating": {
          "average": 7.42,
          "count": 318,
          "weighted": 7.31
        },
        "complexity": {
          "average": 2.29,
          "votes": 121
        }
      }
    ],
    "nextCursor": null,
    "years": [
      {
        "year": 1995,
        "honours": [
          {
            "category": null,
            "result": "winner",
            "game": {
              "id": "5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77",
              "slug": "catan",
              "name": "Catan",
              "originalName": null,
              "yearPublished": 1995,
              "thumbnail": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=200"
            }
          }
        ]
      }
    ]
  }
}

Families

Series and franchises a game belongs to.

List families

GET/families

The families in the catalog with the number of games linked to each, a page at a time.

ParameterTypeMeaning
order optional"name" | "games"name alphabetical, games most games first. default "name"
prefix optionalstringOnly names starting with this text. Case is ignored. at most 40 characters
limit optionalinteger min 1, max 500, default 100
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectA page of families.
400cursor or order is not an accepted value.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of TermCount
totalintegerHow many match, across all pages.
nextCursorstring or null

For example:

{
  "data": [
    {
      "slug": "catan-series",
      "name": "Catan series",
      "games": 2
    }
  ],
  "total": 1,
  "nextCursor": null
}
curl "https://api.thebgdb.org/v1/families"

Get one family and its games

GET/families/{slug}

The family and the games linked to it, a page at a time, optionally filtered and ordered. total counts the games that pass the filters.

ParameterTypeMeaning
slug in the addressstringThe family's slug, as returned by the API.
order optional"added" | "new" | "name" | "year" | "oldest" | "hot" | "rating" | "complexity" | "random"added oldest entry first, new newest entry first, name alphabetical, year most recent game first, oldest oldest game first (games with no known year are left out), hot highest hotness first (see GET /hot), rating highest weighted rating first, complexity heaviest first, random shuffled by seed. With rating and complexity, games nobody has rated or voted on come last. Without it: most recently added first.
seed optionalintegerWith order=random: any whole number. The same seed gives the same order, so pass it with every page to go through the list without seeing a game twice. Without it the order changes every hour. Other orders ignore it. min 0, max 2147483646
kind optional"game" | "expansion" | "accessory"Only entries of this type: game a stand-alone game, expansion one that needs another game, accessory something that is not played (sleeves, an insert, a playmat). Without it, all three are listed.
players optionalintegerOnly games that can be played by this many players. min 1, max 99
players_from optionalintegerWith players_to: only games that can be played at every count from players_from to players_to. Alone, the same as players. min 1, max 99
players_to optionalintegerUpper end of the range started by players_from. min 1, max 99
year_from optionalintegerOnly games published in this year or later.
year_to optionalintegerOnly games published in this year or earlier.
time_max optionalintegerOnly games that can be finished within this many minutes. min 1
age optionalintegerOnly games suitable for someone of this age. min 0, max 99
illustrated optional"1"Set to 1 for only games that have a cover image.
cover optional"ok" | "needs_work" | "unreviewed" | "none"Only games whose cover is in this state. ok: a good cover (imageAcceptable true). needs_work: a cover found not good (not the box front, a person in it, or imageQuality below 3), so a better one is wanted. unreviewed: a cover nothing has looked at yet. none: no cover at all. A cover that was not looked at is neither ok nor needs_work.
complexity_min optionalnumberOnly games whose average complexity is at least this. Games nobody has voted on are left out. min 1, max 5
complexity_max optionalnumberOnly games whose average complexity is at most this. Games nobody has voted on are left out. min 1, max 5
rating_min optionalnumberOnly games whose average rating is at least this. Games nobody has rated are left out. min 1, max 10
lang optionalstringA language code (BCP 47) such as "fr", "ja" or "pt-BR". A game that has a name in that language is returned with it as name, and its main name as originalName; a regional code falls back on its language ("fr-CA" on "fr"), a language with no name of its own takes a regional one ("pt" shows a name the game only has in "pt-BR"), and a game with no name in the language keeps its main name. Only names are localised: descriptions and summaries stay in English.
limit optionalinteger min 1, max 100, default 60
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectThe family with its games.
404No family has this slug.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataTermWithGames

For example:

{
  "data": {
    "slug": "catan-series",
    "name": "Catan series",
    "total": 1,
    "games": [
      {
        "id": "5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77",
        "slug": "catan",
        "name": "Catan",
        "originalName": null,
        "kind": "game",
        "yearPublished": 1995,
        "players": {
          "min": 3,
          "max": 4
        },
        "image": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=600",
        "thumbnail": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=200",
        "rating": {
          "average": 7.42,
          "count": 318,
          "weighted": 7.31
        },
        "complexity": {
          "average": 2.29,
          "votes": 121
        }
      }
    ],
    "nextCursor": null
  }
}

Ratings and polls

Members rate games and vote on their complexity, age, player counts and language dependence. The results are fields of the game.

Rate a game

PUT/games/{id}/ratingNeeds a session

A rating from 1 to 10, with at most one decimal. One rating per member; rating again replaces it. The member's email address must be confirmed. The game's rating changes at once; ranks follow within the hour.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Send (application/json)

FieldTypeMeaning
ratingnumber min 1, max 10

Answers

200objectThe rating was stored.
400rating is not a number from 1 to 10 with at most one decimal.
401The request has no valid session token.
403The member has not confirmed their email address.
404No game has this id.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataobject
data.ratingnumber

For example:

{
  "data": {
    "rating": 7.5
  }
}

Remove your rating of a game

DELETE/games/{id}/ratingNeeds a session

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Answers

200OkThe member has no rating on this game.
401The request has no valid session token.
404No game has this id.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

A Ok:

FieldTypeMeaning
oktrue

For example:

{
  "ok": true
}

Vote on a game's complexity

PUT/games/{id}/complexityNeeds a session

How hard the game is to learn and play: 1 light, 2 medium light, 3 medium, 4 medium heavy, 5 heavy. One vote per member; voting again replaces it. The result is complexity on the game.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Send (application/json)

FieldTypeMeaning
weightinteger min 1, max 5

Answers

200OkThe vote was counted.
400weight is not a whole number from 1 to 5.
401The request has no valid session token.
404No game has this id.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

A Ok:

FieldTypeMeaning
oktrue

For example:

{
  "ok": true
}

Take back your vote on a game's complexity

DELETE/games/{id}/complexityNeeds a session

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Answers

200OkThe member has no vote on this.
401The request has no valid session token.
404No game has this id.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

A Ok:

FieldTypeMeaning
oktrue

For example:

{
  "ok": true
}

Vote on a game's language dependence

PUT/games/{id}/polls/languageNeeds a session

How much the game depends on reading its language: 1 no text needed in play, 2 a little text, easy to memorise or explain, 3 a moderate amount, needs a reference sheet or stickers, 4 a lot of text, 5 unplayable in another language. One vote per member; voting again replaces it. The result is languageDependence on the game.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Send (application/json)

FieldTypeMeaning
levelinteger min 1, max 5

Answers

200OkThe vote was counted.
400level is not a whole number from 1 to 5.
401The request has no valid session token.
404No game has this id.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

A Ok:

FieldTypeMeaning
oktrue

For example:

{
  "ok": true
}

Take back your vote on a game's language dependence

DELETE/games/{id}/polls/languageNeeds a session

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Answers

200OkThe member has no vote on this.
401The request has no valid session token.
404No game has this id.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

A Ok:

FieldTypeMeaning
oktrue

For example:

{
  "ok": true
}

Vote on how many players a game is good with

PUT/games/{id}/polls/playersNeeds a session

One ballot per member: for each number of players the member has an opinion on, whether the game is best, recommended or not_recommended with that many. Sending a ballot replaces the member's previous one entirely. The results are playerCounts, bestWith and recommendedWith on the game.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Send (application/json)

FieldTypeMeaning
votesarray of objectEach number of players at most once.
votes[].playersinteger min 1, max 20
votes[].vote"best" | "recommended" | "not_recommended"

Answers

200OkThe ballot was counted.
400The ballot is empty, repeats a number of players, or has a value out of range.
401The request has no valid session token.
404No game has this id.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

A Ok:

FieldTypeMeaning
oktrue

For example:

{
  "ok": true
}

Take back your ballot on player counts

DELETE/games/{id}/polls/playersNeeds a session

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Answers

200OkThe member has no ballot on this game.
401The request has no valid session token.
404No game has this id.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

A Ok:

FieldTypeMeaning
oktrue

For example:

{
  "ok": true
}

List your ratings

GET/account/ratingsNeeds a session

The games the member has rated, with the rating and when it was last given. Never served from the shared cache.

ParameterTypeMeaning
order optional"recent" | "rating"recent: the latest rating first. rating: the highest rating first. default "recent"
limit optionalinteger min 1, max 100, default 50
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectA page of the member's ratings.
400order or cursor is not an accepted value.
401The request has no valid session token.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of object
data[].gameGameSummary
data[].ratingnumberThe member's rating, out of 10. min 1, max 10
data[].ratedAtstring (date-time)When the rating was last given.
totalintegerHow many games the member has rated.
nextCursorstring or nullPass as cursor to get the next page. Null on the last page.

For example:

{
  "data": [
    {
      "game": {
        "id": "5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77",
        "slug": "catan",
        "name": "Catan",
        "originalName": null,
        "kind": "game",
        "yearPublished": 1995,
        "players": {
          "min": 3,
          "max": 4
        },
        "image": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=600",
        "thumbnail": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=200",
        "rating": {
          "average": 7.42,
          "count": 318,
          "weighted": 7.31
        },
        "complexity": {
          "average": 2.29,
          "votes": 121
        }
      },
      "rating": 7.5,
      "ratedAt": "2026-11-20T18:04:11.120Z"
    }
  ],
  "total": 1,
  "nextCursor": null
}
curl "https://api.thebgdb.org/v1/account/ratings"

Collections

The games a member owns, wants or trades.

Put a game in your collection

PUT/games/{id}/collectionNeeds a session

Marks the game with one or more statuses. The list sent replaces the game's previous statuses.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Send (application/json)

FieldTypeMeaning
statusesarray of CollectionStatus

Answers

200objectThe statuses now on the game.
400statuses is empty or names a status other than owned and wishlist (code invalid_collection_status).
401The request has no valid session token.
404No game has this id.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataobject
data.statusesarray of CollectionStatus

For example:

{
  "data": {
    "statuses": [
      "owned",
      "wishlist"
    ]
  }
}

Take a game out of your collection

DELETE/games/{id}/collectionNeeds a session

Removes every status the member put on the game.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Answers

200OkThe game is not in the member's collection.
401The request has no valid session token.
404No game has this id.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

A Ok:

FieldTypeMeaning
oktrue

For example:

{
  "ok": true
}

List your collection

GET/account/collectionNeeds a session

The games the member has marked, most recently added first, each with its statuses and the member's own rating. Never served from the shared cache.

ParameterTypeMeaning
status optionalCollectionStatusOnly games carrying this status.
limit optionalinteger min 1, max 100, default 50
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectA page of the member's collection.
400status or cursor is not an accepted value.
401The request has no valid session token.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of CollectionItem
totalintegerHow many games match, across all pages.
nextCursorstring or nullPass as cursor to get the next page. Null on the last page.

For example:

{
  "data": [
    {
      "game": {
        "id": "5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77",
        "slug": "catan",
        "name": "Catan",
        "originalName": null,
        "kind": "game",
        "yearPublished": 1995,
        "players": {
          "min": 3,
          "max": 4
        },
        "image": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=600",
        "thumbnail": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=200",
        "rating": {
          "average": 7.42,
          "count": 318,
          "weighted": 7.31
        },
        "complexity": {
          "average": 2.29,
          "votes": 121
        }
      },
      "statuses": [
        "owned",
        "wishlist"
      ],
      "rating": 7.5,
      "addedAt": "2026-11-20T18:04:11.120Z"
    }
  ],
  "total": 1,
  "nextCursor": null
}
curl "https://api.thebgdb.org/v1/account/collection"

Plays

A member's log of games played.

Log a play of a game

POST/games/{id}/playsNeeds a session

Records that the member played the game on a day. The game's plays count follows at once.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Send (application/json)

FieldTypeMeaning
datestring (date)The day it was played. Not in the future.
players optionalinteger min 1, max 99
minutes optionalintegerHow long the play lasted. min 1, max 10000
note optionalstringPlain text. Visible to the member only. at most 500 characters

Answers

201objectThe play was logged.
400The date is missing, malformed or in the future, or another value is out of range.
401The request has no valid session token.
404No game has this id.
429More than 300 requests in a minute from this address. Wait a minute.

What a 201 holds

FieldTypeMeaning
dataobject
data.idstring (uuid)
data.datestring (date)
data.playersinteger or null
data.minutesinteger or null
data.notestring or null

For example:

{
  "data": {
    "id": "7d0a2b1e-1f8e-4d55-9a53-0e5d0f5f7c21",
    "date": "2026-11-20",
    "players": 4,
    "minutes": 75,
    "note": "Longest road won it."
  }
}

List your plays

GET/account/playsNeeds a session

The member's logged plays, most recent day first. Never served from the shared cache.

ParameterTypeMeaning
limit optionalinteger min 1, max 100, default 50
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectA page of the member's plays.
400cursor is not a value this API issued.
401The request has no valid session token.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of Play
totalinteger
nextCursorstring or nullPass as cursor to get the next page. Null on the last page.

For example:

{
  "data": [
    {
      "id": "7d0a2b1e-1f8e-4d55-9a53-0e5d0f5f7c21",
      "game": {
        "id": "5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77",
        "slug": "catan",
        "name": "Catan",
        "originalName": null,
        "kind": "game",
        "yearPublished": 1995,
        "players": {
          "min": 3,
          "max": 4
        },
        "image": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=600",
        "thumbnail": "https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=200",
        "rating": {
          "average": 7.42,
          "count": 318,
          "weighted": 7.31
        },
        "complexity": {
          "average": 2.29,
          "votes": 121
        }
      },
      "date": "2026-11-20",
      "players": 4,
      "minutes": 75,
      "note": "Longest road won it.",
      "createdAt": "2026-11-20T22:10:03.512Z"
    }
  ],
  "total": 1,
  "nextCursor": null
}
curl "https://api.thebgdb.org/v1/account/plays"

Delete one of your plays

DELETE/account/plays/{id}Needs a session

ParameterTypeMeaning
id in the addressstring (uuid)

Answers

200OkThe play is not in the member's log.
401The request has no valid session token.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

A Ok:

FieldTypeMeaning
oktrue

For example:

{
  "ok": true
}

Comments

What members write about a game.

List a game's comments

GET/games/{id}/comments

What members wrote about the game, newest first, each with its author's rating of the game when they gave one. text is plain text exactly as written: escape it before putting it in a page.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.
limit optionalinteger min 1, max 100, default 20
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectA page of comments.
400cursor is not a value this API issued.
404No game has this id.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of Comment
totalinteger
nextCursorstring or nullPass as cursor to get the next page. Null on the last page.

For example:

{
  "data": [
    {
      "id": "4a0e7f0c-64d0-4f0e-8a51-6f4b1b2f9d10",
      "author": "Ana",
      "text": "Trade wood for sheep.",
      "rating": 7.5,
      "createdAt": "2026-11-20T18:04:11.120Z",
      "updatedAt": "2026-11-20T18:04:11.120Z"
    }
  ],
  "total": 1,
  "nextCursor": null
}

Write or edit your comment on a game

PUT/games/{id}/commentNeeds a session

One comment per member and game, of at most 2 000 characters; sending again edits it. Plain text: line breaks are kept, control characters are removed, and markup is stored as the characters typed, never interpreted. The member's email address must be confirmed. A member can send five comments or videos a minute. A comment removed by a moderator cannot be replaced.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Send (application/json)

FieldTypeMeaning
textstring at least 1 characters, at most 2000 characters

Answers

200objectThe comment as stored.
400The text is empty or longer than 2 000 characters.
401The request has no valid session token.
403The member has not confirmed their email address, or a moderator removed their comment on this game.
404No game has this id.
429Rate limited, or more than five posts in a minute.

What a 200 holds

FieldTypeMeaning
dataobject
data.idstring (uuid)
data.textstring
data.createdAtstring (date-time)
data.updatedAtstring (date-time)

For example:

{
  "data": {
    "id": "4a0e7f0c-64d0-4f0e-8a51-6f4b1b2f9d10",
    "text": "Trade wood for sheep.",
    "createdAt": "2026-11-20T18:04:11.120Z",
    "updatedAt": "2026-11-20T18:04:11.120Z"
  }
}

Delete your comment on a game

DELETE/games/{id}/commentNeeds a session

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Answers

200OkThe member has no visible comment on this game.
401The request has no valid session token.
404No game has this id.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

A Ok:

FieldTypeMeaning
oktrue

For example:

{
  "ok": true
}

Videos

Videos about a game, on other sites.

List a game's videos

GET/games/{id}/videos

Videos about the game that a moderator has approved, newest first.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.
category optionalVideoCategoryOnly videos of this kind.
limit optionalinteger min 1, max 100, default 50
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectA page of videos.
400category or cursor is not an accepted value.
404No game has this id.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of Video
nextCursorstring or nullPass as cursor to get the next page. Null on the last page.

For example:

{
  "data": [
    {
      "id": "0b0f5a51-64a5-4f6b-9a39-0a4d6c5c0f11",
      "provider": "youtube",
      "videoId": "dQw4w9WgXcQ",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "title": "How to play Catan",
      "language": "en",
      "category": "how_to_play",
      "submittedBy": "Ana",
      "createdAt": "2026-11-20T18:04:11.120Z"
    }
  ],
  "nextCursor": null
}

Suggest a video for a game

POST/games/{id}/videosNeeds a session

Send the address of a video on YouTube or Vimeo; no other site is accepted. Only the provider and the video's id are kept, and url is rebuilt from them. The video is listed once a moderator has approved it. The member's email address must be confirmed. A member can send five comments or videos a minute and 20 videos a day.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Send (application/json)

FieldTypeMeaning
urlstring (uri)A YouTube or Vimeo video page.
titlestring at least 2 characters, at most 120 characters
languagestringThe language spoken, as a code such as "en" or "pt-BR".
categoryVideoCategory

Answers

201objectThe video was stored and waits for review.
400The address is not a YouTube or Vimeo video, or the title, language or category is not valid.
401The request has no valid session token.
403The member has not confirmed their email address.
404No game has this id.
409This video was already sent in for this game.
429Rate limited, more than five posts in a minute, or 20 videos already sent today.

What a 201 holds

FieldTypeMeaning
dataobject
data.idstring (uuid)
data.provider"youtube" | "vimeo"
data.videoIdstring
data.urlstring (uri)
data.titlestring
data.languagestring
data.categoryVideoCategory
data.status"pending" | "approved"

For example:

{
  "data": {
    "id": "0b0f5a51-64a5-4f6b-9a39-0a4d6c5c0f11",
    "provider": "youtube",
    "videoId": "dQw4w9WgXcQ",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "title": "How to play Catan",
    "language": "en",
    "category": "how_to_play",
    "status": "pending"
  }
}

Music

Playlists to play a game to, on Apple Music, Spotify and YouTube, rated by members.

List music to play a game to

GET/games/{id}/playlists

Playlists and albums on Apple Music, Spotify and YouTube that members suggest as a soundtrack for the game. Best score first (votes up minus votes down), then newest. A playlist members voted down to a score of −3 or lower, with at least 5 votes, is left out. The list is the same for everyone; a member's own votes are in GET /account/games/{id}.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.
provider optionalMusicProviderOnly playlists on this service.
limit optionalinteger min 1, max 100, default 50
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectA page of playlists.
400provider or cursor is not an accepted value.
404No game has this id.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of Playlist
nextCursorstring or nullPass as cursor to get the next page. Null on the last page.

For example:

{
  "data": [
    {
      "id": "7d1c1a0e-2f0b-4d39-9a56-5a8d2b9d7c21",
      "provider": "spotify",
      "kind": "playlist",
      "title": "Island traders: calm medieval folk",
      "url": "https://open.spotify.com/playlist/37i9dQZF1DX4sWSpwq3LiO",
      "score": 4,
      "votes": 6,
      "submittedBy": "Ana",
      "createdAt": "2026-11-20T18:04:11.120Z"
    }
  ],
  "nextCursor": null
}

Add a playlist to a game

POST/games/{id}/playlistsNeeds a session

Send the address of a playlist or an album on Apple Music (music.apple.com), Spotify (open.spotify.com) or YouTube and YouTube Music (youtube.com/playlist?list=…); no other site is accepted, and neither are single tracks, mixes or personal lists such as "liked". Only the service, the kind and the playlist's id there are kept, and url is rebuilt from them. The title is the playlist's own, read from the service; title is only used when the service does not give one (a private playlist, or the service not answering), so it can be left out. The playlist is listed at once. A given playlist can be listed once per game. The member's email address must be confirmed. A member can send five posts a minute and 20 playlists a day.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Send (application/json)

FieldTypeMeaning
urlstring (uri)A playlist or album page on Apple Music, Spotify or YouTube.
title optionalstringA title to fall back on when the service does not give the playlist's own. at least 2 characters, at most 120 characters

Answers

201objectThe playlist is listed.
400The address is not a playlist or album on one of the three services, the title is longer than 120 characters, or the service gave no title and none of 2 to 120 characters was sent.
401The request has no valid session token.
403The member has not confirmed their email address.
404No game has this id.
409This playlist is already listed for this game, or was and is no longer shown.
429Rate limited, more than five posts in a minute, or 20 playlists already added today.

What a 201 holds

FieldTypeMeaning
dataPlaylist

For example:

{
  "data": {
    "id": "7d1c1a0e-2f0b-4d39-9a56-5a8d2b9d7c21",
    "provider": "spotify",
    "kind": "playlist",
    "title": "Island traders: calm medieval folk",
    "url": "https://open.spotify.com/playlist/37i9dQZF1DX4sWSpwq3LiO",
    "score": 0,
    "votes": 0,
    "submittedBy": "Ana",
    "createdAt": "2026-11-20T18:04:11.120Z"
  }
}

Vote a playlist up or down

PUT/games/{id}/playlists/{playlist}/voteNeeds a session

One vote per member and playlist; voting again replaces it. The playlist's score moves at once. A vote that brings the score to −3 or lower, once at least 5 members have voted, hides the playlist (status becomes hidden): it leaves the list and can no longer be voted on.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.
playlist in the addressstring (uuid)The playlist's id.

Send (application/json)

FieldTypeMeaning
vote"up" | "down"

Answers

200objectThe playlist's standing after the vote.
400vote is not "up" or "down".
401The request has no valid session token.
404No game has this id, or it lists no such playlist.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataPlaylistStanding

For example:

{
  "data": {
    "score": 5,
    "votes": 7,
    "status": "visible"
  }
}

Take back your vote on a playlist

DELETE/games/{id}/playlists/{playlist}/voteNeeds a session

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.
playlist in the addressstring (uuid)The playlist's id.

Answers

200objectThe playlist's standing with the member's vote taken out.
401The request has no valid session token.
404No game has this id, or it lists no such playlist.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataPlaylistStanding

For example:

{
  "data": {
    "score": 4,
    "votes": 6,
    "status": "visible"
  }
}

Rules

Rulebooks uploaded by members, each tagged with its language.

List a game's rulebooks

GET/games/{id}/rulebooks

The rulebooks members uploaded for the game and a moderator approved, by language then newest first. A rulebook is one PDF, or the pages as images in reading order. Each file's path is served by GET /media/{key}.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.
language optionalstringOnly rulebooks written in this language.
limit optionalinteger min 1, max 100, default 50
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectA page of rulebooks.
400language or cursor is not an accepted value.
404No game has this id.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of Rulebook
nextCursorstring or nullPass as cursor to get the next page. Null on the last page.

For example:

{
  "data": [
    {
      "id": "c2b7e5a4-3f1d-4b7c-8f0a-9e6d5c4b3a21",
      "language": "en",
      "edition": "5th edition, 2015",
      "kind": "pdf",
      "pages": null,
      "size": 4812330,
      "uploadedBy": "Ana",
      "createdAt": "2026-11-20T18:04:11.120Z",
      "files": [
        {
          "path": "/v1/media/rulebooks/5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77/c2b7e5a4-3f1d-4b7c-8f0a-9e6d5c4b3a21/1.pdf",
          "contentType": "application/pdf",
          "size": 4812330,
          "kind": null
        }
      ]
    }
  ],
  "nextCursor": null
}

Upload a rulebook for a game

POST/games/{id}/rulebooksNeeds a session

Send one PDF, or up to 20 JPEG, PNG or WebP images of the pages in reading order, as repeated file fields. All files together may weigh 25 MB at most, and each image 5 MB; a PDF of up to 200 MB is sent in parts instead, starting with POST /games/{id}/rulebooks/uploads. The type is checked from each file's content, not its name. language says which language the rules are written in. The member's email address must be confirmed. A member can upload 10 rulebooks a day. A rulebook is shown to others once a moderator has approved it; until then only its uploader can list it (GET /account/games/{id}) and download its files.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Send (multipart/form-data)

FieldTypeMeaning
filearray of string (binary)One PDF, or 1 to 20 images.
languagestringA language code such as "en", "fr" or "pt-BR".
edition optionalstringWhich edition or printing these rules belong to. Optional. at most 120 characters

Answers

201objectThe rulebook was stored and waits for review.
400No file was sent, a PDF was sent with other files, there are more than 20 images, or the language or edition is not valid.
401The request has no valid session token.
403The member has not confirmed their email address.
404No game has this id.
413The files weigh more than 25 MB together, or an image more than 5 MB.
415A file is not a PDF, JPEG, PNG or WebP.
429Rate limited, or the member already uploaded 10 rulebooks today.

What a 201 holds

FieldTypeMeaning
dataOwnRulebook + object

For example:

{
  "data": {
    "id": "c2b7e5a4-3f1d-4b7c-8f0a-9e6d5c4b3a21",
    "language": "en",
    "edition": "5th edition, 2015",
    "kind": "pdf",
    "pages": null,
    "size": 4812330,
    "files": [
      {
        "path": "/v1/media/rulebooks/5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77/c2b7e5a4-3f1d-4b7c-8f0a-9e6d5c4b3a21/1.pdf",
        "contentType": "application/pdf",
        "size": 4812330,
        "kind": null
      }
    ],
    "status": "pending"
  }
}

Start sending a large PDF rulebook in parts

POST/games/{id}/rulebooks/uploadsNeeds a session

For a PDF too heavy for POST /games/{id}/rulebooks: up to 200 MB. Say how many bytes the file has; the answer tells how to cut it (partSize bytes a part, the last one shorter, parts in all) and gives a token. Send each part with PUT /rulebook-uploads/{upload}/parts/{part}, then POST /rulebook-uploads/{upload}/complete; those calls carry the token in the x-upload-token header and nothing else. The token opens this one upload, for two hours. The member's email address must be confirmed. A member can start five uploads a minute, have three under way at once, and add 10 rulebooks a day, uploads under way included. An upload neither completed nor cancelled is discarded after a day.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Send (application/json)

FieldTypeMeaning
sizeintegerBytes of the whole file. min 1, max 209715200
languagestringA language code such as "en", "fr" or "pt-BR".
edition optionalstringWhich edition or printing these rules belong to. Optional. at most 120 characters

Answers

201objectThe upload is open.
400The size, the language or the edition is not valid.
401The request has no valid session token.
403The member has not confirmed their email address.
404No game has this id.
413The file is larger than 200 MB.
429Rate limited, more than five starts in a minute, three uploads already under way, or 10 rulebooks already added today.

What a 201 holds

FieldTypeMeaning
dataRulebookUpload

For example:

{
  "data": {
    "id": "c2b7e5a4-3f1d-4b7c-8f0a-9e6d5c4b3a21",
    "token": "9f2c61f0a4b84d7e9c3a5b1d7e2f4a6c8b0d2e4f6a8c0e2f4a6b8d0c2e4f6a81",
    "partSize": 8388608,
    "parts": 8,
    "expiresAt": "2026-11-21T20:04:11.120Z"
  }
}

Send one part of a large rulebook

PUT/rulebook-uploads/{upload}/parts/{part}

The request body is the part's bytes, nothing around them, with their exact content-length: partSize for every part but the last, the remainder for the last. Parts can be sent in any order, and a part that failed can be sent again. The first part must begin as a PDF does (%PDF-): if it does not, the whole upload is discarded. Browsers are answered only on the website's own pages.

ParameterTypeMeaning
upload in the addressstring (uuid)The upload's id, from POST /games/{id}/rulebooks/uploads.
part in the addressintegerThe part's number, from 1 to parts. min 1, max 25

Send (application/octet-stream)

Answers

200objectThe part is stored.
400The part number is not a number, the body is shorter than the part should be, or it did not arrive whole.
401The x-upload-token header is missing, or the token has expired.
403The member has not confirmed their email address.
404No upload has this id and token: it was completed, cancelled or discarded, or the token is another upload's.
413The body is longer than this part should be, or the upload has fewer parts.
415The first part is not the start of a PDF.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataobject
data.partinteger

For example:

{
  "data": {
    "part": 3
  }
}

Finish a large rulebook once its parts are sent

POST/rulebook-uploads/{upload}/complete

Puts the parts together. The file becomes a rulebook that waits for review, exactly as one sent with POST /games/{id}/rulebooks, under the same id as the upload. Its pages is null at first: the pages are counted from the stored file within the hour, usually within seconds.

ParameterTypeMeaning
upload in the addressstring (uuid)The upload's id, from POST /games/{id}/rulebooks/uploads.

Answers

201objectThe rulebook was stored and waits for review.
400The parts do not add up to the size announced. The upload is discarded.
401The x-upload-token header is missing, or the token has expired.
403The member has not confirmed their email address.
404No upload has this id and token: it was completed, cancelled or discarded, or the token is another upload's.
409Some parts have not arrived (missing lists their numbers), or the parts could not be put together.
429More than 300 requests in a minute from this address. Wait a minute.

What a 201 holds

FieldTypeMeaning
dataOwnRulebook + object

For example:

{
  "data": {
    "id": "c2b7e5a4-3f1d-4b7c-8f0a-9e6d5c4b3a21",
    "language": "en",
    "edition": "5th edition, 2015",
    "kind": "pdf",
    "pages": null,
    "size": 4812330,
    "files": [
      {
        "path": "/v1/media/rulebooks/5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77/c2b7e5a4-3f1d-4b7c-8f0a-9e6d5c4b3a21/1.pdf",
        "contentType": "application/pdf",
        "size": 4812330,
        "kind": null
      }
    ],
    "status": "pending"
  }
}

Cancel a large rulebook upload

DELETE/rulebook-uploads/{upload}

Discards the upload and the parts already sent. The token stops working.

ParameterTypeMeaning
upload in the addressstring (uuid)The upload's id, from POST /games/{id}/rulebooks/uploads.

Answers

200objectThe upload is discarded.
401The x-upload-token header is missing, or the token has expired.
403The member has not confirmed their email address.
404No upload has this id and token: it was completed, cancelled or discarded, or the token is another upload's.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
ok optionalboolean

For example:

{
  "ok": true
}

Photos

Photos added by members.

List a game's photos

GET/games/{id}/photos

The photos members added to the game and a moderator approved, oldest first, each with what it shows (kind). A member signed in also sees their own photos waiting for review. The game's cover from its source is not a photo: it is image on the game, with imageKind.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.
kind optional"box_front" | "board_traditional" | "box_partial" | "logo" | "components" | "in_play" | "people" | "other" | "box_back" | "setup" | "cards" | "rulebook"Only photos that show this. box_front the whole front of the box; box_back its back; box_partial the box at an angle, cropped, or an overall shot of it; board_traditional the board of a traditional game that never had a box (chess, go); setup the game laid out ready to play; in_play a game in progress, nobody visible; components the pieces, boards and tokens; cards cards; people people playing, or any person, face or hand in the picture; rulebook a page of the rules; logo a title or logo alone; other anything else. New words may be added; treat an unknown one as other.
limit optionalinteger min 1, max 100, default 50
cursor optionalstringThe nextCursor of the previous page.

Answers

200objectA page of photos.
400kind is not one of the words listed (invalid_photo_kind), or cursor is not an accepted value.
404No game has this id.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of Photo
nextCursorstring or nullPass as cursor to get the next page. Null on the last page.

Add a photo to a game

POST/games/{id}/imagesNeeds a session

Upload one JPEG, PNG or WebP file of at most 5 MB, say what it shows (kind), and optionally say which language the edition it shows is in. A vision model also looks at the photo; its opinion is kept apart and shown to moderators, who may correct kind. The member's email address must be confirmed. The type is checked from the file's content, not its name. A member can add 20 photos a day. A photo is shown to others once a moderator has approved it; the game's oldest approved photo is used as its cover. A member verified as representing one of the game's publishers may send official = true: once approved, that photo is the cover ahead of the others.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Send (multipart/form-data)

FieldTypeMeaning
filestring (binary)
kind"box_front" | "board_traditional" | "box_partial" | "logo" | "components" | "in_play" | "people" | "other" | "box_back" | "setup" | "cards" | "rulebook"What the photo shows. box_front the whole front of the box; box_back its back; box_partial the box at an angle, cropped, or an overall shot of it; board_traditional the board of a traditional game that never had a box (chess, go); setup the game laid out ready to play; in_play a game in progress, nobody visible; components the pieces, boards and tokens; cards cards; people people playing, or any person, face or hand in the picture; rulebook a page of the rules; logo a title or logo alone; other anything else. New words may be added; treat an unknown one as other.
official optional"true"The game's official cover. Only from a verified representative of one of its publishers.
language optionalstringThe language of the edition the photo shows, as a code such as "en" or "pt-BR". Optional.

Answers

201objectThe photo was stored.
400No file was sent (photo_missing), kind is missing (photo_kind_missing) or not one of the words listed (invalid_photo_kind), or the language is not a language code (invalid_language).
401The request has no valid session token.
403The member has not confirmed their email address, or sent official without being a verified representative of one of the game's publishers.
404No game has this id.
413The file is larger than 5 MB.
415The file is not a JPEG, PNG or WebP image.
429Rate limited, or the member already added 20 photos today.

What a 201 holds

FieldTypeMeaning
dataobject
data.idstring (uuid)
data.pathstringPath of the file on this API.
data.kind"box_front" | "board_traditional" | "box_partial" | "logo" | "components" | "in_play" | "people" | "other" | "box_back" | "setup" | "cards" | "rulebook"What the photo shows, as sent.
data.languagestring or nullThe language of the edition shown, when it was said.

Download an uploaded photo or rulebook file

GET/media/{key}Session optional

Serves the file behind a photo's or a rulebook file's path. Photos never change, so they are cached for a year; rulebook files for an hour. A rulebook file is sent with a content-disposition that names it and lets a browser show it in place. The file of a rulebook that waits for review is served only to its uploader and to moderators, who must send their session; to anyone else it does not exist.

ParameterTypeMeaning
key in the addressstringThe rest of a path after /v1/media/. It contains slashes.

Answers

200string (binary)The file.
404No file has this key, or it waits for review and is not yours.

Corrections

Members propose corrections to a game's facts; a moderator accepts or rejects them. Accepted corrections are listed in the game's history.

Suggest a correction to a game

POST/games/{id}/correctionsNeeds a session

One proposal holds 1 to 20 changes to one game: a fact, a credit to add or remove, an alternate name. Nothing changes until a moderator accepts it; an accepted correction is kept against later imports and credited in the game's history. The member's email address must be confirmed. A member can suggest 20 corrections a day. A member verified as representing one of the game's publishers has their correction marked as coming from the publisher; it is reviewed like any other.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too.

Send (application/json)

FieldTypeMeaning
changesarray of object or object or object
textDeclared optionalbooleanMust be true when a description is proposed: you wrote the text, or it is free to reuse.

Answers

201objectThe correction waits for a moderator.
400A change is not valid; the message says which and why.
401The request has no valid session token.
403The member has not confirmed their email address.
404No game has this id.
409The game no longer says what old states, or already is as proposed.
429Rate limited, or the member already suggested 20 corrections today.

What a 201 holds

FieldTypeMeaning
dataobject
data.idstring (uuid)
data.status"pending"
data.fromPublisherstring or nullThe publisher the member verifiably represents, when the game is credited to it.
data.changesarray of object or object or object

List the accepted corrections of a game

GET/games/{id}/history

Who corrected what, newest first: the member's display name, the date and the facts changed. Corrections a moderator took back are left out. At most 100.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too.

Answers

200objectThe game's accepted corrections.
404No game has this id.

What a 200 holds

FieldTypeMeaning
dataarray of object
data[].idstring (uuid)
data[].datestring (date-time)
data[].contributorstringDisplay name of the member.
data[].fromPublisherbooleanThe member was verified as representing one of the game's publishers.
data[].changesarray of object

For example:

{
  "data": [
    {
      "id": "0c8a6e0e-1a53-4c55-9f43-0f1f2a3b4c5d",
      "date": "2026-11-21T09:12:44.031Z",
      "contributor": "Ana",
      "fromPublisher": false,
      "changes": [
        {
          "field": "yearPublished",
          "action": "changed",
          "value": null
        }
      ]
    }
  ]
}

List your corrections

GET/account/correctionsNeeds a session

The corrections the member suggested, newest first, each with its status and, when rejected, the moderator's reason. Once decided, each change says whether it was accepted or declined. Never served from the shared cache.

ParameterTypeMeaning
limit optionalinteger min 1, max 100, default 50
cursor optionalstringnextCursor of the previous page.

Answers

200objectA page of the member's corrections.
400cursor is not an accepted value.
401The request has no valid session token.

What a 200 holds

FieldTypeMeaning
dataarray of object
data[].idstring (uuid)
data[].status"pending" | "accepted" | "rejected"
data[].reasonstring or nullWhy it was rejected.
data[].createdAtstring (date-time)
data[].reviewedAtstring or null (date-time)
data[].undonebooleanAccepted, then taken back by a moderator.
data[].gameobject
data[].changesarray of object or object or object + object
nextCursorstring or nullPass as cursor for the next page.
curl "https://api.thebgdb.org/v1/account/corrections"

List the publishers you asked to represent

GET/account/publisher-claimsNeeds a session

The member's requests to be recognised as representing a publisher, with their status.

Answers

200objectThe member's requests, newest first.
401The request has no valid session token.

What a 200 holds

FieldTypeMeaning
dataarray of object
data[].idstring (uuid)
data[].status"pending" | "verified" | "rejected"
data[].emailDomainstring
data[].notestring or null
data[].createdAt optionalstring (date-time)
data[].verifiedAt optionalstring or null (date-time)
data[].publisherobject
curl "https://api.thebgdb.org/v1/account/publisher-claims"

Say you represent a publisher

POST/account/publisher-claimsNeeds a session

A moderator checks the request by hand. Once verified, the member's corrections to that publisher's games are marked as coming from the publisher, and the member may send a game's official cover (official on POST /games/{id}/images). The member's email address must be confirmed.

Send (application/json)

FieldTypeMeaning
publisherstringThe publisher's slug.
emailDomainstringThe company's email domain.
note optionalstring at most 500 characters

Answers

201objectThe request waits for a moderator.
400The publisher, the domain or the note is not valid.
401The request has no valid session token.
403The member has not confirmed their email address.
409The member already sent a request for this publisher.
429Rate limited, or five requests are already waiting.

What a 201 holds

FieldTypeMeaning
dataobject
data.idstring (uuid)
data.status"pending" | "verified" | "rejected"
data.emailDomainstring
data.notestring or null
data.createdAt optionalstring (date-time)
data.verifiedAt optionalstring or null (date-time)
data.publisherobject

Lists

Lists of games made by members.

List the lists

GET/listsSession optional

The 100 most recent lists. With mine=1 and a session, only the member's own.

ParameterTypeMeaning
mine optional"1"Set to 1 to get only your own lists. Needs a session.

Answers

200objectThe lists, newest first.
401The request has no valid session token.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of ListSummary
curl "https://api.thebgdb.org/v1/lists"

Make a list

POST/listsNeeds a session

Send (application/json)

FieldTypeMeaning
namestring at least 2 characters, at most 80 characters
description optionalstring at most 500 characters

Answers

201objectThe list was created.
400The name or description is too short or too long.
401The request has no valid session token.
429More than 300 requests in a minute from this address. Wait a minute.

What a 201 holds

FieldTypeMeaning
dataobject
data.idstring (uuid)
data.namestring

Get one list and its games

GET/lists/{id}Session optional

ParameterTypeMeaning
id in the addressstring (uuid)
lang optionalstringA language code (BCP 47) such as "fr", "ja" or "pt-BR". A game that has a name in that language is returned with it as name, and its main name as originalName; a regional code falls back on its language ("fr-CA" on "fr"), a language with no name of its own takes a regional one ("pt" shows a name the game only has in "pt-BR"), and a game with no name in the language keeps its main name. Only names are localised: descriptions and summaries stay in English.

Answers

200objectThe list.
404No list has this id.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataList

Add a game to a list

PUT/lists/{id}/games/{game}Needs a session

Only the list's owner can do this. Adding a game twice changes nothing.

ParameterTypeMeaning
id in the addressstring (uuid)
game in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Answers

200OkThe game is on the list.
401The request has no valid session token.
403The session belongs to someone other than the list's owner.
404The list or the game does not exist.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

A Ok:

FieldTypeMeaning
oktrue

Remove a game from a list

DELETE/lists/{id}/games/{game}Needs a session

Only the list's owner can do this.

ParameterTypeMeaning
id in the addressstring (uuid)
game in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Answers

200OkThe game is not on the list.
401The request has no valid session token.
403The session belongs to someone other than the list's owner.
404The list or the game does not exist.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

A Ok:

FieldTypeMeaning
oktrue

Accounts

Your plan and your API tokens.

What you said about a game

GET/account/games/{id}Needs a session

The member's own rating, votes, collection statuses, comment, submitted videos, playlist votes and uploaded rulebooks for one game, so an application can show them next to the game. Never served from the shared cache.

ParameterTypeMeaning
id in the addressstringThe game's id, as returned in every game object. The game's slug is accepted too, and so is an address it had before: a slug changed when the game was renamed by the addressing rule, or the id or slug of an entry merged into it because both were the same game. The answer is the game under its current id and slug; compare them with what you sent to update a stored link.

Answers

200objectThe member's answers about the game.
401The request has no valid session token.
404No game has this id.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataMyAnswers

For example:

{
  "data": {
    "rating": 7.5,
    "complexity": 2,
    "recommendedAge": 10,
    "languageDependence": 2,
    "playerCounts": [
      {
        "players": 3,
        "vote": "recommended"
      },
      {
        "players": 4,
        "vote": "best"
      }
    ],
    "collection": [
      "owned"
    ],
    "comment": {
      "id": "4a0e7f0c-64d0-4f0e-8a51-6f4b1b2f9d10",
      "text": "Trade wood for sheep.",
      "status": "visible",
      "createdAt": "2026-11-20T18:04:11.120Z",
      "updatedAt": "2026-11-20T18:04:11.120Z"
    },
    "videos": [
      {
        "id": "0b0f5a51-64a5-4f6b-9a39-0a4d6c5c0f11",
        "provider": "youtube",
        "videoId": "dQw4w9WgXcQ",
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "title": "How to play Catan",
        "language": "en",
        "category": "how_to_play",
        "submittedBy": "Ana",
        "createdAt": "2026-11-20T18:04:11.120Z",
        "status": "pending"
      }
    ],
    "playlistVotes": [
      {
        "playlistId": "7d1c1a0e-2f0b-4d39-9a56-5a8d2b9d7c21",
        "vote": "up"
      }
    ],
    "rulebooks": [
      {
        "id": "c2b7e5a4-3f1d-4b7c-8f0a-9e6d5c4b3a21",
        "language": "en",
        "edition": "5th edition, 2015",
        "kind": "pdf",
        "pages": null,
        "size": 4812330,
        "createdAt": "2026-11-20T18:04:11.120Z",
        "files": [
          {
            "path": "/v1/media/rulebooks/5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77/c2b7e5a4-3f1d-4b7c-8f0a-9e6d5c4b3a21/1.pdf",
            "contentType": "application/pdf",
            "size": 4812330,
            "kind": null
          }
        ],
        "status": "pending"
      }
    ]
  }
}

Your plan, request limit and settings

GET/accountNeeds a session

Works with a session or an API token; a quick way to check a token.

Answers

200objectThe account behind the credentials sent.
401The request has no valid session token.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataAccount

For example:

{
  "data": {
    "displayName": "Ana",
    "plan": "free",
    "requestsPerMinute": 1200,
    "playlistProvider": null
  }
}
curl "https://api.thebgdb.org/v1/account"

Change your settings

PATCH/accountNeeds a session

Sets which music service the member wants playlists from: one of the three, or null for all of them. The website filters a game's playlists by it; an application can pass it as provider to GET /games/{id}/playlists.

Send (application/json)

FieldTypeMeaning
playlistProviderMusicProvider or null

Answers

200objectThe account with the setting applied.
400playlistProvider is not a known service or null.
401The request has no valid session token.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataAccount

For example:

{
  "data": {
    "displayName": "Ana",
    "plan": "free",
    "requestsPerMinute": 1200,
    "playlistProvider": "spotify"
  }
}

List your API tokens

GET/account/keysNeeds a session

Names and first characters only: a token's full value is shown once, when it is created. Needs a website session, not a token.

Answers

200objectYour tokens, newest first.
401The request has no valid session token.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

FieldTypeMeaning
dataarray of ApiToken
curl "https://api.thebgdb.org/v1/account/keys"

Create an API token

POST/account/keysNeeds a session

Returns the token once. Send it as Authorization: Bearer <token> to get the member request limit. Up to 10 tokens per account.

Send (application/json)

FieldTypeMeaning
namestring at least 1 characters, at most 60 characters

Answers

201objectThe new token. key is not retrievable later.
400The name is missing or too long, or the account already has 10 tokens.
401The request has no valid session token.
429More than 300 requests in a minute from this address. Wait a minute.

What a 201 holds

FieldTypeMeaning
dataApiToken + object

Delete an API token

DELETE/account/keys/{id}Needs a session

The token stops working at once.

ParameterTypeMeaning
id in the addressstring (uuid)

Answers

200OkThe token is gone.
401The request has no valid session token.
429More than 300 requests in a minute from this address. Wait a minute.

What a 200 holds

A Ok:

FieldTypeMeaning
oktrue

Service

Status and this document.

Check the API is up

GET/health

Answers without reading the database. Not rate limited.

Answers

200objectThe API is up.

What a 200 holds

FieldTypeMeaning
status"ok"
environment"production" | "staging" | "local"

For example:

{
  "status": "ok",
  "environment": "production"
}
curl "https://api.thebgdb.org/v1/health"

Get this document

GET/openapi.json

The OpenAPI 3.1 description of the API, regenerated by every deploy.

Answers

200objectThe OpenAPI document.
curl "https://api.thebgdb.org/v1/openapi.json"

Data shapes

The objects the answers above are made of.

Error

FieldTypeMeaning
errorstringWhat went wrong, in plain English words. The wording may change: act on code.
code"not_found" | "internal_error" | "rate_limited" | "invalid_token" | "invalid_lang" | "invalid_cursor" | "invalid_order" | "invalid_filter" | "invalid_letter" | "invalid_query" | "invalid_language" | "invalid_status" | "game_not_found" | "game_withdrawn" | "not_logged_in" | "email_not_confirmed" | "moderators_only" | "posting_too_fast" | "too_many_attempts" | "human_check_unavailable" | "human_check_missing" | "human_check_failed" | "human_check_unverified" | "invalid_email" | "invalid_display_name" | "password_too_short" | "email_taken" | "wrong_credentials" | "verification_link_expired" | "reset_link_invalid" | "reset_link_used" | "reset_link_expired" | "email_not_sent" | "invalid_token_name" | "too_many_tokens" | "invalid_playlist_provider" | "photo_missing" | "photo_too_large" | "photo_type_refused" | "daily_photo_limit" | "official_cover_refused" | "photo_not_found" | "photo_kind_missing" | "invalid_photo_kind" | "list_not_found" | "invalid_list_name" | "list_description_too_long" | "not_list_owner" | "rating_out_of_range" | "invalid_vote" | "invalid_collection_status" | "invalid_play_date" | "invalid_play_players" | "invalid_play_minutes" | "play_note_too_long" | "invalid_comment" | "comment_removed_by_moderator" | "comment_not_found" | "invalid_video_url" | "invalid_video_title" | "invalid_video_category" | "duplicate_video" | "daily_video_limit" | "video_not_found" | "invalid_playlist_url" | "playlist_title_too_long" | "playlist_title_unreadable" | "invalid_playlist_vote" | "duplicate_playlist" | "playlist_hidden" | "daily_playlist_limit" | "playlist_not_found" | "rulebook_missing" | "rulebook_too_large" | "rulebook_image_too_large" | "rulebook_type_refused" | "rulebook_mixed_files" | "rulebook_too_many_images" | "rulebook_edition_too_long" | "daily_rulebook_limit" | "rulebook_not_found" | "rulebook_rejected" | "invalid_upload_size" | "rulebook_upload_too_large" | "too_many_open_uploads" | "upload_token_missing" | "upload_not_found" | "upload_expired" | "invalid_upload_part" | "wrong_part_size" | "upload_not_pdf" | "part_incomplete" | "upload_parts_missing" | "upload_assembly_failed" | "upload_size_mismatch" | "invalid_correction" | "description_not_declared" | "unknown_credit" | "correction_stale" | "correction_range" | "daily_correction_limit" | "invalid_email_domain" | "note_too_long" | "publisher_not_found" | "duplicate_publisher_claim" | "too_many_pending_claims" | "engine_unavailable" | "publisher_unavailable" | "games_required" | "merge_refused" | "game_required" | "cover_candidate_required" | "image_required" | "engine_refused" | "engine_unknown_game" | "enrich_request_not_found" | "cover_review_closed" | "cover_candidate_unknown" | "cover_not_reusable" | "cover_not_stored" | "web_image_unknown" | "image_host_refused" | "image_not_fetched" | "image_not_readable" | "straighten_failed" | "straightened_unknown" | "no_cover" | "claim_not_found" | "invalid_rejection_reason" | "correction_not_found" | "invalid_accepted_changes" | "correction_decided" | "revision_not_found" | "revision_undone" | "revision_changed" | "invalid_snooze_item"A stable name for this refusal, for programs and for showing the message in another language. A code is never renamed; new ones may be added.
params optionalobjectThe numbers the sentence names, when it names any: for example { "max": 20 } with daily_photo_limit.

Ok

FieldTypeMeaning
oktrue

Range

FieldTypeMeaning
mininteger or null
maxinteger or null

GameSummary

FieldTypeMeaning
idstring (uuid)Never changes. When two entries turn out to be the same game, one is merged into the other: its id then leads to the game it was merged into.
slugstringUsed in URLs. The name, then the name and year when the name is taken, then a number after it (catan, catan-1995, catan-1995-2). It may change once, by that rule or by a merge; the slug it had keeps leading to the game.
namestringThe game's main name, or its name in the language asked for with lang when it has one.
originalName optionalstring or nullThe game's main name when name is the one of the language asked for with lang. Null otherwise.
yearPublishedinteger or null
playersRangeFewest and most players.
imagestring or nullThe game's cover: a path on this API when a member uploaded it or when we hold a copy of it (starts with /v1/media/), an absolute URL when it is hosted by the source, or null when the game has none. Texts and images that come from other sources under a licence are credited at https://thebgdb.org/credits and listed by GET /v1/credits.
thumbnailstring or nullA small version of image, for lists. For a cover we hold a copy of it is a path on this API to a file 250 pixels wide; for covers hosted on Wikimedia Commons it is 200 pixels wide. There is no resizing service for members' uploads or covers hosted elsewhere, so for those it is the same address as image. Null when the game has no cover.
kind optional"game" | "expansion" | "accessory"What the entry is: game a stand-alone game; expansion when it needs another game to be played (see relations.expansionOf on the game); accessory when it is not played at all (sleeves, an insert, a playmat). Everything is a game until a source states otherwise.
imageKind optional"box_front" | "board_traditional" | "box_partial" | "logo" | "components" | "in_play" | "people" | "other" | "box_back" | "setup" | "cards" | "rulebook" | nullWhat the cover shows: as a vision model judged it, box_front for a cover a moderator chose, or what the member said for a member's photo shown as the cover. Null when it has not been looked at or when the game has no cover. box_front the whole front of the box; box_back its back; box_partial the box at an angle, cropped, or an overall shot of it; board_traditional the board of a traditional game that never had a box (chess, go); setup the game laid out ready to play; in_play a game in progress, nobody visible; components the pieces, boards and tokens; cards cards; people people playing, or any person, face or hand in the picture; rulebook a page of the rules; logo a title or logo alone; other anything else. New words may be added; treat an unknown one as other.
imageAcceptable optionalboolean or nullWhether the cover is a good one: the whole front of the box (or the board of a traditional game), with no person in it, of quality 3 or more (imageQuality), at least 300 pixels on its short side. False means a better cover is wanted. A moderator's decision overrules what the cover was found to show. Null when nothing has looked at the cover or when the game has none. A member's approved photo is shown as the cover unless it was found not good while the source's cover is good.
imageQuality optionalinteger or nullHow good a picture the cover is, as a vision model judged it: 5 a clean, sharp, straight scan or packshot; 3 an honest photo with small faults (some glare, some angle); 1 and 2 blurred, tiny, dark, glaring, skewed, watermarked or cluttered. Below 3 the cover is not a good one (imageAcceptable false). Null when it has not been judged for quality or when the game has no cover. min 1, max 5
imageWidth optionalinteger or nullWidth of the cover in pixels, to lay it out before it loads. Null when not measured.
imageHeight optionalinteger or nullHeight of the cover in pixels. Null when not measured.
imageLanguage optionalstring or nullThe language of the edition the cover shows, as a language code (de for a German box). Null unless a source states it reliably, which is rare: most covers say nothing about it.
ratingRating or nullMembers' ratings. Null when nobody has rated it.
complexityComplexity or nullMembers' votes on how heavy the game is. Null when nobody has voted.

GameName

FieldTypeMeaning
namestringAs written in that language, in its own script.
languagestringLanguage code, lower case: "fr", "ja", "pt-br".
primarybooleanTrue for the game's main name in that language, false for any other name it is known by there.

SearchResult

Everything in GameSummary, plus:

FieldTypeMeaning
approximatebooleanTrue when the game was found by correcting the spelling of the query: its name is close to the query but does not contain it. Such games always come after the ones that match as written.
matchedNameobject or nullThe alternate name the query was found in. Null when it was found in the game's main name.
matchedName.namestring
matchedName.languagestring

Rating

FieldTypeMeaning
averagenumberMean of members' ratings, from 1 to 10.
countintegerHow many members rated the game.
weightednumberThe average pulled towards the mean of all ratings in the catalog, as if the game had also received 30 ratings at that mean: (30 × catalog mean + sum of the game's ratings) ÷ (30 + count). It keeps a game with a handful of high ratings from outranking a widely rated one. Ranks and order=rating use it. Brought up to date every hour.

Complexity

FieldTypeMeaning
averagenumberFrom 1 (light) to 5 (heavy).
votesinteger

Rank

FieldTypeMeaning
scope"overall" | "category"overall: among all ranked games. category: among the ranked games of one of the game's categories.
slug optionalstringThe category's slug. Absent for overall.
namestring"Overall", or the category's name.
rankinteger1 is best. min 1

PlayerCount

FieldTypeMeaning
playersintegerA number of players.
bestintegerMembers who find the game best with this many.
recommendedinteger
notRecommendedinteger

CollectionStatus

Play

FieldTypeMeaning
idstring (uuid)
gameGameSummary
datestring (date)
playersinteger or null
minutesinteger or null
notestring or null
createdAtstring (date-time)

Comment

FieldTypeMeaning
idstring (uuid)
authorstringDisplay name of the member who wrote it.
textstringPlain text, not HTML. Escape it before display.
ratingnumber or nullThe author's rating of the game, if they gave one.
createdAtstring (date-time)
updatedAtstring (date-time)

VideoCategory

Video

FieldTypeMeaning
idstring (uuid)
provider"youtube" | "vimeo"
videoIdstringThe video's id at the provider, for embedding.
urlstring (uri)Where to watch it, built from the id.
titlestring
languagestringLanguage spoken, such as "en" or "pt-BR".
categoryVideoCategory
submittedBystringDisplay name of the member who suggested it.
createdAtstring (date-time)

MusicProvider

Playlist

FieldTypeMeaning
idstring (uuid)
providerMusicProvider
kind"playlist" | "album"
titlestring
urlstring (uri)Where to listen, built from the service and the playlist's id there.
scoreintegerVotes up minus votes down.
votesintegerHow many members voted, either way.
submittedBystringDisplay name of the member who added it.
createdAtstring (date-time)

PlaylistStanding

FieldTypeMeaning
scoreinteger
votesinteger
status"visible" | "hidden"hidden: voted out of the list by members.

RulebookFile

FieldTypeMeaning
pathstringPath of the file on this API.
contentType"application/pdf" | "image/jpeg" | "image/png" | "image/webp"
sizeintegerBytes.
kind"box_front" | "board_traditional" | "box_partial" | "logo" | "components" | "in_play" | "people" | "other" | "box_back" | "setup" | "cards" | "rulebook" | nullWhat the file shows: rulebook for a page sent as an image; null for a PDF, which is not an image. box_front the whole front of the box; box_back its back; box_partial the box at an angle, cropped, or an overall shot of it; board_traditional the board of a traditional game that never had a box (chess, go); setup the game laid out ready to play; in_play a game in progress, nobody visible; components the pieces, boards and tokens; cards cards; people people playing, or any person, face or hand in the picture; rulebook a page of the rules; logo a title or logo alone; other anything else. New words may be added; treat an unknown one as other.

RulebookUpload

FieldTypeMeaning
idstring (uuid)The upload's id, and the rulebook's once it is complete.
tokenstringSend it as x-upload-token with every part and to finish or cancel. Shown once.
partSizeintegerBytes of every part but the last.
partsintegerHow many parts to send.
expiresAtstring (date-time)When the token stops being accepted.

OwnRulebook

FieldTypeMeaning
idstring (uuid)
languagestringA language code such as "en", "fr" or "pt-BR".
editionstring or nullWhich edition or printing the rules belong to, when the uploader said.
kind"pdf" | "images"One PDF file, or one image per page.
pagesinteger or nullNumber of pages. Null for a PDF whose pages could not be counted.
sizeintegerBytes, all files together.
filesarray of RulebookFileThe files, in reading order. A PDF has one.

Rulebook

FieldTypeMeaning
idstring (uuid)
languagestringA language code such as "en", "fr" or "pt-BR".
editionstring or nullWhich edition or printing the rules belong to, when the uploader said.
kind"pdf" | "images"One PDF file, or one image per page.
pagesinteger or nullNumber of pages. Null for a PDF whose pages could not be counted.
sizeintegerBytes, all files together.
filesarray of RulebookFileThe files, in reading order. A PDF has one.
uploadedBystringDisplay name of the member who uploaded it.
createdAtstring (date-time)

Account

FieldTypeMeaning
displayNamestring
plan"free" | "paid"
requestsPerMinuteinteger
playlistProviderMusicProvider or nullThe one music service the member wants playlists from. Null: all of them.

MyAnswers

FieldTypeMeaning
playlistVotesarray of objectThe member's votes on this game's playlists.
playlistVotes[].playlistIdstring (uuid)
playlistVotes[].vote"up" | "down"
rulebooksarray of OwnRulebook + objectRulebooks the member uploaded for this game, with where each stands. Rejected ones are deleted and not listed.
ratingnumber or null
complexityinteger or null
recommendedAgeinteger or null
languageDependenceinteger or null
playerCountsarray of objectThe member's ballot on player counts.
playerCounts[].playersinteger
playerCounts[].vote"best" | "recommended" | "not_recommended"
collectionarray of CollectionStatus
commentobject or null
comment.idstring (uuid)
comment.textstring
comment.status"visible" | "removed"removed: taken down by a moderator.
comment.createdAtstring (date-time)
comment.updatedAtstring (date-time)
videosarray of Video + objectVideos the member suggested for this game, with where each stands.

TermRef

FieldTypeMeaning
slugstring
namestring

TermCount

FieldTypeMeaning
slugstring
namestring
gamesintegerHow many games are linked to it.

AwardResult

Honour

FieldTypeMeaning
awardTermRef
categorystring or nullWhich prize of the award. Null for its main or only prize.
yearinteger or nullYear of the award. Null when the source does not state it; never guessed from the game's own year.
resultAwardResult

GameRef

FieldTypeMeaning
idstring (uuid)
slugstring
namestring
originalNamestring or null
yearPublishedinteger or null
thumbnailstring or nullA small version of the cover from the game's source. Members' photos are not used here.

AwardYear

FieldTypeMeaning
yearinteger or nullNull groups the honours whose year no source states; it comes last.
honoursarray of objectBy category (the main prize first), winners before the others.
honours[].categorystring or null
honours[].resultAwardResult
honours[].gameGameRef

AwardWithGames

Everything in TermWithGames, plus:

FieldTypeMeaning
yearsarray of AwardYearNewest first. The 500 most recent honours; independent of cursor and of the filters.

Relations

FieldTypeMeaning
expansionsarray of GameSummaryExpansions of this game.
expansionOfarray of GameSummaryThe game or games this expansion needs.
reimplementsarray of GameSummaryEarlier games this one is based on and reworks (Brass: Birmingham reworks Brass: Lancashire).
reimplementedByarray of GameSummaryLater games based on this one.
containsarray of GameSummaryGames that come in this box (a compilation).
containedInarray of GameSummaryCompilations this game is part of.
integratesWitharray of GameSummaryGames this one can be combined with. No source states this yet, so it is always empty for now.

Photo

FieldTypeMeaning
idstring (uuid)
pathstringPath of the file on this API.
kind"box_front" | "board_traditional" | "box_partial" | "logo" | "components" | "in_play" | "people" | "other" | "box_back" | "setup" | "cards" | "rulebook" | nullWhat the photo shows, as its uploader said and a moderator checked. Photos added before members were asked carry what a vision model saw. Null when nothing has said yet. box_front the whole front of the box; box_back its back; box_partial the box at an angle, cropped, or an overall shot of it; board_traditional the board of a traditional game that never had a box (chess, go); setup the game laid out ready to play; in_play a game in progress, nobody visible; components the pieces, boards and tokens; cards cards; people people playing, or any person, face or hand in the picture; rulebook a page of the rules; logo a title or logo alone; other anything else. New words may be added; treat an unknown one as other.
languagestring or nullThe language of the edition the photo shows, as a code such as "en" or "pt-BR". Null when its uploader did not say.
uploadedBystringDisplay name of the member who added it.
createdAtstring (date-time)
status"approved" | "pending"pending only appears to the member who uploaded it.
official optionalbooleanThe game's official cover, sent by a verified representative of one of its publishers.

Game

Everything in GameSummary, plus:

FieldTypeMeaning
namesarray of GameNameEvery name the game is known by, with its language: main names first, then by language. Empty when no source gave any beyond name. At most 200.
taglinestring or nullOne line saying what the game is, at most 160 characters. Null when no source gave one.
descriptionstring or nullA longer text about the game, in English, taken word for word from a source that allows it, such as the game's English Wikipedia article. Null when there is none. Texts and images that come from other sources under a licence are credited at https://thebgdb.org/credits and listed by GET /v1/credits.
summarystringOne factual paragraph built from the game's own data: year, players, designers, playing time, mechanics, publishers, awards. An empty string when the catalog knows none of these.
playtimeRangeShortest and longest game, in minutes.
minAgeinteger or nullRecommended minimum age.
eanstring or nullEAN-13 barcode.
officialUrlstring or nullThe game's official website.
updatedAtstring (date-time)
creditsobjectEverything the game is credited to or filed under, by kind. Each entry has its own endpoint. awards here is **deprecated**: it lists the awards that honoured the game by name only, nominations included; use the game's awards field, which has the category, the year and the result.
credits.designersarray of TermRef
credits.artistsarray of TermRef
credits.publishersarray of TermRef
credits.categoriesarray of TermRef
credits.mechanicsarray of TermRef
credits.awardsarray of TermRef
credits.familiesarray of TermRef
awardsarray of HonourWhat the game received from awards: most recent first, those with no stated year last. At most 200.
relationsRelations
imagesarray of PhotoOldest first.
ranksarray of RankThe game's place by weighted rating: overall first, then within each of its categories. Empty until five members have rated the game. Recomputed every hour.
recommendedAgeobject or nullThe age members recommend the game from: the median of their votes. Null when nobody has voted. The publisher's stated age is minAge.
recommendedAge.ageinteger
recommendedAge.votesinteger
playerCountsarray of PlayerCountMembers' votes for each number of players anyone voted on, fewest players first. Empty when nobody has voted.
bestWitharray of integerNumbers of players for which best has more votes than recommended and than notRecommended.
recommendedWitharray of integerNumbers of players for which best and recommended together have more votes than notRecommended.
languageDependenceobject or nullHow much the game depends on reading its language: the level most members chose (the lower one on a tie). 1 no text needed in play, 2 a little text, 3 a moderate amount, 4 a lot, 5 unplayable in another language. Null when nobody has voted.
languageDependence.levelinteger min 1, max 5
languageDependence.votesinteger
playlistsintegerPlaylists listed for the game (GET /games/{id}/playlists).
rulebooksintegerApproved rulebooks, in any language (GET /games/{id}/rulebooks).

ListSummary

FieldTypeMeaning
idstring (uuid)
namestring
descriptionstring or null
ownerstringDisplay name of the member who made it.
createdAtstring (date-time)
updatedAt optionalstring (date-time)When a game was last added to it, or when it was made.
gamesintegerHow many games are on it.

List

FieldTypeMeaning
idstring (uuid)
namestring
descriptionstring or null
ownerstring
createdAtstring (date-time)
isOwnerbooleanTrue when the session sent belongs to the owner.
gamesarray of GameSummaryIn the order they were added.

ApiToken

FieldTypeMeaning
idstring (uuid)
namestring
prefixstringFirst characters of the token.
createdAt optionalstring (date-time)

User

FieldTypeMeaning
idstring (uuid)
emailstring (email)
displayNamestring
emailVerified optionalbooleanFalse until the member opens the link emailed to them.
plan optional"free" | "paid"
role optional"member" | "moderator"

Session

FieldTypeMeaning
tokenstringSend as Authorization: Bearer <token>. Valid 30 days.
userUser