Esta referencia solo está en inglés.
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.
/games
Games, ordered and filtered as asked. To read everything, call again with cursor set to the nextCursor you received, until nextCursor is null.
| Parameter | Type | Meaning |
|---|
limit optional | integer | How many games to return. min 1, max 100, default 20 |
cursor optional | string | The 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 optional | integer | With 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 optional | integer | Only games that can be played by this many players. min 1, max 99 |
players_from optional | integer | With 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 optional | integer | Upper end of the range started by players_from. min 1, max 99 |
year_from optional | integer | Only games published in this year or later. |
year_to optional | integer | Only games published in this year or earlier. |
time_max optional | integer | Only games that can be finished within this many minutes. min 1 |
age optional | integer | Only 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 optional | number | Only games whose average complexity is at least this. Games nobody has voted on are left out. min 1, max 5 |
complexity_max optional | number | Only games whose average complexity is at most this. Games nobody has voted on are left out. min 1, max 5 |
rating_min optional | number | Only games whose average rating is at least this. Games nobody has rated are left out. min 1, max 10 |
lang optional | string | A 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
200 | object | A page of games. |
400 | | cursor, order, lang or a filter is not an accepted value. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
| Field | Type | Meaning |
|---|
data | array of GameSummary | |
total | integer | How many games match, across all pages. |
nextCursor | string or null | Pass 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"
/sitemap/games
A compact listing meant for sitemaps and mirrors: up to 10 000 games per call, in the order they entered the catalog.
| Parameter | Type | Meaning |
|---|
limit optional | integer | min 1, max 10000, default 10000 |
cursor optional | string | The nextCursor of the previous page. |
Answers
200 | object | A page of slugs. |
400 | | cursor is not a value this API issued. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
| Field | Type | Meaning |
|---|
data | array of object | |
data[].slug | string | |
data[].name | string | |
data[].updatedAt | string (date-time) | |
data[].image | string or null | The 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. |
nextCursor | string or null | |
curl "https://api.thebgdb.org/v1/sitemap/games"
/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
200 | object | The counts. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
| Field | Type | Meaning |
|---|
data | object | |
data.letters | array of object | |
data.years | array 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"
/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.
| Parameter | Type | Meaning |
|---|
lang optional | string | A 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 optional | string | Only games whose main name starts with this letter (A to Z, case ignored). 0 gives the names that start with anything else. |
year optional | integer | Only games first published this year. min -4000, max 2100 |
limit optional | integer | min 1, max 500, default 500 |
cursor optional | string | The nextCursor of the previous page. |
Answers
200 | object | A page of names. |
400 | | letter, year or cursor is not valid. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
| Field | Type | Meaning |
|---|
data | array of object | |
data[].id | string (uuid) | |
data[].slug | string | |
data[].name | string | The name in the language asked for with lang, when the game has one; its main name otherwise. |
data[].originalName | string or null | The main name, which decides the letter and the order, when name is a translation of it. |
data[].yearPublished | integer or null | |
total | integer | How many games match in all. |
nextCursor | string or null | Pass 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"
/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.
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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 optional | string | A 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
200 | object | The game. |
404 | | No game has this id. |
410 | | The entry was withdrawn because it is not a game (a series, a kind of game, an app); reason says what it is. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
/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.
| Parameter | Type | Meaning |
|---|
q required | string | What to look for. at least 2 characters, at most 100 characters |
limit optional | integer | min 1, max 50, default 20 |
lang optional | string | A 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
200 | object | Matching 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. |
400 | | q is shorter than 2 or longer than 100 characters, or lang is not a language code. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
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"
/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.
| Parameter | Type | Meaning |
|---|
kind optional | "text" | "image" | Only texts, or only images. Both when absent. |
limit optional | integer | min 1, max 100, default 100 |
cursor optional | string | The nextCursor of the previous page. |
lang optional | string | A 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
200 | object | A page of credits. |
400 | | kind or cursor is not an accepted value, or lang is not a language code. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
| Field | Type | Meaning |
|---|
data | array of object | |
data[].kind | "text" | "image" | text: the game's description. image: the game's cover from its source. |
data[].game | object | |
data[].sourceUrl | string 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[].sourceTitle | string or null | The Wikipedia article's title or the image's file name. Null when the address does not give one. |
data[].license | string | The 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[].licenseUrl | string or null (uri) | The licence's deed. Null when the short name does not say which version. |
data[].author | string or null | The 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. |
total | integer | How many credits match. |
nextCursor | string or null | Pass 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"
/anniversaries
Games whose age this year is a multiple of five, at most 100. The catalog records publication years, not days.
| Parameter | Type | Meaning |
|---|
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 optional | string | A 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
200 | object | This year's anniversaries, in the order asked for. |
400 | | order is not an accepted value. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
| Field | Type | Meaning |
|---|
year | integer | |
data | array of GameSummary + object | |
curl "https://api.thebgdb.org/v1/anniversaries"
/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.
| Parameter | Type | Meaning |
|---|
limit optional | integer | min 1, max 30, default 10 |
lang optional | string | A 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
200 | object | Winning games, most recent first. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
| Field | Type | Meaning |
|---|
data | array of object | |
data[].game | GameSummary | |
data[].honour | object | |
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"
/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.
| Parameter | Type | Meaning |
|---|
limit optional | integer | min 1, max 100, default 20 |
lang optional | string | A 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
200 | object | The hottest games, hottest first. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
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"
Awards
Awards, and the games each honoured, year by year: winners, nominees and other distinctions.
/awards
The awards in the catalog with the number of games linked to each, a page at a time.
| Parameter | Type | Meaning |
|---|
order optional | "name" | "games" | name alphabetical, games most games first. default "name" |
prefix optional | string | Only names starting with this text. Case is ignored. at most 40 characters |
limit optional | integer | min 1, max 500, default 100 |
cursor optional | string | The nextCursor of the previous page. |
Answers
200 | object | A page of awards. |
400 | | cursor or order is not an accepted value. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
| Field | Type | Meaning |
|---|
data | array of TermCount | |
total | integer | How many match, across all pages. |
nextCursor | string 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"
/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.
| Parameter | Type | Meaning |
|---|
slug in the address | string | The 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 optional | integer | With 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 optional | integer | Only games that can be played by this many players. min 1, max 99 |
players_from optional | integer | With 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 optional | integer | Upper end of the range started by players_from. min 1, max 99 |
year_from optional | integer | Only games published in this year or later. |
year_to optional | integer | Only games published in this year or earlier. |
time_max optional | integer | Only games that can be finished within this many minutes. min 1 |
age optional | integer | Only 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 optional | number | Only games whose average complexity is at least this. Games nobody has voted on are left out. min 1, max 5 |
complexity_max optional | number | Only games whose average complexity is at most this. Games nobody has voted on are left out. min 1, max 5 |
rating_min optional | number | Only games whose average rating is at least this. Games nobody has rated are left out. min 1, max 10 |
lang optional | string | A 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 optional | integer | min 1, max 100, default 60 |
cursor optional | string | The nextCursor of the previous page. |
Answers
200 | object | The award with its games. |
301 | | The slug is a prize that now belongs to an award: Location is that award's address. |
404 | | No award has this slug. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
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"
}
}
]
}
]
}
}
Ratings and polls
Members rate games and vote on their complexity, age, player counts and language dependence. The results are fields of the game.
/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.
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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)
| Field | Type | Meaning |
|---|
rating | number | min 1, max 10 |
Answers
200 | object | The rating was stored. |
400 | | rating is not a number from 1 to 10 with at most one decimal. |
401 | | The request has no valid session token. |
403 | | The member has not confirmed their email address. |
404 | | No game has this id. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
| Field | Type | Meaning |
|---|
data | object | |
data.rating | number | |
For example:
{
"data": {
"rating": 7.5
}
}
/games/{id}/ratingNeeds a session
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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
200 | Ok | The member has no rating on this game. |
401 | | The request has no valid session token. |
404 | | No game has this id. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
A Ok:
For example:
{
"ok": true
}
/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.
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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)
| Field | Type | Meaning |
|---|
weight | integer | min 1, max 5 |
Answers
200 | Ok | The vote was counted. |
400 | | weight is not a whole number from 1 to 5. |
401 | | The request has no valid session token. |
404 | | No game has this id. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
A Ok:
For example:
{
"ok": true
}
/games/{id}/complexityNeeds a session
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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
200 | Ok | The member has no vote on this. |
401 | | The request has no valid session token. |
404 | | No game has this id. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
A Ok:
For example:
{
"ok": true
}
/games/{id}/polls/ageNeeds a session
The youngest age, in years, the member would recommend the game for. This is members' opinion; the age stated by the publisher is minAge. One vote per member; voting again replaces it. The result is recommendedAge on the game.
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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)
| Field | Type | Meaning |
|---|
age | integer | min 1, max 21 |
Answers
200 | Ok | The vote was counted. |
400 | | age is not a whole number from 1 to 21. |
401 | | The request has no valid session token. |
404 | | No game has this id. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
A Ok:
For example:
{
"ok": true
}
/games/{id}/polls/ageNeeds a session
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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
200 | Ok | The member has no vote on this. |
401 | | The request has no valid session token. |
404 | | No game has this id. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
A Ok:
For example:
{
"ok": true
}
/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.
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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)
| Field | Type | Meaning |
|---|
level | integer | min 1, max 5 |
Answers
200 | Ok | The vote was counted. |
400 | | level is not a whole number from 1 to 5. |
401 | | The request has no valid session token. |
404 | | No game has this id. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
A Ok:
For example:
{
"ok": true
}
/games/{id}/polls/languageNeeds a session
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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
200 | Ok | The member has no vote on this. |
401 | | The request has no valid session token. |
404 | | No game has this id. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
A Ok:
For example:
{
"ok": true
}
/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.
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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)
| Field | Type | Meaning |
|---|
votes | array of object | Each number of players at most once. |
votes[].players | integer | min 1, max 20 |
votes[].vote | "best" | "recommended" | "not_recommended" | |
Answers
200 | Ok | The ballot was counted. |
400 | | The ballot is empty, repeats a number of players, or has a value out of range. |
401 | | The request has no valid session token. |
404 | | No game has this id. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
A Ok:
For example:
{
"ok": true
}
/games/{id}/polls/playersNeeds a session
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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
200 | Ok | The member has no ballot on this game. |
401 | | The request has no valid session token. |
404 | | No game has this id. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
A Ok:
For example:
{
"ok": true
}
/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.
| Parameter | Type | Meaning |
|---|
order optional | "recent" | "rating" | recent: the latest rating first. rating: the highest rating first. default "recent" |
limit optional | integer | min 1, max 100, default 50 |
cursor optional | string | The nextCursor of the previous page. |
Answers
200 | object | A page of the member's ratings. |
400 | | order or cursor is not an accepted value. |
401 | | The request has no valid session token. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
| Field | Type | Meaning |
|---|
data | array of object | |
data[].game | GameSummary | |
data[].rating | number | The member's rating, out of 10. min 1, max 10 |
data[].ratedAt | string (date-time) | When the rating was last given. |
total | integer | How many games the member has rated. |
nextCursor | string or null | Pass 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.
/games/{id}/collectionNeeds a session
Marks the game with one or more statuses. The list sent replaces the game's previous statuses.
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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)
Answers
200 | object | The statuses now on the game. |
400 | | statuses is empty or names a status other than owned and wishlist (code invalid_collection_status). |
401 | | The request has no valid session token. |
404 | | No game has this id. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
For example:
{
"data": {
"statuses": [
"owned",
"wishlist"
]
}
}
/games/{id}/collectionNeeds a session
Removes every status the member put on the game.
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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
200 | Ok | The game is not in the member's collection. |
401 | | The request has no valid session token. |
404 | | No game has this id. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
A Ok:
For example:
{
"ok": true
}
/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.
| Parameter | Type | Meaning |
|---|
status optional | CollectionStatus | Only games carrying this status. |
limit optional | integer | min 1, max 100, default 50 |
cursor optional | string | The nextCursor of the previous page. |
Answers
200 | object | A page of the member's collection. |
400 | | status or cursor is not an accepted value. |
401 | | The request has no valid session token. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
| Field | Type | Meaning |
|---|
data | array of CollectionItem | |
total | integer | How many games match, across all pages. |
nextCursor | string or null | Pass 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.
/games/{id}/playsNeeds a session
Records that the member played the game on a day. The game's plays count follows at once.
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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)
| Field | Type | Meaning |
|---|
date | string (date) | The day it was played. Not in the future. |
players optional | integer | min 1, max 99 |
minutes optional | integer | How long the play lasted. min 1, max 10000 |
note optional | string | Plain text. Visible to the member only. at most 500 characters |
Answers
201 | object | The play was logged. |
400 | | The date is missing, malformed or in the future, or another value is out of range. |
401 | | The request has no valid session token. |
404 | | No game has this id. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 201 holds
| Field | Type | Meaning |
|---|
data | object | |
data.id | string (uuid) | |
data.date | string (date) | |
data.players | integer or null | |
data.minutes | integer or null | |
data.note | string or null | |
For example:
{
"data": {
"id": "7d0a2b1e-1f8e-4d55-9a53-0e5d0f5f7c21",
"date": "2026-11-20",
"players": 4,
"minutes": 75,
"note": "Longest road won it."
}
}
/account/playsNeeds a session
The member's logged plays, most recent day first. Never served from the shared cache.
| Parameter | Type | Meaning |
|---|
limit optional | integer | min 1, max 100, default 50 |
cursor optional | string | The nextCursor of the previous page. |
Answers
200 | object | A page of the member's plays. |
400 | | cursor is not a value this API issued. |
401 | | The request has no valid session token. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
| Field | Type | Meaning |
|---|
data | array of Play | |
total | integer | |
nextCursor | string or null | Pass 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"
/account/plays/{id}Needs a session
| Parameter | Type | Meaning |
|---|
id in the address | string (uuid) | |
Answers
200 | Ok | The play is not in the member's log. |
401 | | The request has no valid session token. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
A Ok:
For example:
{
"ok": true
}
Music
Playlists to play a game to, on Apple Music, Spotify and YouTube, rated by members.
/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}.
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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 optional | MusicProvider | Only playlists on this service. |
limit optional | integer | min 1, max 100, default 50 |
cursor optional | string | The nextCursor of the previous page. |
Answers
200 | object | A page of playlists. |
400 | | provider or cursor is not an accepted value. |
404 | | No game has this id. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
| Field | Type | Meaning |
|---|
data | array of Playlist | |
nextCursor | string or null | Pass 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
}
/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.
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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)
| Field | Type | Meaning |
|---|
url | string (uri) | A playlist or album page on Apple Music, Spotify or YouTube. |
title optional | string | A title to fall back on when the service does not give the playlist's own. at least 2 characters, at most 120 characters |
Answers
201 | object | The playlist is listed. |
400 | | The 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. |
401 | | The request has no valid session token. |
403 | | The member has not confirmed their email address. |
404 | | No game has this id. |
409 | | This playlist is already listed for this game, or was and is no longer shown. |
429 | | Rate limited, more than five posts in a minute, or 20 playlists already added today. |
What a 201 holds
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"
}
}
/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.
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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 address | string (uuid) | The playlist's id. |
Send (application/json)
| Field | Type | Meaning |
|---|
vote | "up" | "down" | |
Answers
200 | object | The playlist's standing after the vote. |
400 | | vote is not "up" or "down". |
401 | | The request has no valid session token. |
404 | | No game has this id, or it lists no such playlist. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
For example:
{
"data": {
"score": 5,
"votes": 7,
"status": "visible"
}
}
/games/{id}/playlists/{playlist}/voteNeeds a session
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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 address | string (uuid) | The playlist's id. |
Answers
200 | object | The playlist's standing with the member's vote taken out. |
401 | | The request has no valid session token. |
404 | | No game has this id, or it lists no such playlist. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
For example:
{
"data": {
"score": 4,
"votes": 6,
"status": "visible"
}
}
Rules
Rulebooks uploaded by members, each tagged with its language.
/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}.
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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 optional | string | Only rulebooks written in this language. |
limit optional | integer | min 1, max 100, default 50 |
cursor optional | string | The nextCursor of the previous page. |
Answers
200 | object | A page of rulebooks. |
400 | | language or cursor is not an accepted value. |
404 | | No game has this id. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
| Field | Type | Meaning |
|---|
data | array of Rulebook | |
nextCursor | string or null | Pass 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
}
/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.
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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)
| Field | Type | Meaning |
|---|
file | array of string (binary) | One PDF, or 1 to 20 images. |
language | string | A language code such as "en", "fr" or "pt-BR". |
edition optional | string | Which edition or printing these rules belong to. Optional. at most 120 characters |
Answers
201 | object | The rulebook was stored and waits for review. |
400 | | No file was sent, a PDF was sent with other files, there are more than 20 images, or the language or edition is not valid. |
401 | | The request has no valid session token. |
403 | | The member has not confirmed their email address. |
404 | | No game has this id. |
413 | | The files weigh more than 25 MB together, or an image more than 5 MB. |
415 | | A file is not a PDF, JPEG, PNG or WebP. |
429 | | Rate limited, or the member already uploaded 10 rulebooks today. |
What a 201 holds
| Field | Type | Meaning |
|---|
data | OwnRulebook + 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"
}
}
/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.
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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)
| Field | Type | Meaning |
|---|
size | integer | Bytes of the whole file. min 1, max 209715200 |
language | string | A language code such as "en", "fr" or "pt-BR". |
edition optional | string | Which edition or printing these rules belong to. Optional. at most 120 characters |
Answers
201 | object | The upload is open. |
400 | | The size, the language or the edition is not valid. |
401 | | The request has no valid session token. |
403 | | The member has not confirmed their email address. |
404 | | No game has this id. |
413 | | The file is larger than 200 MB. |
429 | | Rate limited, more than five starts in a minute, three uploads already under way, or 10 rulebooks already added today. |
What a 201 holds
For example:
{
"data": {
"id": "c2b7e5a4-3f1d-4b7c-8f0a-9e6d5c4b3a21",
"token": "9f2c61f0a4b84d7e9c3a5b1d7e2f4a6c8b0d2e4f6a8c0e2f4a6b8d0c2e4f6a81",
"partSize": 8388608,
"parts": 8,
"expiresAt": "2026-11-21T20:04:11.120Z"
}
}
/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.
| Parameter | Type | Meaning |
|---|
upload in the address | string (uuid) | The upload's id, from POST /games/{id}/rulebooks/uploads. |
part in the address | integer | The part's number, from 1 to parts. min 1, max 25 |
Send (application/octet-stream)
Answers
200 | object | The part is stored. |
400 | | The part number is not a number, the body is shorter than the part should be, or it did not arrive whole. |
401 | | The x-upload-token header is missing, or the token has expired. |
403 | | The member has not confirmed their email address. |
404 | | No upload has this id and token: it was completed, cancelled or discarded, or the token is another upload's. |
413 | | The body is longer than this part should be, or the upload has fewer parts. |
415 | | The first part is not the start of a PDF. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
| Field | Type | Meaning |
|---|
data | object | |
data.part | integer | |
For example:
{
"data": {
"part": 3
}
}
/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.
| Parameter | Type | Meaning |
|---|
upload in the address | string (uuid) | The upload's id, from POST /games/{id}/rulebooks/uploads. |
Answers
201 | object | The rulebook was stored and waits for review. |
400 | | The parts do not add up to the size announced. The upload is discarded. |
401 | | The x-upload-token header is missing, or the token has expired. |
403 | | The member has not confirmed their email address. |
404 | | No upload has this id and token: it was completed, cancelled or discarded, or the token is another upload's. |
409 | | Some parts have not arrived (missing lists their numbers), or the parts could not be put together. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 201 holds
| Field | Type | Meaning |
|---|
data | OwnRulebook + 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"
}
}
/rulebook-uploads/{upload}
Discards the upload and the parts already sent. The token stops working.
| Parameter | Type | Meaning |
|---|
upload in the address | string (uuid) | The upload's id, from POST /games/{id}/rulebooks/uploads. |
Answers
200 | object | The upload is discarded. |
401 | | The x-upload-token header is missing, or the token has expired. |
403 | | The member has not confirmed their email address. |
404 | | No upload has this id and token: it was completed, cancelled or discarded, or the token is another upload's. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
| Field | Type | Meaning |
|---|
ok optional | boolean | |
For example:
{
"ok": true
}
Corrections
Members propose corrections to a game's facts; a moderator accepts or rejects them. Accepted corrections are listed in the game's history.
/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.
| Parameter | Type | Meaning |
|---|
id in the address | string | The game's id, as returned in every game object. The game's slug is accepted too. |
Send (application/json)
| Field | Type | Meaning |
|---|
changes | array of object or object or object | |
textDeclared optional | boolean | Must be true when a description is proposed: you wrote the text, or it is free to reuse. |
Answers
201 | object | The correction waits for a moderator. |
400 | | A change is not valid; the message says which and why. |
401 | | The request has no valid session token. |
403 | | The member has not confirmed their email address. |
404 | | No game has this id. |
409 | | The game no longer says what old states, or already is as proposed. |
429 | | Rate limited, or the member already suggested 20 corrections today. |
What a 201 holds
| Field | Type | Meaning |
|---|
data | object | |
data.id | string (uuid) | |
data.status | "pending" | |
data.fromPublisher | string or null | The publisher the member verifiably represents, when the game is credited to it. |
data.changes | array of object or object or object | |
/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.
| Parameter | Type | Meaning |
|---|
id in the address | string | The game's id, as returned in every game object. The game's slug is accepted too. |
Answers
200 | object | The game's accepted corrections. |
404 | | No game has this id. |
What a 200 holds
| Field | Type | Meaning |
|---|
data | array of object | |
data[].id | string (uuid) | |
data[].date | string (date-time) | |
data[].contributor | string | Display name of the member. |
data[].fromPublisher | boolean | The member was verified as representing one of the game's publishers. |
data[].changes | array 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
}
]
}
]
}
/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.
| Parameter | Type | Meaning |
|---|
limit optional | integer | min 1, max 100, default 50 |
cursor optional | string | nextCursor of the previous page. |
Answers
200 | object | A page of the member's corrections. |
400 | | cursor is not an accepted value. |
401 | | The request has no valid session token. |
What a 200 holds
| Field | Type | Meaning |
|---|
data | array of object | |
data[].id | string (uuid) | |
data[].status | "pending" | "accepted" | "rejected" | |
data[].reason | string or null | Why it was rejected. |
data[].createdAt | string (date-time) | |
data[].reviewedAt | string or null (date-time) | |
data[].undone | boolean | Accepted, then taken back by a moderator. |
data[].game | object | |
data[].changes | array of object or object or object + object | |
nextCursor | string or null | Pass as cursor for the next page. |
curl "https://api.thebgdb.org/v1/account/corrections"
/account/publisher-claimsNeeds a session
The member's requests to be recognised as representing a publisher, with their status.
Answers
200 | object | The member's requests, newest first. |
401 | | The request has no valid session token. |
What a 200 holds
| Field | Type | Meaning |
|---|
data | array of object | |
data[].id | string (uuid) | |
data[].status | "pending" | "verified" | "rejected" | |
data[].emailDomain | string | |
data[].note | string or null | |
data[].createdAt optional | string (date-time) | |
data[].verifiedAt optional | string or null (date-time) | |
data[].publisher | object | |
curl "https://api.thebgdb.org/v1/account/publisher-claims"
/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)
| Field | Type | Meaning |
|---|
publisher | string | The publisher's slug. |
emailDomain | string | The company's email domain. |
note optional | string | at most 500 characters |
Answers
201 | object | The request waits for a moderator. |
400 | | The publisher, the domain or the note is not valid. |
401 | | The request has no valid session token. |
403 | | The member has not confirmed their email address. |
409 | | The member already sent a request for this publisher. |
429 | | Rate limited, or five requests are already waiting. |
What a 201 holds
| Field | Type | Meaning |
|---|
data | object | |
data.id | string (uuid) | |
data.status | "pending" | "verified" | "rejected" | |
data.emailDomain | string | |
data.note | string or null | |
data.createdAt optional | string (date-time) | |
data.verifiedAt optional | string or null (date-time) | |
data.publisher | object | |
Accounts
Your plan and your API tokens.
/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.
| Parameter | Type | Meaning |
|---|
id in the address | string | The 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
200 | object | The member's answers about the game. |
401 | | The request has no valid session token. |
404 | | No game has this id. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
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"
}
]
}
}
/accountNeeds a session
Works with a session or an API token; a quick way to check a token.
Answers
200 | object | The account behind the credentials sent. |
401 | | The request has no valid session token. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
For example:
{
"data": {
"displayName": "Ana",
"plan": "free",
"requestsPerMinute": 1200,
"playlistProvider": null
}
}
curl "https://api.thebgdb.org/v1/account"
/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)
| Field | Type | Meaning |
|---|
playlistProvider | MusicProvider or null | |
Answers
200 | object | The account with the setting applied. |
400 | | playlistProvider is not a known service or null. |
401 | | The request has no valid session token. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
For example:
{
"data": {
"displayName": "Ana",
"plan": "free",
"requestsPerMinute": 1200,
"playlistProvider": "spotify"
}
}
/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
200 | object | Your tokens, newest first. |
401 | | The request has no valid session token. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
curl "https://api.thebgdb.org/v1/account/keys"
/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)
| Field | Type | Meaning |
|---|
name | string | at least 1 characters, at most 60 characters |
Answers
201 | object | The new token. key is not retrievable later. |
400 | | The name is missing or too long, or the account already has 10 tokens. |
401 | | The request has no valid session token. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 201 holds
| Field | Type | Meaning |
|---|
data | ApiToken + object | |
/account/keys/{id}Needs a session
The token stops working at once.
| Parameter | Type | Meaning |
|---|
id in the address | string (uuid) | |
Answers
200 | Ok | The token is gone. |
401 | | The request has no valid session token. |
429 | | More than 300 requests in a minute from this address. Wait a minute. |
What a 200 holds
A Ok: