{"openapi":"3.1.0","info":{"title":"The Board Game DB API","version":"1.0.0","summary":"An open database of board games.","description":"Read the catalog of board games: facts about each game, the people and companies behind it, how it is classified and what it won.\n\n**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.\n\n**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>`.\n\n**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.\n\n**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.\n\n**Slugs** are stable: once a game or a credit has a slug, it does not change.\n\n**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."},"servers":[{"url":"https://api.thebgdb.org/v1","description":"Production"},{"url":"https://api-staging.thebgdb.org/v1","description":"Staging (test data)"}],"tags":[{"name":"Games","description":"Look games up, list them, search them."},{"name":"Designers","description":"People who design games."},{"name":"Artists","description":"People who illustrate games."},{"name":"Publishers","description":"Companies that publish games."},{"name":"Categories","description":"What a game is about."},{"name":"Mechanics","description":"How a game plays."},{"name":"Awards","description":"Awards, and the games each honoured, year by year: winners, nominees and other distinctions."},{"name":"Families","description":"Series and franchises a game belongs to."},{"name":"Ratings and polls","description":"Members rate games and vote on their complexity, age, player counts and language dependence. The results are fields of the game."},{"name":"Collections","description":"The games a member owns, wants or trades."},{"name":"Plays","description":"A member's log of games played."},{"name":"Comments","description":"What members write about a game."},{"name":"Videos","description":"Videos about a game, on other sites."},{"name":"Music","description":"Playlists to play a game to, on Apple Music, Spotify and YouTube, rated by members."},{"name":"Rules","description":"Rulebooks uploaded by members, each tagged with its language."},{"name":"Photos","description":"Photos added by members."},{"name":"Corrections","description":"Members propose corrections to a game's facts; a moderator accepts or rejects them. Accepted corrections are listed in the game's history."},{"name":"Lists","description":"Lists of games made by members."},{"name":"Accounts","description":"Your plan and your API tokens."},{"name":"Service","description":"Status and this document."}],"paths":{"/health":{"get":{"operationId":"get_health","tags":["Service"],"summary":"Check the API is up","description":"Answers without reading the database. Not rate limited.","responses":{"200":{"description":"The API is up.","content":{"application/json":{"schema":{"type":"object","required":["status","environment"],"properties":{"status":{"type":"string","const":"ok"},"environment":{"type":"string","enum":["production","staging","local"]}}},"example":{"status":"ok","environment":"production"}}}}}}},"/openapi.json":{"get":{"operationId":"get_openapi","tags":["Service"],"summary":"Get this document","description":"The OpenAPI 3.1 description of the API, regenerated by every deploy.","responses":{"200":{"description":"The OpenAPI document.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/games":{"get":{"operationId":"list_games","tags":["Games"],"summary":"List games, a page at a time","description":"Games, ordered and filtered as asked. To read everything, call again with `cursor` set to the `nextCursor` you received, until `nextCursor` is null.","parameters":[{"name":"limit","in":"query","description":"How many games to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page. Omit for the first page.","schema":{"type":"string"}},{"name":"order","in":"query","description":"`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.","schema":{"type":"string","enum":["added","new","name","year","oldest","hot","rating","complexity","random"],"default":"added"}},{"name":"seed","in":"query","description":"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.","schema":{"type":"integer","minimum":0,"maximum":2147483646},"example":482913},{"name":"kind","in":"query","description":"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.","schema":{"type":"string","enum":["game","expansion","accessory"]}},{"name":"players","in":"query","description":"Only games that can be played by this many players.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"players_from","in":"query","description":"With players_to: only games that can be played at every count from players_from to players_to. Alone, the same as players.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"players_to","in":"query","description":"Upper end of the range started by players_from.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"year_from","in":"query","description":"Only games published in this year or later.","schema":{"type":"integer"}},{"name":"year_to","in":"query","description":"Only games published in this year or earlier.","schema":{"type":"integer"}},{"name":"time_max","in":"query","description":"Only games that can be finished within this many minutes.","schema":{"type":"integer","minimum":1}},{"name":"age","in":"query","description":"Only games suitable for someone of this age.","schema":{"type":"integer","minimum":0,"maximum":99}},{"name":"illustrated","in":"query","description":"Set to 1 for only games that have a cover image.","schema":{"type":"string","enum":["1"]}},{"name":"cover","in":"query","description":"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`.","schema":{"type":"string","enum":["ok","needs_work","unreviewed","none"]}},{"name":"complexity_min","in":"query","description":"Only games whose average complexity is at least this. Games nobody has voted on are left out.","schema":{"type":"number","minimum":1,"maximum":5},"example":2.5},{"name":"complexity_max","in":"query","description":"Only games whose average complexity is at most this. Games nobody has voted on are left out.","schema":{"type":"number","minimum":1,"maximum":5},"example":3.5},{"name":"rating_min","in":"query","description":"Only games whose average rating is at least this. Games nobody has rated are left out.","schema":{"type":"number","minimum":1,"maximum":10},"example":7},{"name":"lang","in":"query","description":"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.","schema":{"type":"string"},"example":"fr"}],"responses":{"200":{"description":"A page of games.","content":{"application/json":{"schema":{"type":"object","required":["data","total","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GameSummary"}},"total":{"type":"integer","description":"How many games match, across all pages."},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."}}},"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"}}}},"400":{"description":"`cursor`, `order`, `lang` or a filter is not an accepted value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sitemap/games":{"get":{"operationId":"list_game_addresses","tags":["Games"],"summary":"List every game's slug, cover and last change","description":"A compact listing meant for sitemaps and mirrors: up to 10 000 games per call, in the order they entered the catalog.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":10000,"default":10000}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of slugs.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","required":["slug","name","updatedAt","image"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"},"image":{"type":["string","null"],"description":"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":{"type":["string","null"]}}}}}},"400":{"description":"`cursor` is not a value this API issued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/index/games/counts":{"get":{"operationId":"count_games_by_letter_and_year","tags":["Games"],"summary":"Count games by first letter and by year","description":"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.","responses":{"200":{"description":"The counts.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["letters","years"],"properties":{"letters":{"type":"array","items":{"type":"object","required":["letter","games"],"properties":{"letter":{"type":"string","description":"A to Z, or `0` for names that start with a digit, a sign or an accented letter."},"games":{"type":"integer"}}}},"years":{"type":"array","items":{"type":"object","required":["year","games"],"properties":{"year":{"type":"integer"},"games":{"type":"integer"}}}}}}}},"example":{"data":{"letters":[{"letter":"0","games":212},{"letter":"A","games":1340}],"years":[{"year":1995,"games":210},{"year":1996,"games":198}]}}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/index/games":{"get":{"operationId":"list_game_names","tags":["Games"],"summary":"List game names by first letter or by year","description":"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.","parameters":[{"name":"lang","in":"query","description":"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.","schema":{"type":"string"},"example":"fr"},{"name":"letter","in":"query","description":"Only games whose main name starts with this letter (A to Z, case ignored). `0` gives the names that start with anything else.","schema":{"type":"string","pattern":"^[A-Za-z0]$"}},{"name":"year","in":"query","description":"Only games first published this year.","schema":{"type":"integer","minimum":-4000,"maximum":2100}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":500}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of names.","content":{"application/json":{"schema":{"type":"object","required":["data","total","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","slug","name","originalName","yearPublished"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string","description":"The name in the language asked for with `lang`, when the game has one; its main name otherwise."},"originalName":{"type":["string","null"],"description":"The main name, which decides the letter and the order, when `name` is a translation of it."},"yearPublished":{"type":["integer","null"]}}}},"total":{"type":"integer","description":"How many games match in all."},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."}}},"example":{"data":[{"id":"6c45ac28-4841-43f5-a1b3-59ea01e63f16","slug":"catan","name":"Catan","originalName":null,"yearPublished":1995}],"total":1,"nextCursor":null}}}},"400":{"description":"`letter`, `year` or `cursor` is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}":{"get":{"operationId":"get_game","tags":["Games"],"summary":"Get one game","description":"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.","parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"},{"name":"lang","in":"query","description":"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.","schema":{"type":"string"},"example":"fr"}],"responses":{"200":{"description":"The game.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Game"}}}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"The entry was withdrawn because it is not a game (a series, a kind of game, an app); `reason` says what it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/photos":{"get":{"operationId":"list_game_photos","tags":["Photos"],"summary":"List a game's photos","description":"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`.","parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"},{"name":"kind","in":"query","description":"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`.","schema":{"type":"string","enum":["box_front","board_traditional","box_partial","logo","components","in_play","people","other","box_back","setup","cards","rulebook"]},"example":"box_back"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of photos.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Photo"}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."}}}}}},"400":{"description":"`kind` is not one of the words listed (`invalid_photo_kind`), or `cursor` is not an accepted value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/images":{"post":{"operationId":"add_game_photo","tags":["Photos"],"summary":"Add a photo to a game","description":"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.","security":[{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","kind"],"properties":{"file":{"type":"string","format":"binary"},"kind":{"type":"string","enum":["box_front","board_traditional","box_partial","logo","components","in_play","people","other","box_back","setup","cards","rulebook"],"description":"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":{"type":"string","enum":["true"],"description":"The game's official cover. Only from a verified representative of one of its publishers."},"language":{"type":"string","description":"The language of the edition the photo shows, as a code such as \"en\" or \"pt-BR\". Optional."}}}}}},"responses":{"201":{"description":"The photo was stored.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","path","kind","language"],"properties":{"id":{"type":"string","format":"uuid"},"path":{"type":"string","description":"Path of the file on this API."},"kind":{"type":"string","enum":["box_front","board_traditional","box_partial","logo","components","in_play","people","other","box_back","setup","cards","rulebook"],"description":"What the photo shows, as sent."},"language":{"type":["string","null"],"description":"The language of the edition shown, when it was said."}}}}}}}},"400":{"description":"No 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`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The member has not confirmed their email address, or sent `official` without being a verified representative of one of the game's publishers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The file is larger than 5 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The file is not a JPEG, PNG or WebP image.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited, or the member already added 20 photos today.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/media/{key}":{"get":{"operationId":"get_media","tags":["Photos"],"summary":"Download an uploaded photo or rulebook file","description":"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.","security":[{},{"session":[]},{"apiToken":[]}],"parameters":[{"name":"key","in":"path","required":true,"description":"The rest of a `path` after `/v1/media/`. It contains slashes.","schema":{"type":"string"}}],"responses":{"200":{"description":"The file.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"No file has this key, or it waits for review and is not yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/search":{"get":{"operationId":"search_games","tags":["Games"],"summary":"Search games by name","description":"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).\n\nMisspellings: 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.","parameters":[{"name":"q","in":"query","required":true,"description":"What to look for.","schema":{"type":"string","minLength":2,"maxLength":100},"example":"catan"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"lang","in":"query","description":"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.","schema":{"type":"string"},"example":"fr"}],"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"type":"object","required":["query","data"],"properties":{"query":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}}}},"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}]}}}},"400":{"description":"`q` is shorter than 2 or longer than 100 characters, or `lang` is not a language code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credits":{"get":{"operationId":"list_credits","tags":["Games"],"summary":"Texts and images to credit","description":"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.","parameters":[{"name":"kind","in":"query","description":"Only texts, or only images. Both when absent.","schema":{"type":"string","enum":["text","image"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}},{"name":"lang","in":"query","description":"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.","schema":{"type":"string"},"example":"fr"}],"responses":{"200":{"description":"A page of credits.","content":{"application/json":{"schema":{"type":"object","required":["data","total","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","required":["kind","game","sourceUrl","sourceTitle","license","licenseUrl","author"],"properties":{"kind":{"type":"string","enum":["text","image"],"description":"`text`: the game's `description`. `image`: the game's cover from its source."},"game":{"type":"object","required":["id","slug","name"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string","description":"The game's main name, or its name in the language asked for with `lang`."}}},"sourceUrl":{"type":["string","null"],"format":"uri","description":"The page the text was taken from, or the page that documents the image. Null when no such page is on record.","example":"https://en.wikipedia.org/wiki/Catan"},"sourceTitle":{"type":["string","null"],"description":"The Wikipedia article's title or the image's file name. Null when the address does not give one.","example":"Catan"},"license":{"type":"string","description":"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.","example":"CC BY-SA 4.0"},"licenseUrl":{"type":["string","null"],"format":"uri","description":"The licence's deed. Null when the short name does not say which version.","example":"https://creativecommons.org/licenses/by-sa/4.0/"},"author":{"type":["string","null"],"description":"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.","example":"Jane Doe"}}}},"total":{"type":"integer","description":"How many credits match."},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."}}},"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}}}},"400":{"description":"`kind` or `cursor` is not an accepted value, or `lang` is not a language code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/anniversaries":{"get":{"operationId":"list_anniversaries","tags":["Games"],"summary":"Games with a round birthday this year","description":"Games whose age this year is a multiple of five, at most 100. The catalog records publication years, not days.","parameters":[{"name":"order","in":"query","description":"`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.","schema":{"type":"string","enum":["oldest","youngest"],"default":"oldest"}},{"name":"lang","in":"query","description":"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.","schema":{"type":"string"},"example":"fr"}],"responses":{"200":{"description":"This year's anniversaries, in the order asked for.","content":{"application/json":{"schema":{"type":"object","required":["year","data"],"properties":{"year":{"type":"integer"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/GameSummary"},{"type":"object","required":["age"],"properties":{"age":{"type":"integer","description":"Years since publication."}}}]}}}}}}},"400":{"description":"`order` is not an accepted value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/designers":{"get":{"operationId":"list_designers","tags":["Designers"],"summary":"List designers","description":"The designers in the catalog with the number of games linked to each, a page at a time.","parameters":[{"name":"order","in":"query","description":"`name` alphabetical, `games` most games first.","schema":{"type":"string","enum":["name","games"],"default":"name"}},{"name":"prefix","in":"query","description":"Only names starting with this text. Case is ignored.","schema":{"type":"string","maxLength":40}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of designers.","content":{"application/json":{"schema":{"type":"object","required":["data","total","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TermCount"}},"total":{"type":"integer","description":"How many match, across all pages."},"nextCursor":{"type":["string","null"]}}},"example":{"data":[{"slug":"klaus-teuber","name":"Klaus Teuber","games":2}],"total":1,"nextCursor":null}}}},"400":{"description":"`cursor` or `order` is not an accepted value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/designers/{slug}":{"get":{"operationId":"get_designer","tags":["Designers"],"summary":"Get one designer and its games","description":"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.","parameters":[{"name":"slug","in":"path","required":true,"description":"The designer's slug, as returned by the API.","schema":{"type":"string"},"example":"klaus-teuber"},{"name":"order","in":"query","description":"`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.","schema":{"type":"string","enum":["added","new","name","year","oldest","hot","rating","complexity","random"]}},{"name":"seed","in":"query","description":"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.","schema":{"type":"integer","minimum":0,"maximum":2147483646},"example":482913},{"name":"kind","in":"query","description":"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.","schema":{"type":"string","enum":["game","expansion","accessory"]}},{"name":"players","in":"query","description":"Only games that can be played by this many players.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"players_from","in":"query","description":"With players_to: only games that can be played at every count from players_from to players_to. Alone, the same as players.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"players_to","in":"query","description":"Upper end of the range started by players_from.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"year_from","in":"query","description":"Only games published in this year or later.","schema":{"type":"integer"}},{"name":"year_to","in":"query","description":"Only games published in this year or earlier.","schema":{"type":"integer"}},{"name":"time_max","in":"query","description":"Only games that can be finished within this many minutes.","schema":{"type":"integer","minimum":1}},{"name":"age","in":"query","description":"Only games suitable for someone of this age.","schema":{"type":"integer","minimum":0,"maximum":99}},{"name":"illustrated","in":"query","description":"Set to 1 for only games that have a cover image.","schema":{"type":"string","enum":["1"]}},{"name":"cover","in":"query","description":"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`.","schema":{"type":"string","enum":["ok","needs_work","unreviewed","none"]}},{"name":"complexity_min","in":"query","description":"Only games whose average complexity is at least this. Games nobody has voted on are left out.","schema":{"type":"number","minimum":1,"maximum":5},"example":2.5},{"name":"complexity_max","in":"query","description":"Only games whose average complexity is at most this. Games nobody has voted on are left out.","schema":{"type":"number","minimum":1,"maximum":5},"example":3.5},{"name":"rating_min","in":"query","description":"Only games whose average rating is at least this. Games nobody has rated are left out.","schema":{"type":"number","minimum":1,"maximum":10},"example":7},{"name":"lang","in":"query","description":"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.","schema":{"type":"string"},"example":"fr"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":60}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"The designer with its games.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/TermWithGames"}}},"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}}}}},"404":{"description":"No designer has this slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/artists":{"get":{"operationId":"list_artists","tags":["Artists"],"summary":"List artists","description":"The artists in the catalog with the number of games linked to each, a page at a time.","parameters":[{"name":"order","in":"query","description":"`name` alphabetical, `games` most games first.","schema":{"type":"string","enum":["name","games"],"default":"name"}},{"name":"prefix","in":"query","description":"Only names starting with this text. Case is ignored.","schema":{"type":"string","maxLength":40}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of artists.","content":{"application/json":{"schema":{"type":"object","required":["data","total","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TermCount"}},"total":{"type":"integer","description":"How many match, across all pages."},"nextCursor":{"type":["string","null"]}}},"example":{"data":[{"slug":"beth-sobel","name":"Beth Sobel","games":2}],"total":1,"nextCursor":null}}}},"400":{"description":"`cursor` or `order` is not an accepted value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/artists/{slug}":{"get":{"operationId":"get_artist","tags":["Artists"],"summary":"Get one artist and its games","description":"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.","parameters":[{"name":"slug","in":"path","required":true,"description":"The artist's slug, as returned by the API.","schema":{"type":"string"},"example":"beth-sobel"},{"name":"order","in":"query","description":"`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.","schema":{"type":"string","enum":["added","new","name","year","oldest","hot","rating","complexity","random"]}},{"name":"seed","in":"query","description":"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.","schema":{"type":"integer","minimum":0,"maximum":2147483646},"example":482913},{"name":"kind","in":"query","description":"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.","schema":{"type":"string","enum":["game","expansion","accessory"]}},{"name":"players","in":"query","description":"Only games that can be played by this many players.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"players_from","in":"query","description":"With players_to: only games that can be played at every count from players_from to players_to. Alone, the same as players.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"players_to","in":"query","description":"Upper end of the range started by players_from.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"year_from","in":"query","description":"Only games published in this year or later.","schema":{"type":"integer"}},{"name":"year_to","in":"query","description":"Only games published in this year or earlier.","schema":{"type":"integer"}},{"name":"time_max","in":"query","description":"Only games that can be finished within this many minutes.","schema":{"type":"integer","minimum":1}},{"name":"age","in":"query","description":"Only games suitable for someone of this age.","schema":{"type":"integer","minimum":0,"maximum":99}},{"name":"illustrated","in":"query","description":"Set to 1 for only games that have a cover image.","schema":{"type":"string","enum":["1"]}},{"name":"cover","in":"query","description":"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`.","schema":{"type":"string","enum":["ok","needs_work","unreviewed","none"]}},{"name":"complexity_min","in":"query","description":"Only games whose average complexity is at least this. Games nobody has voted on are left out.","schema":{"type":"number","minimum":1,"maximum":5},"example":2.5},{"name":"complexity_max","in":"query","description":"Only games whose average complexity is at most this. Games nobody has voted on are left out.","schema":{"type":"number","minimum":1,"maximum":5},"example":3.5},{"name":"rating_min","in":"query","description":"Only games whose average rating is at least this. Games nobody has rated are left out.","schema":{"type":"number","minimum":1,"maximum":10},"example":7},{"name":"lang","in":"query","description":"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.","schema":{"type":"string"},"example":"fr"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":60}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"The artist with its games.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/TermWithGames"}}},"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}}}}},"404":{"description":"No artist has this slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/publishers":{"get":{"operationId":"list_publishers","tags":["Publishers"],"summary":"List publishers","description":"The publishers in the catalog with the number of games linked to each, a page at a time.","parameters":[{"name":"order","in":"query","description":"`name` alphabetical, `games` most games first.","schema":{"type":"string","enum":["name","games"],"default":"name"}},{"name":"prefix","in":"query","description":"Only names starting with this text. Case is ignored.","schema":{"type":"string","maxLength":40}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of publishers.","content":{"application/json":{"schema":{"type":"object","required":["data","total","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TermCount"}},"total":{"type":"integer","description":"How many match, across all pages."},"nextCursor":{"type":["string","null"]}}},"example":{"data":[{"slug":"kosmos","name":"Kosmos","games":2}],"total":1,"nextCursor":null}}}},"400":{"description":"`cursor` or `order` is not an accepted value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/publishers/{slug}":{"get":{"operationId":"get_publisher","tags":["Publishers"],"summary":"Get one publisher and its games","description":"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.","parameters":[{"name":"slug","in":"path","required":true,"description":"The publisher's slug, as returned by the API.","schema":{"type":"string"},"example":"kosmos"},{"name":"order","in":"query","description":"`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.","schema":{"type":"string","enum":["added","new","name","year","oldest","hot","rating","complexity","random"]}},{"name":"seed","in":"query","description":"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.","schema":{"type":"integer","minimum":0,"maximum":2147483646},"example":482913},{"name":"kind","in":"query","description":"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.","schema":{"type":"string","enum":["game","expansion","accessory"]}},{"name":"players","in":"query","description":"Only games that can be played by this many players.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"players_from","in":"query","description":"With players_to: only games that can be played at every count from players_from to players_to. Alone, the same as players.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"players_to","in":"query","description":"Upper end of the range started by players_from.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"year_from","in":"query","description":"Only games published in this year or later.","schema":{"type":"integer"}},{"name":"year_to","in":"query","description":"Only games published in this year or earlier.","schema":{"type":"integer"}},{"name":"time_max","in":"query","description":"Only games that can be finished within this many minutes.","schema":{"type":"integer","minimum":1}},{"name":"age","in":"query","description":"Only games suitable for someone of this age.","schema":{"type":"integer","minimum":0,"maximum":99}},{"name":"illustrated","in":"query","description":"Set to 1 for only games that have a cover image.","schema":{"type":"string","enum":["1"]}},{"name":"cover","in":"query","description":"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`.","schema":{"type":"string","enum":["ok","needs_work","unreviewed","none"]}},{"name":"complexity_min","in":"query","description":"Only games whose average complexity is at least this. Games nobody has voted on are left out.","schema":{"type":"number","minimum":1,"maximum":5},"example":2.5},{"name":"complexity_max","in":"query","description":"Only games whose average complexity is at most this. Games nobody has voted on are left out.","schema":{"type":"number","minimum":1,"maximum":5},"example":3.5},{"name":"rating_min","in":"query","description":"Only games whose average rating is at least this. Games nobody has rated are left out.","schema":{"type":"number","minimum":1,"maximum":10},"example":7},{"name":"lang","in":"query","description":"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.","schema":{"type":"string"},"example":"fr"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":60}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"The publisher with its games.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/TermWithGames"}}},"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}}}}},"404":{"description":"No publisher has this slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/categories":{"get":{"operationId":"list_categories","tags":["Categories"],"summary":"List categories","description":"The categories in the catalog with the number of games linked to each, a page at a time.","parameters":[{"name":"order","in":"query","description":"`name` alphabetical, `games` most games first.","schema":{"type":"string","enum":["name","games"],"default":"name"}},{"name":"prefix","in":"query","description":"Only names starting with this text. Case is ignored.","schema":{"type":"string","maxLength":40}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of categories.","content":{"application/json":{"schema":{"type":"object","required":["data","total","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TermCount"}},"total":{"type":"integer","description":"How many match, across all pages."},"nextCursor":{"type":["string","null"]}}},"example":{"data":[{"slug":"family","name":"Family","games":2}],"total":1,"nextCursor":null}}}},"400":{"description":"`cursor` or `order` is not an accepted value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/categories/{slug}":{"get":{"operationId":"get_category","tags":["Categories"],"summary":"Get one category and its games","description":"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.","parameters":[{"name":"slug","in":"path","required":true,"description":"The category's slug, as returned by the API.","schema":{"type":"string"},"example":"family"},{"name":"order","in":"query","description":"`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.","schema":{"type":"string","enum":["added","new","name","year","oldest","hot","rating","complexity","random"]}},{"name":"seed","in":"query","description":"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.","schema":{"type":"integer","minimum":0,"maximum":2147483646},"example":482913},{"name":"kind","in":"query","description":"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.","schema":{"type":"string","enum":["game","expansion","accessory"]}},{"name":"players","in":"query","description":"Only games that can be played by this many players.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"players_from","in":"query","description":"With players_to: only games that can be played at every count from players_from to players_to. Alone, the same as players.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"players_to","in":"query","description":"Upper end of the range started by players_from.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"year_from","in":"query","description":"Only games published in this year or later.","schema":{"type":"integer"}},{"name":"year_to","in":"query","description":"Only games published in this year or earlier.","schema":{"type":"integer"}},{"name":"time_max","in":"query","description":"Only games that can be finished within this many minutes.","schema":{"type":"integer","minimum":1}},{"name":"age","in":"query","description":"Only games suitable for someone of this age.","schema":{"type":"integer","minimum":0,"maximum":99}},{"name":"illustrated","in":"query","description":"Set to 1 for only games that have a cover image.","schema":{"type":"string","enum":["1"]}},{"name":"cover","in":"query","description":"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`.","schema":{"type":"string","enum":["ok","needs_work","unreviewed","none"]}},{"name":"complexity_min","in":"query","description":"Only games whose average complexity is at least this. Games nobody has voted on are left out.","schema":{"type":"number","minimum":1,"maximum":5},"example":2.5},{"name":"complexity_max","in":"query","description":"Only games whose average complexity is at most this. Games nobody has voted on are left out.","schema":{"type":"number","minimum":1,"maximum":5},"example":3.5},{"name":"rating_min","in":"query","description":"Only games whose average rating is at least this. Games nobody has rated are left out.","schema":{"type":"number","minimum":1,"maximum":10},"example":7},{"name":"lang","in":"query","description":"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.","schema":{"type":"string"},"example":"fr"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":60}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"The category with its games.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/TermWithGames"}}},"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}}}}},"404":{"description":"No category has this slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mechanics":{"get":{"operationId":"list_mechanics","tags":["Mechanics"],"summary":"List mechanics","description":"The mechanics in the catalog with the number of games linked to each, a page at a time.","parameters":[{"name":"order","in":"query","description":"`name` alphabetical, `games` most games first.","schema":{"type":"string","enum":["name","games"],"default":"name"}},{"name":"prefix","in":"query","description":"Only names starting with this text. Case is ignored.","schema":{"type":"string","maxLength":40}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of mechanics.","content":{"application/json":{"schema":{"type":"object","required":["data","total","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TermCount"}},"total":{"type":"integer","description":"How many match, across all pages."},"nextCursor":{"type":["string","null"]}}},"example":{"data":[{"slug":"tile-placement","name":"Tile placement","games":2}],"total":1,"nextCursor":null}}}},"400":{"description":"`cursor` or `order` is not an accepted value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mechanics/{slug}":{"get":{"operationId":"get_mechanic","tags":["Mechanics"],"summary":"Get one mechanic and its games","description":"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.","parameters":[{"name":"slug","in":"path","required":true,"description":"The mechanic's slug, as returned by the API.","schema":{"type":"string"},"example":"tile-placement"},{"name":"order","in":"query","description":"`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.","schema":{"type":"string","enum":["added","new","name","year","oldest","hot","rating","complexity","random"]}},{"name":"seed","in":"query","description":"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.","schema":{"type":"integer","minimum":0,"maximum":2147483646},"example":482913},{"name":"kind","in":"query","description":"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.","schema":{"type":"string","enum":["game","expansion","accessory"]}},{"name":"players","in":"query","description":"Only games that can be played by this many players.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"players_from","in":"query","description":"With players_to: only games that can be played at every count from players_from to players_to. Alone, the same as players.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"players_to","in":"query","description":"Upper end of the range started by players_from.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"year_from","in":"query","description":"Only games published in this year or later.","schema":{"type":"integer"}},{"name":"year_to","in":"query","description":"Only games published in this year or earlier.","schema":{"type":"integer"}},{"name":"time_max","in":"query","description":"Only games that can be finished within this many minutes.","schema":{"type":"integer","minimum":1}},{"name":"age","in":"query","description":"Only games suitable for someone of this age.","schema":{"type":"integer","minimum":0,"maximum":99}},{"name":"illustrated","in":"query","description":"Set to 1 for only games that have a cover image.","schema":{"type":"string","enum":["1"]}},{"name":"cover","in":"query","description":"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`.","schema":{"type":"string","enum":["ok","needs_work","unreviewed","none"]}},{"name":"complexity_min","in":"query","description":"Only games whose average complexity is at least this. Games nobody has voted on are left out.","schema":{"type":"number","minimum":1,"maximum":5},"example":2.5},{"name":"complexity_max","in":"query","description":"Only games whose average complexity is at most this. Games nobody has voted on are left out.","schema":{"type":"number","minimum":1,"maximum":5},"example":3.5},{"name":"rating_min","in":"query","description":"Only games whose average rating is at least this. Games nobody has rated are left out.","schema":{"type":"number","minimum":1,"maximum":10},"example":7},{"name":"lang","in":"query","description":"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.","schema":{"type":"string"},"example":"fr"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":60}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"The mechanic with its games.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/TermWithGames"}}},"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}}}}},"404":{"description":"No mechanic has this slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/awards":{"get":{"operationId":"list_awards","tags":["Awards"],"summary":"List awards","description":"The awards in the catalog with the number of games linked to each, a page at a time.","parameters":[{"name":"order","in":"query","description":"`name` alphabetical, `games` most games first.","schema":{"type":"string","enum":["name","games"],"default":"name"}},{"name":"prefix","in":"query","description":"Only names starting with this text. Case is ignored.","schema":{"type":"string","maxLength":40}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of awards.","content":{"application/json":{"schema":{"type":"object","required":["data","total","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TermCount"}},"total":{"type":"integer","description":"How many match, across all pages."},"nextCursor":{"type":["string","null"]}}},"example":{"data":[{"slug":"spiel-des-jahres","name":"Spiel des Jahres","games":2}],"total":1,"nextCursor":null}}}},"400":{"description":"`cursor` or `order` is not an accepted value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/awards/{slug}":{"get":{"operationId":"get_award","tags":["Awards"],"summary":"Get one award and its games","description":"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.","parameters":[{"name":"slug","in":"path","required":true,"description":"The award's slug, as returned by the API.","schema":{"type":"string"},"example":"spiel-des-jahres"},{"name":"order","in":"query","description":"`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.","schema":{"type":"string","enum":["added","new","name","year","oldest","hot","rating","complexity","random"]}},{"name":"seed","in":"query","description":"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.","schema":{"type":"integer","minimum":0,"maximum":2147483646},"example":482913},{"name":"kind","in":"query","description":"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.","schema":{"type":"string","enum":["game","expansion","accessory"]}},{"name":"players","in":"query","description":"Only games that can be played by this many players.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"players_from","in":"query","description":"With players_to: only games that can be played at every count from players_from to players_to. Alone, the same as players.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"players_to","in":"query","description":"Upper end of the range started by players_from.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"year_from","in":"query","description":"Only games published in this year or later.","schema":{"type":"integer"}},{"name":"year_to","in":"query","description":"Only games published in this year or earlier.","schema":{"type":"integer"}},{"name":"time_max","in":"query","description":"Only games that can be finished within this many minutes.","schema":{"type":"integer","minimum":1}},{"name":"age","in":"query","description":"Only games suitable for someone of this age.","schema":{"type":"integer","minimum":0,"maximum":99}},{"name":"illustrated","in":"query","description":"Set to 1 for only games that have a cover image.","schema":{"type":"string","enum":["1"]}},{"name":"cover","in":"query","description":"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`.","schema":{"type":"string","enum":["ok","needs_work","unreviewed","none"]}},{"name":"complexity_min","in":"query","description":"Only games whose average complexity is at least this. Games nobody has voted on are left out.","schema":{"type":"number","minimum":1,"maximum":5},"example":2.5},{"name":"complexity_max","in":"query","description":"Only games whose average complexity is at most this. Games nobody has voted on are left out.","schema":{"type":"number","minimum":1,"maximum":5},"example":3.5},{"name":"rating_min","in":"query","description":"Only games whose average rating is at least this. Games nobody has rated are left out.","schema":{"type":"number","minimum":1,"maximum":10},"example":7},{"name":"lang","in":"query","description":"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.","schema":{"type":"string"},"example":"fr"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":60}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"The award with its games.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AwardWithGames"}}},"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"}}]}]}}}}},"301":{"description":"The slug is a prize that now belongs to an award: `Location` is that award's address."},"404":{"description":"No award has this slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/families":{"get":{"operationId":"list_families","tags":["Families"],"summary":"List families","description":"The families in the catalog with the number of games linked to each, a page at a time.","parameters":[{"name":"order","in":"query","description":"`name` alphabetical, `games` most games first.","schema":{"type":"string","enum":["name","games"],"default":"name"}},{"name":"prefix","in":"query","description":"Only names starting with this text. Case is ignored.","schema":{"type":"string","maxLength":40}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of families.","content":{"application/json":{"schema":{"type":"object","required":["data","total","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TermCount"}},"total":{"type":"integer","description":"How many match, across all pages."},"nextCursor":{"type":["string","null"]}}},"example":{"data":[{"slug":"catan-series","name":"Catan series","games":2}],"total":1,"nextCursor":null}}}},"400":{"description":"`cursor` or `order` is not an accepted value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/families/{slug}":{"get":{"operationId":"get_family","tags":["Families"],"summary":"Get one family and its games","description":"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.","parameters":[{"name":"slug","in":"path","required":true,"description":"The family's slug, as returned by the API.","schema":{"type":"string"},"example":"catan-series"},{"name":"order","in":"query","description":"`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.","schema":{"type":"string","enum":["added","new","name","year","oldest","hot","rating","complexity","random"]}},{"name":"seed","in":"query","description":"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.","schema":{"type":"integer","minimum":0,"maximum":2147483646},"example":482913},{"name":"kind","in":"query","description":"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.","schema":{"type":"string","enum":["game","expansion","accessory"]}},{"name":"players","in":"query","description":"Only games that can be played by this many players.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"players_from","in":"query","description":"With players_to: only games that can be played at every count from players_from to players_to. Alone, the same as players.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"players_to","in":"query","description":"Upper end of the range started by players_from.","schema":{"type":"integer","minimum":1,"maximum":99}},{"name":"year_from","in":"query","description":"Only games published in this year or later.","schema":{"type":"integer"}},{"name":"year_to","in":"query","description":"Only games published in this year or earlier.","schema":{"type":"integer"}},{"name":"time_max","in":"query","description":"Only games that can be finished within this many minutes.","schema":{"type":"integer","minimum":1}},{"name":"age","in":"query","description":"Only games suitable for someone of this age.","schema":{"type":"integer","minimum":0,"maximum":99}},{"name":"illustrated","in":"query","description":"Set to 1 for only games that have a cover image.","schema":{"type":"string","enum":["1"]}},{"name":"cover","in":"query","description":"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`.","schema":{"type":"string","enum":["ok","needs_work","unreviewed","none"]}},{"name":"complexity_min","in":"query","description":"Only games whose average complexity is at least this. Games nobody has voted on are left out.","schema":{"type":"number","minimum":1,"maximum":5},"example":2.5},{"name":"complexity_max","in":"query","description":"Only games whose average complexity is at most this. Games nobody has voted on are left out.","schema":{"type":"number","minimum":1,"maximum":5},"example":3.5},{"name":"rating_min","in":"query","description":"Only games whose average rating is at least this. Games nobody has rated are left out.","schema":{"type":"number","minimum":1,"maximum":10},"example":7},{"name":"lang","in":"query","description":"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.","schema":{"type":"string"},"example":"fr"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":60}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"The family with its games.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/TermWithGames"}}},"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}}}}},"404":{"description":"No family has this slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/honours/recent":{"get":{"operationId":"list_recent_honours","tags":["Games"],"summary":"Games with the most recent award wins","description":"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.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":30,"default":10}},{"name":"lang","in":"query","description":"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.","schema":{"type":"string"},"example":"fr"}],"responses":{"200":{"description":"Winning games, most recent first.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["game","honour"],"properties":{"game":{"$ref":"#/components/schemas/GameSummary"},"honour":{"type":"object","required":["award","category","year","result"],"properties":{"award":{"type":"object","required":["slug","name"],"properties":{"slug":{"type":"string"},"name":{"type":"string"}}},"category":{"type":["string","null"]},"year":{"type":"integer"},"result":{"type":"string","enum":["winner"]}}}}}}}},"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"}}]}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/hot":{"get":{"operationId":"list_hot_games","tags":["Games"],"summary":"The games people are looking at now","description":"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`.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"lang","in":"query","description":"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.","schema":{"type":"string"},"example":"fr"}],"responses":{"200":{"description":"The hottest games, hottest first.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GameSummary"}}}},"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}}]}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/rating":{"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"}],"put":{"operationId":"rate_game","tags":["Ratings and polls"],"summary":"Rate a game","description":"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.","security":[{"session":[]},{"apiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rating"],"properties":{"rating":{"type":"number","minimum":1,"maximum":10,"multipleOf":0.1}}},"example":{"rating":7.5}}}},"responses":{"200":{"description":"The rating was stored.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["rating"],"properties":{"rating":{"type":"number"}}}}},"example":{"data":{"rating":7.5}}}}},"400":{"description":"`rating` is not a number from 1 to 10 with at most one decimal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The member has not confirmed their email address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"unrate_game","tags":["Ratings and polls"],"summary":"Remove your rating of a game","security":[{"session":[]},{"apiToken":[]}],"responses":{"200":{"description":"The member has no rating on this game.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"},"example":{"ok":true}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/complexity":{"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"}],"put":{"operationId":"vote_complexity","tags":["Ratings and polls"],"summary":"Vote on a game's complexity","description":"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.","security":[{"session":[]},{"apiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["weight"],"properties":{"weight":{"type":"integer","minimum":1,"maximum":5}}},"example":{"weight":3}}}},"responses":{"200":{"description":"The vote was counted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"},"example":{"ok":true}}}},"400":{"description":"`weight` is not a whole number from 1 to 5.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"unvote_complexity","tags":["Ratings and polls"],"summary":"Take back your vote on a game's complexity","security":[{"session":[]},{"apiToken":[]}],"responses":{"200":{"description":"The member has no vote on this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"},"example":{"ok":true}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/polls/age":{"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"}],"put":{"operationId":"vote_recommended_age","tags":["Ratings and polls"],"summary":"Vote on a game's recommended age","description":"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.","security":[{"session":[]},{"apiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["age"],"properties":{"age":{"type":"integer","minimum":1,"maximum":21}}},"example":{"age":10}}}},"responses":{"200":{"description":"The vote was counted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"},"example":{"ok":true}}}},"400":{"description":"`age` is not a whole number from 1 to 21.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"unvote_recommended_age","tags":["Ratings and polls"],"summary":"Take back your vote on a game's recommended age","security":[{"session":[]},{"apiToken":[]}],"responses":{"200":{"description":"The member has no vote on this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"},"example":{"ok":true}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/polls/language":{"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"}],"put":{"operationId":"vote_language_dependence","tags":["Ratings and polls"],"summary":"Vote on a game's language dependence","description":"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.","security":[{"session":[]},{"apiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["level"],"properties":{"level":{"type":"integer","minimum":1,"maximum":5}}},"example":{"level":2}}}},"responses":{"200":{"description":"The vote was counted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"},"example":{"ok":true}}}},"400":{"description":"`level` is not a whole number from 1 to 5.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"unvote_language_dependence","tags":["Ratings and polls"],"summary":"Take back your vote on a game's language dependence","security":[{"session":[]},{"apiToken":[]}],"responses":{"200":{"description":"The member has no vote on this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"},"example":{"ok":true}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/polls/players":{"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"}],"put":{"operationId":"vote_player_counts","tags":["Ratings and polls"],"summary":"Vote on how many players a game is good with","description":"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.","security":[{"session":[]},{"apiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["votes"],"properties":{"votes":{"type":"array","minItems":1,"maxItems":20,"description":"Each number of players at most once.","items":{"type":"object","required":["players","vote"],"properties":{"players":{"type":"integer","minimum":1,"maximum":20},"vote":{"type":"string","enum":["best","recommended","not_recommended"]}}}}}},"example":{"votes":[{"players":2,"vote":"not_recommended"},{"players":3,"vote":"recommended"},{"players":4,"vote":"best"}]}}}},"responses":{"200":{"description":"The ballot was counted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"},"example":{"ok":true}}}},"400":{"description":"The ballot is empty, repeats a number of players, or has a value out of range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"unvote_player_counts","tags":["Ratings and polls"],"summary":"Take back your ballot on player counts","security":[{"session":[]},{"apiToken":[]}],"responses":{"200":{"description":"The member has no ballot on this game.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"},"example":{"ok":true}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/collection":{"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"}],"put":{"operationId":"set_collection_status","tags":["Collections"],"summary":"Put a game in your collection","description":"Marks the game with one or more statuses. The list sent replaces the game's previous statuses.","security":[{"session":[]},{"apiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["statuses"],"properties":{"statuses":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/CollectionStatus"}}}},"example":{"statuses":["owned","wishlist"]}}}},"responses":{"200":{"description":"The statuses now on the game.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["statuses"],"properties":{"statuses":{"type":"array","items":{"$ref":"#/components/schemas/CollectionStatus"}}}}}},"example":{"data":{"statuses":["owned","wishlist"]}}}}},"400":{"description":"`statuses` is empty or names a status other than `owned` and `wishlist` (code `invalid_collection_status`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"remove_from_collection","tags":["Collections"],"summary":"Take a game out of your collection","description":"Removes every status the member put on the game.","security":[{"session":[]},{"apiToken":[]}],"responses":{"200":{"description":"The game is not in the member's collection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"},"example":{"ok":true}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account/ratings":{"get":{"operationId":"list_ratings","tags":["Ratings and polls"],"summary":"List your ratings","description":"The games the member has rated, with the rating and when it was last given. Never served from the shared cache.","security":[{"session":[]},{"apiToken":[]}],"parameters":[{"name":"order","in":"query","description":"`recent`: the latest rating first. `rating`: the highest rating first.","schema":{"type":"string","enum":["recent","rating"],"default":"recent"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of the member's ratings.","content":{"application/json":{"schema":{"type":"object","required":["data","total","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","required":["game","rating","ratedAt"],"properties":{"game":{"$ref":"#/components/schemas/GameSummary"},"rating":{"type":"number","minimum":1,"maximum":10,"description":"The member's rating, out of 10."},"ratedAt":{"type":"string","format":"date-time","description":"When the rating was last given."}}}},"total":{"type":"integer","description":"How many games the member has rated."},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."}}},"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}}}},"400":{"description":"`order` or `cursor` is not an accepted value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account/collection":{"get":{"operationId":"list_collection","tags":["Collections"],"summary":"List your collection","description":"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.","security":[{"session":[]},{"apiToken":[]}],"parameters":[{"name":"status","in":"query","description":"Only games carrying this status.","schema":{"$ref":"#/components/schemas/CollectionStatus"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of the member's collection.","content":{"application/json":{"schema":{"type":"object","required":["data","total","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CollectionItem"}},"total":{"type":"integer","description":"How many games match, across all pages."},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."}}},"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}}}},"400":{"description":"`status` or `cursor` is not an accepted value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/plays":{"post":{"operationId":"log_play","tags":["Plays"],"summary":"Log a play of a game","description":"Records that the member played the game on a day. The game's `plays` count follows at once.","security":[{"session":[]},{"apiToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["date"],"properties":{"date":{"type":"string","format":"date","description":"The day it was played. Not in the future."},"players":{"type":"integer","minimum":1,"maximum":99},"minutes":{"type":"integer","minimum":1,"maximum":10000,"description":"How long the play lasted."},"note":{"type":"string","maxLength":500,"description":"Plain text. Visible to the member only."}}},"example":{"date":"2026-11-20","players":4,"minutes":75,"note":"Longest road won it."}}}},"responses":{"201":{"description":"The play was logged.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","date","players","minutes","note"],"properties":{"id":{"type":"string","format":"uuid"},"date":{"type":"string","format":"date"},"players":{"type":["integer","null"]},"minutes":{"type":["integer","null"]},"note":{"type":["string","null"]}}}}},"example":{"data":{"id":"7d0a2b1e-1f8e-4d55-9a53-0e5d0f5f7c21","date":"2026-11-20","players":4,"minutes":75,"note":"Longest road won it."}}}}},"400":{"description":"The date is missing, malformed or in the future, or another value is out of range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account/plays":{"get":{"operationId":"list_plays","tags":["Plays"],"summary":"List your plays","description":"The member's logged plays, most recent day first. Never served from the shared cache.","security":[{"session":[]},{"apiToken":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of the member's plays.","content":{"application/json":{"schema":{"type":"object","required":["data","total","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Play"}},"total":{"type":"integer"},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."}}},"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}}}},"400":{"description":"`cursor` is not a value this API issued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account/plays/{id}":{"delete":{"operationId":"delete_play","tags":["Plays"],"summary":"Delete one of your plays","security":[{"session":[]},{"apiToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The play is not in the member's log.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"},"example":{"ok":true}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account/games/{id}":{"get":{"operationId":"get_my_answers","tags":["Accounts"],"summary":"What you said about a game","description":"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.","security":[{"session":[]},{"apiToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"}],"responses":{"200":{"description":"The member's answers about the game.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/MyAnswers"}}},"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","likes":12,"dislikes":1,"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"}]}}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/comments":{"get":{"operationId":"list_game_comments","tags":["Comments"],"summary":"List a game's comments","description":"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.","parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of comments.","content":{"application/json":{"schema":{"type":"object","required":["data","total","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Comment"}},"total":{"type":"integer"},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."}}},"example":{"data":[{"id":"4a0e7f0c-64d0-4f0e-8a51-6f4b1b2f9d10","author":"Ana","text":"Trade wood for sheep.","rating":7.5,"likes":4,"dislikes":0,"createdAt":"2026-11-20T18:04:11.120Z","updatedAt":"2026-11-20T18:04:11.120Z"}],"total":1,"nextCursor":null}}}},"400":{"description":"`cursor` is not a value this API issued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/comment":{"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"}],"put":{"operationId":"write_comment","tags":["Comments"],"summary":"Write or edit your comment on a game","description":"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.","security":[{"session":[]},{"apiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":2000}}},"example":{"text":"Trade wood for sheep."}}}},"responses":{"200":{"description":"The comment as stored.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","text","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"text":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}},"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"}}}}},"400":{"description":"The text is empty or longer than 2 000 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The member has not confirmed their email address, or a moderator removed their comment on this game.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited, or more than five posts in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"delete_comment","tags":["Comments"],"summary":"Delete your comment on a game","security":[{"session":[]},{"apiToken":[]}],"responses":{"200":{"description":"The member has no visible comment on this game.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"},"example":{"ok":true}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/videos":{"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"}],"get":{"operationId":"list_game_videos","tags":["Videos"],"summary":"List a game's videos","description":"Videos about the game that a moderator has approved, newest first.","parameters":[{"name":"category","in":"query","description":"Only videos of this kind.","schema":{"$ref":"#/components/schemas/VideoCategory"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of videos.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Video"}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."}}},"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","likes":12,"dislikes":1,"createdAt":"2026-11-20T18:04:11.120Z"}],"nextCursor":null}}}},"400":{"description":"`category` or `cursor` is not an accepted value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"submit_video","tags":["Videos"],"summary":"Suggest a video for a game","description":"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.","security":[{"session":[]},{"apiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","title","language","category"],"properties":{"url":{"type":"string","format":"uri","description":"A YouTube or Vimeo video page."},"title":{"type":"string","minLength":2,"maxLength":120},"language":{"type":"string","description":"The language spoken, as a code such as \"en\" or \"pt-BR\"."},"category":{"$ref":"#/components/schemas/VideoCategory"}}},"example":{"url":"https://youtu.be/dQw4w9WgXcQ","title":"How to play Catan","language":"en","category":"how_to_play"}}}},"responses":{"201":{"description":"The video was stored and waits for review.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","provider","videoId","url","title","language","category","status"],"properties":{"id":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["youtube","vimeo"]},"videoId":{"type":"string"},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"language":{"type":"string"},"category":{"$ref":"#/components/schemas/VideoCategory"},"status":{"type":"string","enum":["pending","approved"]}}}}},"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"}}}}},"400":{"description":"The address is not a YouTube or Vimeo video, or the title, language or category is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The member has not confirmed their email address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"This video was already sent in for this game.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited, more than five posts in a minute, or 20 videos already sent today.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/playlists":{"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"}],"get":{"operationId":"list_game_playlists","tags":["Music"],"summary":"List music to play a game to","description":"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}`.","parameters":[{"name":"provider","in":"query","description":"Only playlists on this service.","schema":{"$ref":"#/components/schemas/MusicProvider"},"example":"spotify"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of playlists.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Playlist"}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."}}},"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}}}},"400":{"description":"`provider` or `cursor` is not an accepted value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"add_playlist","tags":["Music"],"summary":"Add a playlist to a game","description":"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.","security":[{"session":[]},{"apiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"A playlist or album page on Apple Music, Spotify or YouTube."},"title":{"type":"string","minLength":2,"maxLength":120,"description":"A title to fall back on when the service does not give the playlist's own."}}},"example":{"url":"https://open.spotify.com/playlist/37i9dQZF1DX4sWSpwq3LiO?si=abc","title":"Island traders: calm medieval folk"}}}},"responses":{"201":{"description":"The playlist is listed.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Playlist"}}},"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"}}}}},"400":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The member has not confirmed their email address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"This playlist is already listed for this game, or was and is no longer shown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited, more than five posts in a minute, or 20 playlists already added today.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/merge-proposals":{"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"}],"post":{"operationId":"propose_merge","tags":["Corrections"],"summary":"Say a game is the same as another entry","description":"The game in the address and the one named by `sameAs` are the same game listed twice. A moderator merges them or keeps them apart; the merged entry's address then leads to the kept one. `mergeNow` (moderators only) merges at once: the entry kept is the one with an English main name, then more facts, then the older.","security":[{"session":[]},{"apiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sameAs"],"properties":{"sameAs":{"type":"string","description":"The other entry's id or address (slug)."},"note":{"type":"string","maxLength":500,"description":"Why, for the moderator."},"mergeNow":{"type":"boolean","description":"Moderators only: merge without review."}}},"example":{"sameAs":"a-feast-for-odin","note":"Odin is the short name on the 2023 box."}}}},"responses":{"200":{"description":"Merged at once (`mergeNow`).","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["status","kept"],"properties":{"status":{"type":"string","enum":["merged"]},"kept":{"type":"object","required":["id","slug","name"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}}}}}}}}}},"201":{"description":"The proposal, waiting for a moderator.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending"]}}}}},"example":{"data":{"id":"9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f","status":"pending"}}}}},"400":{"description":"`sameAs` names no other game of the catalog, or the note is too long.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The member has not confirmed their email address, or asked for `mergeNow` without being a moderator.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A proposal about these two games is already waiting, or the merge was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The merge could not be made now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/comments/{comment}/vote":{"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"},{"name":"comment","in":"path","required":true,"description":"The comment's id.","schema":{"type":"string","format":"uuid"},"example":"4a0e7f0c-64d0-4f0e-8a51-6f4b1b2f9d10"}],"put":{"operationId":"vote_comment","tags":["Comments"],"summary":"Like or dislike a comment","description":"`up` likes the comment, `down` dislikes it. One vote per member; voting again replaces it. Members cannot vote on what they added themselves. A vote that brings dislikes 3 or more ahead of likes, once at least 5 members have voted, hides the comment (`status` becomes `hidden`) until a moderator shows it again or removes it.","security":[{"session":[]},{"apiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["vote"],"properties":{"vote":{"type":"string","enum":["up","down"]}}},"example":{"vote":"up"}}}},"responses":{"200":{"description":"The comment's counts after the vote.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/VoteStanding"}}},"example":{"data":{"likes":4,"dislikes":1,"status":"visible"}}}}},"400":{"description":"`vote` is not \"up\" or \"down\".","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The comment is the member's own.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id, or no such comment is shown on it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"unvote_comment","tags":["Comments"],"summary":"Take back your vote on a comment","security":[{"session":[]},{"apiToken":[]}],"responses":{"200":{"description":"The comment's counts with the member's vote taken out.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/VoteStanding"}}},"example":{"data":{"likes":3,"dislikes":1,"status":"visible"}}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The comment is the member's own.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id, or no such comment is shown on it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/videos/{video}/vote":{"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"},{"name":"video","in":"path","required":true,"description":"The video's id.","schema":{"type":"string","format":"uuid"},"example":"0b0f5a51-64a5-4f6b-9a39-0a4d6c5c0f11"}],"put":{"operationId":"vote_video","tags":["Videos"],"summary":"Like or dislike a video","description":"`up` likes the video, `down` dislikes it. One vote per member; voting again replaces it. Members cannot vote on what they added themselves. A vote that brings dislikes 3 or more ahead of likes, once at least 5 members have voted, hides the video (`status` becomes `hidden`) until a moderator shows it again or removes it.","security":[{"session":[]},{"apiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["vote"],"properties":{"vote":{"type":"string","enum":["up","down"]}}},"example":{"vote":"up"}}}},"responses":{"200":{"description":"The video's counts after the vote.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/VoteStanding"}}},"example":{"data":{"likes":4,"dislikes":1,"status":"visible"}}}}},"400":{"description":"`vote` is not \"up\" or \"down\".","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The video is the member's own.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id, or no such video is shown on it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"unvote_video","tags":["Videos"],"summary":"Take back your vote on a video","security":[{"session":[]},{"apiToken":[]}],"responses":{"200":{"description":"The video's counts with the member's vote taken out.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/VoteStanding"}}},"example":{"data":{"likes":3,"dislikes":1,"status":"visible"}}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The video is the member's own.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id, or no such video is shown on it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/photos/{photo}/vote":{"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"},{"name":"photo","in":"path","required":true,"description":"The photo's id.","schema":{"type":"string","format":"uuid"},"example":"2f6a3c1e-8d4b-4b8f-9a0e-1c2d3e4f5a6b"}],"put":{"operationId":"vote_photo","tags":["Photos"],"summary":"Like or dislike a photo","description":"`up` likes the photo, `down` dislikes it. One vote per member; voting again replaces it. Members cannot vote on what they added themselves. A vote that brings dislikes 3 or more ahead of likes, once at least 5 members have voted, hides the photo (`status` becomes `hidden`) until a moderator shows it again or removes it.","security":[{"session":[]},{"apiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["vote"],"properties":{"vote":{"type":"string","enum":["up","down"]}}},"example":{"vote":"up"}}}},"responses":{"200":{"description":"The photo's counts after the vote.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/VoteStanding"}}},"example":{"data":{"likes":4,"dislikes":1,"status":"visible"}}}}},"400":{"description":"`vote` is not \"up\" or \"down\".","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The photo is the member's own.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id, or no such photo is shown on it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"unvote_photo","tags":["Photos"],"summary":"Take back your vote on a photo","security":[{"session":[]},{"apiToken":[]}],"responses":{"200":{"description":"The photo's counts with the member's vote taken out.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/VoteStanding"}}},"example":{"data":{"likes":3,"dislikes":1,"status":"visible"}}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The photo is the member's own.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id, or no such photo is shown on it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/playlists/{playlist}/vote":{"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"},{"name":"playlist","in":"path","required":true,"description":"The playlist's id.","schema":{"type":"string","format":"uuid"},"example":"7d1c1a0e-2f0b-4d39-9a56-5a8d2b9d7c21"}],"put":{"operationId":"vote_playlist","tags":["Music"],"summary":"Vote a playlist up or down","description":"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.","security":[{"session":[]},{"apiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["vote"],"properties":{"vote":{"type":"string","enum":["up","down"]}}},"example":{"vote":"up"}}}},"responses":{"200":{"description":"The playlist's standing after the vote.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PlaylistStanding"}}},"example":{"data":{"score":5,"votes":7,"status":"visible"}}}}},"400":{"description":"`vote` is not \"up\" or \"down\".","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id, or it lists no such playlist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"unvote_playlist","tags":["Music"],"summary":"Take back your vote on a playlist","security":[{"session":[]},{"apiToken":[]}],"responses":{"200":{"description":"The playlist's standing with the member's vote taken out.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PlaylistStanding"}}},"example":{"data":{"score":4,"votes":6,"status":"visible"}}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id, or it lists no such playlist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/rulebooks":{"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"}],"get":{"operationId":"list_game_rulebooks","tags":["Rules"],"summary":"List a game's rulebooks","description":"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}`.","parameters":[{"name":"language","in":"query","description":"Only rulebooks written in this language.","schema":{"type":"string","description":"A language code such as \"en\", \"fr\" or \"pt-BR\"."},"example":"fr"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of rulebooks.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Rulebook"}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page. Null on the last page."}}},"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}}}},"400":{"description":"`language` or `cursor` is not an accepted value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"upload_rulebook","tags":["Rules"],"summary":"Upload a rulebook for a game","description":"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.","security":[{"session":[]},{"apiToken":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","language"],"properties":{"file":{"type":"array","description":"One PDF, or 1 to 20 images.","minItems":1,"maxItems":20,"items":{"type":"string","format":"binary"}},"language":{"type":"string","description":"A language code such as \"en\", \"fr\" or \"pt-BR\"."},"edition":{"type":"string","maxLength":120,"description":"Which edition or printing these rules belong to. Optional."}}},"example":{"language":"en","edition":"5th edition, 2015"}}}},"responses":{"201":{"description":"The rulebook was stored and waits for review.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/OwnRulebook"},{"type":"object","properties":{"status":{"type":"string","enum":["pending","approved"]}}}]}}},"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"}}}}},"400":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The member has not confirmed their email address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The files weigh more than 25 MB together, or an image more than 5 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"A file is not a PDF, JPEG, PNG or WebP.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited, or the member already uploaded 10 rulebooks today.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/rulebooks/uploads":{"parameters":[{"name":"id","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"}],"post":{"operationId":"start_rulebook_upload","tags":["Rules"],"summary":"Start sending a large PDF rulebook in parts","description":"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.","security":[{"session":[]},{"apiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["size","language"],"properties":{"size":{"type":"integer","minimum":1,"maximum":209715200,"description":"Bytes of the whole file."},"language":{"type":"string","description":"A language code such as \"en\", \"fr\" or \"pt-BR\"."},"edition":{"type":"string","maxLength":120,"description":"Which edition or printing these rules belong to. Optional."}}},"example":{"size":61250112,"language":"en","edition":"5th edition, 2015"}}}},"responses":{"201":{"description":"The upload is open.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/RulebookUpload"}}},"example":{"data":{"id":"c2b7e5a4-3f1d-4b7c-8f0a-9e6d5c4b3a21","token":"9f2c61f0a4b84d7e9c3a5b1d7e2f4a6c8b0d2e4f6a8c0e2f4a6b8d0c2e4f6a81","partSize":8388608,"parts":8,"expiresAt":"2026-11-21T20:04:11.120Z"}}}}},"400":{"description":"The size, the language or the edition is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The member has not confirmed their email address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The file is larger than 200 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited, more than five starts in a minute, three uploads already under way, or 10 rulebooks already added today.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rulebook-uploads/{upload}/parts/{part}":{"parameters":[{"name":"upload","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The upload's id, from `POST /games/{id}/rulebooks/uploads`."},{"name":"part","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":25},"description":"The part's number, from 1 to `parts`."}],"put":{"operationId":"send_rulebook_upload_part","tags":["Rules"],"summary":"Send one part of a large rulebook","description":"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.","security":[{"uploadToken":[]}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"The part is stored.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["part"],"properties":{"part":{"type":"integer"}}}}},"example":{"data":{"part":3}}}}},"400":{"description":"The part number is not a number, the body is shorter than the part should be, or it did not arrive whole.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The `x-upload-token` header is missing, or the token has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The member has not confirmed their email address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No upload has this id and token: it was completed, cancelled or discarded, or the token is another upload's.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is longer than this part should be, or the upload has fewer parts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The first part is not the start of a PDF.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rulebook-uploads/{upload}/complete":{"parameters":[{"name":"upload","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The upload's id, from `POST /games/{id}/rulebooks/uploads`."}],"post":{"operationId":"complete_rulebook_upload","tags":["Rules"],"summary":"Finish a large rulebook once its parts are sent","description":"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.","security":[{"uploadToken":[]}],"responses":{"201":{"description":"The rulebook was stored and waits for review.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/OwnRulebook"},{"type":"object","properties":{"status":{"type":"string","enum":["pending","approved"]}}}]}}},"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"}}}}},"400":{"description":"The parts do not add up to the size announced. The upload is discarded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The `x-upload-token` header is missing, or the token has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The member has not confirmed their email address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No upload has this id and token: it was completed, cancelled or discarded, or the token is another upload's.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Some parts have not arrived (`missing` lists their numbers), or the parts could not be put together.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"missing":{"type":"array","items":{"type":"integer"}}}},"example":{"error":"Some parts have not arrived yet. Send them first.","missing":[4,7]}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rulebook-uploads/{upload}":{"parameters":[{"name":"upload","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The upload's id, from `POST /games/{id}/rulebooks/uploads`."}],"delete":{"operationId":"cancel_rulebook_upload","tags":["Rules"],"summary":"Cancel a large rulebook upload","description":"Discards the upload and the parts already sent. The token stops working.","security":[{"uploadToken":[]}],"responses":{"200":{"description":"The upload is discarded.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}},"example":{"ok":true}}}},"401":{"description":"The `x-upload-token` header is missing, or the token has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The member has not confirmed their email address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No upload has this id and token: it was completed, cancelled or discarded, or the token is another upload's.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/corrections":{"post":{"operationId":"suggest_correction","tags":["Corrections"],"summary":"Suggest a correction to a game","description":"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.","security":[{"session":[]},{"apiToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The game's id, as returned in every game object. The game's slug is accepted too.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["changes"],"properties":{"changes":{"type":"array","minItems":1,"maxItems":20,"items":{"oneOf":[{"type":"object","title":"A fact","required":["type","field","old","new"],"properties":{"type":{"type":"string","const":"field"},"field":{"type":"string","enum":["name","yearPublished","minPlayers","maxPlayers","minPlaytime","maxPlaytime","minAge","tagline","description","officialUrl","ean","kind"]},"old":{"type":["string","integer","null"],"description":"The value the game showed when you wrote the correction. The correction is refused when the game no longer says this."},"new":{"type":["string","integer","null"],"description":"The value you propose, held to the rules of the field: `yearPublished` -3500 to 2100, players 1 to 999, playing time in minutes, `minAge` 0 to 99, `tagline` one line of 160 characters, `description` plain text of 5,000 characters, `officialUrl` an http(s) address, `ean` a valid EAN-13 (a 12-digit UPC is accepted), `kind` one of game, expansion, accessory. Null says the fact is unknown; `name` and `kind` cannot be null."},"source":{"type":"string","format":"uri","maxLength":500,"description":"Where you read it. Optional."},"note":{"type":"string","maxLength":500,"description":"Optional."}}},{"type":"object","title":"A credit","required":["type","action","kind"],"properties":{"type":{"type":"string","const":"credit"},"action":{"type":"string","enum":["add","remove"]},"kind":{"type":"string","enum":["designer","artist","publisher","category","mechanic","family"]},"slug":{"type":"string","description":"The slug of an existing entry. Required to remove a credit."},"name":{"type":"string","maxLength":200,"description":"To add someone or something the catalog does not list yet."},"source":{"type":"string","format":"uri","maxLength":500,"description":"Where you read it. Optional."},"note":{"type":"string","maxLength":500,"description":"Optional."}}},{"type":"object","title":"An alternate name","required":["type","language","name"],"properties":{"type":{"type":"string","const":"name"},"language":{"type":"string","description":"A language code such as \"fr\" or \"pt-br\"."},"name":{"type":"string","maxLength":300},"source":{"type":"string","format":"uri","maxLength":500,"description":"Where you read it. Optional."},"note":{"type":"string","maxLength":500,"description":"Optional."}}}]}},"textDeclared":{"type":"boolean","description":"Must be true when a description is proposed: you wrote the text, or it is free to reuse."}}},"example":{"changes":[{"type":"field","field":"yearPublished","old":1994,"new":1995,"source":"https://www.catan.com/about-us"},{"type":"credit","action":"add","kind":"artist","name":"Michael Menzel"}]}}}},"responses":{"201":{"description":"The correction waits for a moderator.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","status","fromPublisher","changes"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","const":"pending"},"fromPublisher":{"type":["string","null"],"description":"The publisher the member verifiably represents, when the game is credited to it."},"changes":{"type":"array","items":{"oneOf":[{"type":"object","title":"A fact","required":["type","field","old","new"],"properties":{"type":{"type":"string","const":"field"},"field":{"type":"string","enum":["name","yearPublished","minPlayers","maxPlayers","minPlaytime","maxPlaytime","minAge","tagline","description","officialUrl","ean","kind"]},"old":{"type":["string","integer","null"],"description":"The value the game showed when you wrote the correction. The correction is refused when the game no longer says this."},"new":{"type":["string","integer","null"],"description":"The value you propose, held to the rules of the field: `yearPublished` -3500 to 2100, players 1 to 999, playing time in minutes, `minAge` 0 to 99, `tagline` one line of 160 characters, `description` plain text of 5,000 characters, `officialUrl` an http(s) address, `ean` a valid EAN-13 (a 12-digit UPC is accepted), `kind` one of game, expansion, accessory. Null says the fact is unknown; `name` and `kind` cannot be null."},"source":{"type":"string","format":"uri","maxLength":500,"description":"Where you read it. Optional."},"note":{"type":"string","maxLength":500,"description":"Optional."}}},{"type":"object","title":"A credit","required":["type","action","kind"],"properties":{"type":{"type":"string","const":"credit"},"action":{"type":"string","enum":["add","remove"]},"kind":{"type":"string","enum":["designer","artist","publisher","category","mechanic","family"]},"slug":{"type":"string","description":"The slug of an existing entry. Required to remove a credit."},"name":{"type":"string","maxLength":200,"description":"To add someone or something the catalog does not list yet."},"source":{"type":"string","format":"uri","maxLength":500,"description":"Where you read it. Optional."},"note":{"type":"string","maxLength":500,"description":"Optional."}}},{"type":"object","title":"An alternate name","required":["type","language","name"],"properties":{"type":{"type":"string","const":"name"},"language":{"type":"string","description":"A language code such as \"fr\" or \"pt-br\"."},"name":{"type":"string","maxLength":300},"source":{"type":"string","format":"uri","maxLength":500,"description":"Where you read it. Optional."},"note":{"type":"string","maxLength":500,"description":"Optional."}}}]}}}}}}}}},"400":{"description":"A change is not valid; the message says which and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The member has not confirmed their email address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The game no longer says what `old` states, or already is as proposed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited, or the member already suggested 20 corrections today.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{id}/history":{"get":{"operationId":"get_game_history","tags":["Corrections"],"summary":"List the accepted corrections of a game","description":"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.","parameters":[{"name":"id","in":"path","required":true,"description":"The game's id, as returned in every game object. The game's slug is accepted too.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"}],"responses":{"200":{"description":"The game's accepted corrections.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","date","contributor","fromPublisher","changes"],"properties":{"id":{"type":"string","format":"uuid"},"date":{"type":"string","format":"date-time"},"contributor":{"type":"string","description":"Display name of the member."},"fromPublisher":{"type":"boolean","description":"The member was verified as representing one of the game's publishers."},"changes":{"type":"array","items":{"type":"object","required":["field","action","value"],"properties":{"field":{"type":"string","description":"A fact's name (`yearPublished`), a kind of credit (`designers`) or `names`."},"action":{"type":"string","enum":["changed","added","removed"]},"value":{"type":["string","null"],"description":"The credit or name added or removed; null for a fact."}}}}}}}}},"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}]}]}}}},"404":{"description":"No game has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account/corrections":{"get":{"operationId":"list_own_corrections","tags":["Corrections"],"summary":"List your corrections","description":"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.","security":[{"session":[]},{"apiToken":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"`nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of the member's corrections.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","status","reason","createdAt","reviewedAt","undone","game","changes"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","accepted","rejected"]},"reason":{"type":["string","null"],"description":"Why it was rejected."},"createdAt":{"type":"string","format":"date-time"},"reviewedAt":{"type":["string","null"],"format":"date-time"},"undone":{"type":"boolean","description":"Accepted, then taken back by a moderator."},"game":{"type":"object","required":["id","slug","name"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"}}},"changes":{"type":"array","items":{"allOf":[{"oneOf":[{"type":"object","title":"A fact","required":["type","field","old","new"],"properties":{"type":{"type":"string","const":"field"},"field":{"type":"string","enum":["name","yearPublished","minPlayers","maxPlayers","minPlaytime","maxPlaytime","minAge","tagline","description","officialUrl","ean","kind"]},"old":{"type":["string","integer","null"],"description":"The value the game showed when you wrote the correction. The correction is refused when the game no longer says this."},"new":{"type":["string","integer","null"],"description":"The value you propose, held to the rules of the field: `yearPublished` -3500 to 2100, players 1 to 999, playing time in minutes, `minAge` 0 to 99, `tagline` one line of 160 characters, `description` plain text of 5,000 characters, `officialUrl` an http(s) address, `ean` a valid EAN-13 (a 12-digit UPC is accepted), `kind` one of game, expansion, accessory. Null says the fact is unknown; `name` and `kind` cannot be null."},"source":{"type":"string","format":"uri","maxLength":500,"description":"Where you read it. Optional."},"note":{"type":"string","maxLength":500,"description":"Optional."}}},{"type":"object","title":"A credit","required":["type","action","kind"],"properties":{"type":{"type":"string","const":"credit"},"action":{"type":"string","enum":["add","remove"]},"kind":{"type":"string","enum":["designer","artist","publisher","category","mechanic","family"]},"slug":{"type":"string","description":"The slug of an existing entry. Required to remove a credit."},"name":{"type":"string","maxLength":200,"description":"To add someone or something the catalog does not list yet."},"source":{"type":"string","format":"uri","maxLength":500,"description":"Where you read it. Optional."},"note":{"type":"string","maxLength":500,"description":"Optional."}}},{"type":"object","title":"An alternate name","required":["type","language","name"],"properties":{"type":{"type":"string","const":"name"},"language":{"type":"string","description":"A language code such as \"fr\" or \"pt-br\"."},"name":{"type":"string","maxLength":300},"source":{"type":"string","format":"uri","maxLength":500,"description":"Where you read it. Optional."},"note":{"type":"string","maxLength":500,"description":"Optional."}}}]},{"type":"object","properties":{"decision":{"type":"string","enum":["accepted","declined"]}}}]}}}}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` for the next page."}}}}}},"400":{"description":"`cursor` is not an accepted value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account/publisher-claims":{"get":{"operationId":"list_publisher_claims","tags":["Corrections"],"summary":"List the publishers you asked to represent","description":"The member's requests to be recognised as representing a publisher, with their status.","security":[{"session":[]},{"apiToken":[]}],"responses":{"200":{"description":"The member's requests, newest first.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","status","emailDomain","note","publisher"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","verified","rejected"]},"emailDomain":{"type":"string"},"note":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"verifiedAt":{"type":["string","null"],"format":"date-time"},"publisher":{"type":"object","required":["slug","name"],"properties":{"slug":{"type":"string"},"name":{"type":"string"}}}}}}}}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"claim_publisher","tags":["Corrections"],"summary":"Say you represent a publisher","description":"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.","security":[{"session":[]},{"apiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["publisher","emailDomain"],"properties":{"publisher":{"type":"string","description":"The publisher's slug."},"emailDomain":{"type":"string","description":"The company's email domain."},"note":{"type":"string","maxLength":500}}},"example":{"publisher":"kosmos","emailDomain":"kosmos.de","note":"Product manager for the Catan line."}}}},"responses":{"201":{"description":"The request waits for a moderator.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","status","emailDomain","note","publisher"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","verified","rejected"]},"emailDomain":{"type":"string"},"note":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"verifiedAt":{"type":["string","null"],"format":"date-time"},"publisher":{"type":"object","required":["slug","name"],"properties":{"slug":{"type":"string"},"name":{"type":"string"}}}}}}}}}},"400":{"description":"The publisher, the domain or the note is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The member has not confirmed their email address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The member already sent a request for this publisher.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited, or five requests are already waiting.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lists":{"get":{"operationId":"list_lists","tags":["Lists"],"summary":"List the lists","description":"The 100 most recent lists. With `mine=1` and a session, only the member's own.","parameters":[{"name":"mine","in":"query","description":"Set to 1 to get only your own lists. Needs a session.","schema":{"type":"string","enum":["1"]}}],"security":[{},{"session":[]}],"responses":{"200":{"description":"The lists, newest first.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ListSummary"}}}}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create_list","tags":["Lists"],"summary":"Make a list","security":[{"session":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":2,"maxLength":80},"description":{"type":"string","maxLength":500}}},"example":{"name":"Gateway games","description":"Easy to teach to new players."}}}},"responses":{"201":{"description":"The list was created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}}}},"400":{"description":"The name or description is too short or too long.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lists/{id}":{"get":{"operationId":"get_list","tags":["Lists"],"summary":"Get one list and its games","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"lang","in":"query","description":"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.","schema":{"type":"string"},"example":"fr"}],"security":[{},{"session":[]}],"responses":{"200":{"description":"The list.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/List"}}}}}},"404":{"description":"No list has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lists/{id}/games/{game}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"game","in":"path","required":true,"description":"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.","schema":{"type":"string"},"example":"5c9b0f43-7a39-4f0c-8a4e-2f2d2b1d9a77"}],"put":{"operationId":"add_game_to_list","tags":["Lists"],"summary":"Add a game to a list","description":"Only the list's owner can do this. Adding a game twice changes nothing.","security":[{"session":[]}],"responses":{"200":{"description":"The game is on the list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The session belongs to someone other than the list's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The list or the game does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"remove_game_from_list","tags":["Lists"],"summary":"Remove a game from a list","description":"Only the list's owner can do this.","security":[{"session":[]}],"responses":{"200":{"description":"The game is not on the list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The session belongs to someone other than the list's owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The list or the game does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account":{"get":{"operationId":"get_account","tags":["Accounts"],"summary":"Your plan, request limit and settings","description":"Works with a session or an API token; a quick way to check a token.","security":[{"session":[]},{"apiToken":[]}],"responses":{"200":{"description":"The account behind the credentials sent.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Account"}}},"example":{"data":{"displayName":"Ana","plan":"free","requestsPerMinute":1200,"playlistProvider":null}}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"update_account","tags":["Accounts"],"summary":"Change your settings","description":"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`.","security":[{"session":[]},{"apiToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["playlistProvider"],"properties":{"playlistProvider":{"oneOf":[{"$ref":"#/components/schemas/MusicProvider"},{"type":"null"}]}}},"example":{"playlistProvider":"spotify"}}}},"responses":{"200":{"description":"The account with the setting applied.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Account"}}},"example":{"data":{"displayName":"Ana","plan":"free","requestsPerMinute":1200,"playlistProvider":"spotify"}}}}},"400":{"description":"`playlistProvider` is not a known service or null.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account/keys":{"get":{"operationId":"list_api_tokens","tags":["Accounts"],"summary":"List your API tokens","description":"Names and first characters only: a token's full value is shown once, when it is created. Needs a website session, not a token.","security":[{"session":[]}],"responses":{"200":{"description":"Your tokens, newest first.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiToken"}}}}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create_api_token","tags":["Accounts"],"summary":"Create an API token","description":"Returns the token once. Send it as `Authorization: Bearer <token>` to get the member request limit. Up to 10 tokens per account.","security":[{"session":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":60}}},"example":{"name":"My app"}}}},"responses":{"201":{"description":"The new token. `key` is not retrievable later.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/ApiToken"},{"type":"object","required":["key"],"properties":{"key":{"type":"string","description":"The token. Starts with `bgdb_`."}}}]}}}}}},"400":{"description":"The name is missing or too long, or the account already has 10 tokens.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account/keys/{id}":{"delete":{"operationId":"delete_api_token","tags":["Accounts"],"summary":"Delete an API token","description":"The token stops working at once.","security":[{"session":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The token is gone.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}},"401":{"description":"The request has no valid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 requests in a minute from this address. Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"session":{"type":"http","scheme":"bearer","description":"The session of a member signed in on the website. Used by the website itself."},"apiToken":{"type":"http","scheme":"bearer","description":"A personal API token (starts with `bgdb_`), created on the website's account page. Optional for reading: it raises the request limit."},"uploadToken":{"type":"apiKey","in":"header","name":"x-upload-token","description":"The token of one rulebook upload in parts, from `POST /games/{id}/rulebooks/uploads`. It opens that upload only, for two hours."}},"schemas":{"Error":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string","description":"What went wrong, in plain English words. The wording may change: act on `code`."},"code":{"type":"string","enum":["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","comment_hidden_by_votes","own_contribution_vote","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","invalid_merge_proposal","duplicate_merge_proposal"],"description":"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":{"type":"object","additionalProperties":{"type":["string","number"]},"description":"The numbers the sentence names, when it names any: for example `{ \"max\": 20 }` with `daily_photo_limit`."}},"example":{"error":"Game not found","code":"game_not_found"}},"Ok":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean","const":true}}},"Range":{"type":"object","required":["min","max"],"properties":{"min":{"type":["integer","null"]},"max":{"type":["integer","null"]}}},"GameSummary":{"type":"object","required":["id","slug","name","yearPublished","players","image","thumbnail","rating","complexity"],"properties":{"id":{"type":"string","format":"uuid","description":"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."},"slug":{"type":"string","description":"Used 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."},"name":{"type":"string","description":"The game's main name, or its name in the language asked for with `lang` when it has one."},"originalName":{"type":["string","null"],"description":"The game's main name when `name` is the one of the language asked for with `lang`. Null otherwise."},"yearPublished":{"type":["integer","null"]},"players":{"$ref":"#/components/schemas/Range","description":"Fewest and most players."},"image":{"type":["string","null"],"description":"The 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`."},"thumbnail":{"type":["string","null"],"description":"A 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.","example":"https://commons.wikimedia.org/wiki/Special:FilePath/Catan.jpg?width=200"},"kind":{"type":"string","enum":["game","expansion","accessory"],"description":"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":{"type":["string","null"],"enum":["box_front","board_traditional","box_partial","logo","components","in_play","people","other","box_back","setup","cards","rulebook",null],"description":"What 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":{"type":["boolean","null"],"description":"Whether 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":{"type":["integer","null"],"minimum":1,"maximum":5,"description":"How 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.","example":4},"imageWidth":{"type":["integer","null"],"description":"Width of the cover in pixels, to lay it out before it loads. Null when not measured."},"imageHeight":{"type":["integer","null"],"description":"Height of the cover in pixels. Null when not measured."},"imageLanguage":{"type":["string","null"],"description":"The 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.","example":null},"rating":{"oneOf":[{"$ref":"#/components/schemas/Rating"},{"type":"null"}],"description":"Members' ratings. Null when nobody has rated it."},"complexity":{"oneOf":[{"$ref":"#/components/schemas/Complexity"},{"type":"null"}],"description":"Members' votes on how heavy the game is. Null when nobody has voted."}},"example":{"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}}},"GameName":{"type":"object","required":["name","language","primary"],"properties":{"name":{"type":"string","description":"As written in that language, in its own script."},"language":{"type":"string","description":"Language code, lower case: \"fr\", \"ja\", \"pt-br\"."},"primary":{"type":"boolean","description":"True for the game's main name in that language, false for any other name it is known by there."}},"example":{"name":"Les Colons de Catane","language":"fr","primary":true}},"SearchResult":{"allOf":[{"$ref":"#/components/schemas/GameSummary"},{"type":"object","required":["matchedName","approximate"],"properties":{"approximate":{"type":"boolean","description":"True 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."},"matchedName":{"type":["object","null"],"description":"The alternate name the query was found in. Null when it was found in the game's main name.","required":["name","language"],"properties":{"name":{"type":"string"},"language":{"type":"string"}}}}}]},"Rating":{"type":"object","required":["average","count","weighted"],"properties":{"average":{"type":"number","description":"Mean of members' ratings, from 1 to 10.","example":7.42},"count":{"type":"integer","description":"How many members rated the game.","example":318},"weighted":{"type":"number","description":"The 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.","example":7.31}}},"Complexity":{"type":"object","required":["average","votes"],"properties":{"average":{"type":"number","description":"From 1 (light) to 5 (heavy).","example":2.29},"votes":{"type":"integer","example":121}}},"Rank":{"type":"object","required":["scope","name","rank"],"properties":{"scope":{"type":"string","enum":["overall","category"],"description":"`overall`: among all ranked games. `category`: among the ranked games of one of the game's categories."},"slug":{"type":"string","description":"The category's slug. Absent for `overall`."},"name":{"type":"string","description":"\"Overall\", or the category's name."},"rank":{"type":"integer","minimum":1,"description":"1 is best."}},"example":{"scope":"category","slug":"family","name":"Family","rank":3}},"PlayerCount":{"type":"object","required":["players","best","recommended","notRecommended"],"properties":{"players":{"type":"integer","description":"A number of players."},"best":{"type":"integer","description":"Members who find the game best with this many."},"recommended":{"type":"integer"},"notRecommended":{"type":"integer"}},"example":{"players":4,"best":61,"recommended":22,"notRecommended":3}},"CollectionStatus":{"type":"string","description":"What a game is to the member: one they own, or one they wish for.","enum":["owned","wishlist"]},"CollectionItem":{"type":"object","required":["game","statuses","rating","addedAt"],"properties":{"game":{"$ref":"#/components/schemas/GameSummary"},"statuses":{"type":"array","items":{"$ref":"#/components/schemas/CollectionStatus"}},"rating":{"type":["number","null"],"description":"The member's own rating of the game, if any."},"addedAt":{"type":"string","format":"date-time"}}},"Play":{"type":"object","required":["id","game","date","players","minutes","note","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"game":{"$ref":"#/components/schemas/GameSummary"},"date":{"type":"string","format":"date"},"players":{"type":["integer","null"]},"minutes":{"type":["integer","null"]},"note":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}},"Comment":{"type":"object","required":["id","author","text","rating","likes","dislikes","createdAt","updatedAt"],"properties":{"likes":{"type":"integer","description":"Members who liked it."},"dislikes":{"type":"integer","description":"Members who disliked it. Once dislikes outnumber likes by 3 or more, with at least 5 votes, it is hidden until a moderator looks at it."},"id":{"type":"string","format":"uuid"},"author":{"type":"string","description":"Display name of the member who wrote it."},"text":{"type":"string","description":"Plain text, not HTML. Escape it before display."},"rating":{"type":["number","null"],"description":"The author's rating of the game, if they gave one."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"VideoCategory":{"type":"string","enum":["review","how_to_play","playthrough","other"]},"Video":{"type":"object","required":["id","provider","videoId","url","title","language","category","submittedBy","likes","dislikes","createdAt"],"properties":{"likes":{"type":"integer","description":"Members who liked it."},"dislikes":{"type":"integer","description":"Members who disliked it. Once dislikes outnumber likes by 3 or more, with at least 5 votes, it is hidden until a moderator looks at it."},"id":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["youtube","vimeo"]},"videoId":{"type":"string","description":"The video's id at the provider, for embedding."},"url":{"type":"string","format":"uri","description":"Where to watch it, built from the id."},"title":{"type":"string"},"language":{"type":"string","description":"Language spoken, such as \"en\" or \"pt-BR\"."},"category":{"$ref":"#/components/schemas/VideoCategory"},"submittedBy":{"type":"string","description":"Display name of the member who suggested it."},"createdAt":{"type":"string","format":"date-time"}},"example":{"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","likes":12,"dislikes":1,"createdAt":"2026-11-20T18:04:11.120Z"}},"MusicProvider":{"type":"string","enum":["spotify","apple_music","youtube"],"description":"`youtube` covers YouTube and YouTube Music."},"Playlist":{"type":"object","required":["id","provider","kind","title","url","score","votes","submittedBy","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"provider":{"$ref":"#/components/schemas/MusicProvider"},"kind":{"type":"string","enum":["playlist","album"]},"title":{"type":"string"},"url":{"type":"string","format":"uri","description":"Where to listen, built from the service and the playlist's id there."},"score":{"type":"integer","description":"Votes up minus votes down."},"votes":{"type":"integer","description":"How many members voted, either way."},"submittedBy":{"type":"string","description":"Display name of the member who added it."},"createdAt":{"type":"string","format":"date-time"}},"example":{"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"}},"VoteStanding":{"type":"object","required":["likes","dislikes","status"],"properties":{"likes":{"type":"integer","description":"Members who liked it."},"dislikes":{"type":"integer","description":"Members who disliked it. Once dislikes outnumber likes by 3 or more, with at least 5 votes, it is hidden until a moderator looks at it."},"status":{"type":"string","enum":["visible","hidden"],"description":"`hidden`: voted down by members; no longer shown until a moderator looks at it."}}},"PlaylistStanding":{"type":"object","required":["score","votes","status"],"properties":{"score":{"type":"integer"},"votes":{"type":"integer"},"status":{"type":"string","enum":["visible","hidden"],"description":"`hidden`: voted out of the list by members."}}},"RulebookFile":{"type":"object","required":["path","contentType","size","kind"],"properties":{"path":{"type":"string","description":"Path of the file on this API."},"contentType":{"type":"string","enum":["application/pdf","image/jpeg","image/png","image/webp"]},"size":{"type":"integer","description":"Bytes."},"kind":{"type":["string","null"],"enum":["box_front","board_traditional","box_partial","logo","components","in_play","people","other","box_back","setup","cards","rulebook",null],"description":"What 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":{"type":"object","description":"A large rulebook on its way in, and how to send it.","required":["id","token","partSize","parts","expiresAt"],"properties":{"id":{"type":"string","format":"uuid","description":"The upload's id, and the rulebook's once it is complete."},"token":{"type":"string","description":"Send it as `x-upload-token` with every part and to finish or cancel. Shown once."},"partSize":{"type":"integer","description":"Bytes of every part but the last."},"parts":{"type":"integer","description":"How many parts to send."},"expiresAt":{"type":"string","format":"date-time","description":"When the token stops being accepted."}}},"OwnRulebook":{"type":"object","description":"A rulebook as its uploader sees it.","required":["id","language","edition","kind","pages","size","files"],"properties":{"id":{"type":"string","format":"uuid"},"language":{"type":"string","description":"A language code such as \"en\", \"fr\" or \"pt-BR\"."},"edition":{"type":["string","null"],"description":"Which edition or printing the rules belong to, when the uploader said."},"kind":{"type":"string","enum":["pdf","images"],"description":"One PDF file, or one image per page."},"pages":{"type":["integer","null"],"description":"Number of pages. Null for a PDF whose pages could not be counted."},"size":{"type":"integer","description":"Bytes, all files together."},"files":{"type":"array","description":"The files, in reading order. A PDF has one.","items":{"$ref":"#/components/schemas/RulebookFile"}}}},"Rulebook":{"type":"object","required":["id","language","edition","kind","pages","size","uploadedBy","createdAt","files"],"properties":{"id":{"type":"string","format":"uuid"},"language":{"type":"string","description":"A language code such as \"en\", \"fr\" or \"pt-BR\"."},"edition":{"type":["string","null"],"description":"Which edition or printing the rules belong to, when the uploader said."},"kind":{"type":"string","enum":["pdf","images"],"description":"One PDF file, or one image per page."},"pages":{"type":["integer","null"],"description":"Number of pages. Null for a PDF whose pages could not be counted."},"size":{"type":"integer","description":"Bytes, all files together."},"files":{"type":"array","description":"The files, in reading order. A PDF has one.","items":{"$ref":"#/components/schemas/RulebookFile"}},"uploadedBy":{"type":"string","description":"Display name of the member who uploaded it."},"createdAt":{"type":"string","format":"date-time"}},"example":{"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}]}},"Account":{"type":"object","required":["displayName","plan","requestsPerMinute","playlistProvider"],"properties":{"displayName":{"type":"string"},"plan":{"type":"string","enum":["free","paid"]},"requestsPerMinute":{"type":"integer"},"playlistProvider":{"oneOf":[{"$ref":"#/components/schemas/MusicProvider"},{"type":"null"}],"description":"The one music service the member wants playlists from. Null: all of them."}}},"MyAnswers":{"type":"object","required":["rating","complexity","recommendedAge","languageDependence","playerCounts","collection","comment","videos","playlistVotes","rulebooks","votes"],"properties":{"votes":{"type":"array","description":"The member's likes (`up`) and dislikes (`down`) of this game's comments, videos and photos.","items":{"type":"object","required":["target","id","vote"],"properties":{"target":{"type":"string","enum":["comment","video","photo"]},"id":{"type":"string","format":"uuid"},"vote":{"type":"string","enum":["up","down"]}}}},"playlistVotes":{"type":"array","description":"The member's votes on this game's playlists.","items":{"type":"object","required":["playlistId","vote"],"properties":{"playlistId":{"type":"string","format":"uuid"},"vote":{"type":"string","enum":["up","down"]}}}},"rulebooks":{"type":"array","description":"Rulebooks the member uploaded for this game, with where each stands. Rejected ones are deleted and not listed.","items":{"allOf":[{"$ref":"#/components/schemas/OwnRulebook"},{"type":"object","required":["status","createdAt"],"properties":{"status":{"type":"string","enum":["pending","approved"]},"createdAt":{"type":"string","format":"date-time"}}}]}},"rating":{"type":["number","null"]},"complexity":{"type":["integer","null"]},"recommendedAge":{"type":["integer","null"]},"languageDependence":{"type":["integer","null"]},"playerCounts":{"type":"array","description":"The member's ballot on player counts.","items":{"type":"object","required":["players","vote"],"properties":{"players":{"type":"integer"},"vote":{"type":"string","enum":["best","recommended","not_recommended"]}}}},"collection":{"type":"array","items":{"$ref":"#/components/schemas/CollectionStatus"}},"comment":{"type":["object","null"],"required":["id","text","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"text":{"type":"string"},"status":{"type":"string","enum":["visible","removed","hidden"],"description":"`removed`: taken down by a moderator. `hidden`: voted down by members, waiting for a moderator."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"videos":{"type":"array","description":"Videos the member suggested for this game, with where each stands.","items":{"allOf":[{"$ref":"#/components/schemas/Video"},{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["pending","approved","rejected"]}}}]}}}},"TermRef":{"type":"object","required":["slug","name"],"properties":{"slug":{"type":"string"},"name":{"type":"string"}}},"TermCount":{"type":"object","required":["slug","name","games"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"games":{"type":"integer","description":"How many games are linked to it."}}},"TermWithGames":{"type":"object","required":["slug","name","total","games","nextCursor"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"games":{"type":"array","items":{"$ref":"#/components/schemas/GameSummary"}}}},"AwardResult":{"type":"string","enum":["winner","nominee","recommended","finalist","special"],"description":"`winner` the game won; `nominee` it was nominated; `recommended` it was on the award's list of recommendations; `finalist` it reached the final selection; `special` it received a special prize."},"Honour":{"type":"object","required":["award","category","year","result"],"properties":{"award":{"$ref":"#/components/schemas/TermRef"},"category":{"type":["string","null"],"description":"Which prize of the award. Null for its main or only prize."},"year":{"type":["integer","null"],"description":"Year of the award. Null when the source does not state it; never guessed from the game's own year."},"result":{"$ref":"#/components/schemas/AwardResult"}},"example":{"award":{"slug":"spiel-des-jahres","name":"Spiel des Jahres"},"category":"Kennerspiel des Jahres","year":2011,"result":"winner"}},"GameRef":{"type":"object","required":["id","slug","name","originalName","yearPublished","thumbnail"],"description":"Enough of a game to list it and link to it.","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"originalName":{"type":["string","null"]},"yearPublished":{"type":["integer","null"]},"thumbnail":{"type":["string","null"],"description":"A small version of the cover from the game's source. Members' photos are not used here."}}},"AwardYear":{"type":"object","required":["year","honours"],"properties":{"year":{"type":["integer","null"],"description":"Null groups the honours whose year no source states; it comes last."},"honours":{"type":"array","description":"By category (the main prize first), winners before the others.","items":{"type":"object","required":["category","result","game"],"properties":{"category":{"type":["string","null"]},"result":{"$ref":"#/components/schemas/AwardResult"},"game":{"$ref":"#/components/schemas/GameRef"}}}}}},"AwardWithGames":{"allOf":[{"$ref":"#/components/schemas/TermWithGames"},{"type":"object","required":["years"],"properties":{"years":{"type":"array","items":{"$ref":"#/components/schemas/AwardYear"},"description":"Newest first. The 500 most recent honours; independent of `cursor` and of the filters."}}}]},"Relations":{"type":"object","description":"Other games in the catalog this one is related to, as sources state it. Each list holds at most 50 games, oldest first, and is empty when nothing is known. A relation stated on either of the two games appears on both.","required":["expansions","expansionOf","reimplements","reimplementedBy","contains","containedIn","integratesWith"],"properties":{"expansions":{"type":"array","items":{"$ref":"#/components/schemas/GameSummary"},"description":"Expansions of this game."},"expansionOf":{"type":"array","items":{"$ref":"#/components/schemas/GameSummary"},"description":"The game or games this expansion needs."},"reimplements":{"type":"array","items":{"$ref":"#/components/schemas/GameSummary"},"description":"Earlier games this one is based on and reworks (Brass: Birmingham reworks Brass: Lancashire)."},"reimplementedBy":{"type":"array","items":{"$ref":"#/components/schemas/GameSummary"},"description":"Later games based on this one."},"contains":{"type":"array","items":{"$ref":"#/components/schemas/GameSummary"},"description":"Games that come in this box (a compilation)."},"containedIn":{"type":"array","items":{"$ref":"#/components/schemas/GameSummary"},"description":"Compilations this game is part of."},"integratesWith":{"type":"array","items":{"$ref":"#/components/schemas/GameSummary"},"description":"Games this one can be combined with. No source states this yet, so it is always empty for now."}}},"Photo":{"type":"object","required":["id","path","kind","language","uploadedBy","createdAt","status","likes","dislikes"],"properties":{"likes":{"type":"integer","description":"Members who liked it."},"dislikes":{"type":"integer","description":"Members who disliked it. Once dislikes outnumber likes by 3 or more, with at least 5 votes, it is hidden until a moderator looks at it."},"id":{"type":"string","format":"uuid"},"path":{"type":"string","description":"Path of the file on this API."},"kind":{"type":["string","null"],"enum":["box_front","board_traditional","box_partial","logo","components","in_play","people","other","box_back","setup","cards","rulebook",null],"description":"What 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`."},"language":{"type":["string","null"],"description":"The language of the edition the photo shows, as a code such as \"en\" or \"pt-BR\". Null when its uploader did not say."},"uploadedBy":{"type":"string","description":"Display name of the member who added it."},"createdAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["approved","pending"],"description":"`pending` only appears to the member who uploaded it."},"official":{"type":"boolean","description":"The game's official cover, sent by a verified representative of one of its publishers."}}},"Game":{"description":"Everything the catalog knows about a game. Texts and images that come from other sources under a licence are credited at https://thebgdb.org/credits and listed by `GET /v1/credits`.","allOf":[{"$ref":"#/components/schemas/GameSummary"},{"type":"object","required":["names","tagline","description","summary","playtime","minAge","ean","officialUrl","updatedAt","credits","awards","relations","images","ranks","recommendedAge","playerCounts","bestWith","recommendedWith","languageDependence","distributions","playlists","rulebooks"],"properties":{"names":{"type":"array","items":{"$ref":"#/components/schemas/GameName"},"description":"Every 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."},"tagline":{"type":["string","null"],"description":"One line saying what the game is, at most 160 characters. Null when no source gave one.","example":"1995 board game by Klaus Teuber"},"description":{"type":["string","null"],"description":"A 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`."},"summary":{"type":"string","description":"One 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."},"playtime":{"$ref":"#/components/schemas/Range","description":"Shortest and longest game, in minutes."},"minAge":{"type":["integer","null"],"description":"Recommended minimum age."},"ean":{"type":["string","null"],"description":"EAN-13 barcode."},"officialUrl":{"type":["string","null"],"description":"The game's official website."},"updatedAt":{"type":"string","format":"date-time"},"credits":{"type":"object","description":"Everything 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.","required":["designers","artists","publishers","categories","mechanics","awards","families"],"properties":{"designers":{"type":"array","items":{"$ref":"#/components/schemas/TermRef"}},"artists":{"type":"array","items":{"$ref":"#/components/schemas/TermRef"}},"publishers":{"type":"array","items":{"$ref":"#/components/schemas/TermRef"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/TermRef"}},"mechanics":{"type":"array","items":{"$ref":"#/components/schemas/TermRef"}},"awards":{"type":"array","items":{"$ref":"#/components/schemas/TermRef"}},"families":{"type":"array","items":{"$ref":"#/components/schemas/TermRef"}}}},"awards":{"type":"array","items":{"$ref":"#/components/schemas/Honour"},"description":"What the game received from awards: most recent first, those with no stated year last. At most 200."},"relations":{"$ref":"#/components/schemas/Relations"},"images":{"type":"array","items":{"$ref":"#/components/schemas/Photo"},"description":"Oldest first."},"ranks":{"type":"array","items":{"$ref":"#/components/schemas/Rank"},"description":"The 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.","example":[{"scope":"overall","name":"Overall","rank":12},{"scope":"category","slug":"family","name":"Family","rank":3}]},"recommendedAge":{"type":["object","null"],"description":"The age members recommend the game from: the median of their votes. Null when nobody has voted. The publisher's stated age is `minAge`.","required":["age","votes"],"properties":{"age":{"type":"integer"},"votes":{"type":"integer"}},"example":{"age":8,"votes":47}},"playerCounts":{"type":"array","items":{"$ref":"#/components/schemas/PlayerCount"},"description":"Members' votes for each number of players anyone voted on, fewest players first. Empty when nobody has voted."},"bestWith":{"type":"array","items":{"type":"integer"},"description":"Numbers of players for which `best` has more votes than `recommended` and than `notRecommended`.","example":[4]},"recommendedWith":{"type":"array","items":{"type":"integer"},"description":"Numbers of players for which `best` and `recommended` together have more votes than `notRecommended`.","example":[3,4]},"languageDependence":{"type":["object","null"],"description":"How 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.","required":["level","votes"],"properties":{"level":{"type":"integer","minimum":1,"maximum":5},"votes":{"type":"integer"}},"example":{"level":2,"votes":35}},"distributions":{"type":"object","description":"How many members gave each answer: `rating[0]` counts ratings from 1 to 1.5, up to `rating[9]` for 10; `complexity[0]` counts votes of 1 (light) up to `complexity[4]` for 5 (heavy).","required":["rating","complexity"],"properties":{"rating":{"type":"array","items":{"type":"integer"},"minItems":10,"maxItems":10},"complexity":{"type":"array","items":{"type":"integer"},"minItems":5,"maxItems":5}},"example":{"rating":[0,1,2,4,9,21,38,30,12,3],"complexity":[3,18,40,11,2]}},"playlists":{"type":"integer","description":"Playlists listed for the game (`GET /games/{id}/playlists`).","example":3},"rulebooks":{"type":"integer","description":"Approved rulebooks, in any language (`GET /games/{id}/rulebooks`).","example":2}}}]},"ListSummary":{"type":"object","required":["id","name","description","owner","createdAt","games"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"owner":{"type":"string","description":"Display name of the member who made it."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time","description":"When a game was last added to it, or when it was made."},"games":{"type":"integer","description":"How many games are on it."}}},"List":{"type":"object","required":["id","name","description","owner","createdAt","isOwner","games"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"owner":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"isOwner":{"type":"boolean","description":"True when the session sent belongs to the owner."},"games":{"type":"array","items":{"$ref":"#/components/schemas/GameSummary"},"description":"In the order they were added."}}},"ApiToken":{"type":"object","required":["id","name","prefix"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"prefix":{"type":"string","description":"First characters of the token."},"createdAt":{"type":"string","format":"date-time"}}},"User":{"type":"object","required":["id","email","displayName"],"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"displayName":{"type":"string"},"emailVerified":{"type":"boolean","description":"False until the member opens the link emailed to them."},"plan":{"type":"string","enum":["free","paid"]},"role":{"type":"string","enum":["member","moderator"]}}},"Session":{"type":"object","required":["token","user"],"properties":{"token":{"type":"string","description":"Send as `Authorization: Bearer <token>`. Valid 30 days."},"user":{"$ref":"#/components/schemas/User"}}}}}}