{"openapi":"3.0.3","info":{"title":"TableArchive","description":"Board, card, and tabletop game database","version":"0.1.0"},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer"}},"schemas":{}},"paths":{"/v1/me":{"get":{"summary":"Your account","tags":["accounts"],"responses":{"200":{"description":"Default Response"}}}},"/v1/items":{"get":{"summary":"Search and filter items","tags":["items"],"parameters":[{"schema":{"type":"string","maxLength":200},"in":"query","name":"q","required":false,"description":"Search name and description"},{"schema":{"type":"string","enum":["board_game","card_game","rpg","rpg_supplement","rpg_adventure","card_set","miniatures_game","expansion","edition","accessory","other"]},"in":"query","name":"kind","required":false,"description":"Editions and card sets are left out unless asked for"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":9007199254740991},"in":"query","name":"players","required":false,"description":"Playable with exactly this many"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":9007199254740991},"in":"query","name":"max_playtime","required":false,"description":"Minutes"},{"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"age","required":false,"description":"Suitable for a player of this age"},{"schema":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"in":"query","name":"year","required":false},{"schema":{"type":"string","maxLength":200},"in":"query","name":"term","required":false,"description":"Term slug, e.g. deck-building"},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"entity","required":false,"description":"Credited person or organization"},{"schema":{"type":"string","maxLength":300},"in":"query","name":"external_id","required":false,"description":"ID in another system, e.g. a barcode or Wikidata QID"},{"schema":{"type":"string","maxLength":100},"in":"query","name":"external_source","required":false,"description":"Narrow external_id to one source, e.g. gtin, wikidata, bgg"},{"schema":{"type":"string","enum":["relevance","popular","name","year","updated"]},"in":"query","name":"sort","required":false,"description":"Defaults to relevance with a search, popular without: well-linked, photographed, complete items first."},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/v1/items/{idOrSlug}":{"get":{"summary":"One item with credits, terms, relations, photos, and provenance","tags":["items"],"parameters":[{"schema":{"type":"string","maxLength":200},"in":"path","name":"idOrSlug","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/entities":{"get":{"summary":"People and organizations","tags":["entities"],"parameters":[{"schema":{"type":"string","maxLength":200},"in":"query","name":"q","required":false},{"schema":{"type":"string","enum":["person","organization"]},"in":"query","name":"kind","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/v1/entities/{idOrSlug}":{"get":{"summary":"One entity and its credits","tags":["entities"],"parameters":[{"schema":{"type":"string","maxLength":200},"in":"path","name":"idOrSlug","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/terms":{"get":{"summary":"Mechanics, categories, and other tags, with item counts","tags":["terms"],"parameters":[{"schema":{"type":"string","maxLength":50},"in":"query","name":"kind","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/v1/stats":{"get":{"summary":"How much the catalog holds","tags":["sources"],"security":[],"responses":{"200":{"description":"Default Response"}}}},"/v1/sources":{"get":{"summary":"Where the data comes from, and its licensing","tags":["sources"],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Register or update a source (bots and admins)","tags":["sources"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":200},"name":{"type":"string","minLength":1,"maxLength":300},"kind":{"type":"string","enum":["manufacturer","open_data","community","other"]},"url":{"type":"string","maxLength":2000,"format":"uri"},"license":{"type":"string","maxLength":200}},"required":["key","name","kind"]}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/items/{idOrSlug}/history":{"get":{"summary":"Every change to one item, newest first","tags":["history"],"description":"Each event lists what changed with before and after values, which submission and source it came from, and who approved it.","parameters":[{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"offset","required":false},{"schema":{"type":"string","maxLength":200},"in":"path","name":"idOrSlug","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/events":{"get":{"summary":"Recent changes across the whole database","tags":["history"],"description":"Pass the highest event id you have seen as `after` to fetch only what is new, oldest first.","parameters":[{"schema":{"type":"string","enum":["created","updated","merged","photo_added","photo_removed"]},"in":"query","name":"type","required":false},{"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"after","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/v1/submissions":{"post":{"summary":"Propose a new item or a change to one","tags":["submissions"],"description":"Submissions from regular users wait for an admin. A \"create\" whose external_ids match an item we already hold is turned into an update of that item.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["create","update"]},"item_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"payload":{"type":"object","properties":{"kind":{"type":"string","enum":["board_game","card_game","rpg","rpg_supplement","rpg_adventure","card_set","miniatures_game","expansion","edition","accessory","other"]},"name":{"type":"string","minLength":1,"maxLength":300},"data":{"default":{},"type":"object","properties":{"description":{"nullable":true,"type":"string","maxLength":20000},"short_description":{"nullable":true,"type":"string","maxLength":500},"min_players":{"nullable":true,"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100000},"max_players":{"nullable":true,"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100000},"min_age":{"nullable":true,"type":"integer","minimum":0,"maximum":120},"min_playtime":{"nullable":true,"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100000},"max_playtime":{"nullable":true,"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100000},"year_published":{"nullable":true,"type":"integer","minimum":-4000,"maximum":2200},"alternate_names":{"nullable":true,"maxItems":200,"type":"array","items":{"type":"string","maxLength":300}},"website":{"nullable":true,"type":"string","maxLength":2000,"format":"uri"},"language":{"nullable":true,"type":"string","maxLength":100}},"additionalProperties":{}},"credits":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"role":{"type":"string","minLength":1,"maxLength":50},"name":{"type":"string","minLength":1,"maxLength":300},"kind":{"default":"person","type":"string","enum":["person","organization"]},"external_ids":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"source":{"type":"string","minLength":1,"maxLength":100},"id":{"type":"string","minLength":1,"maxLength":300},"url":{"type":"string","maxLength":2000,"format":"uri"}},"required":["source","id"]}},"entity_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["role","name"]}},"terms":{"default":[],"maxItems":200,"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","minLength":1,"maxLength":50},"name":{"type":"string","minLength":1,"maxLength":200}},"required":["kind","name"]}},"relations":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["expansion_of","supplement_for","set_of","edition_of","reimplements","integrates_with","accessory_for","contains"]},"item_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"external_id":{"type":"object","properties":{"source":{"type":"string","minLength":1,"maxLength":100},"id":{"type":"string","minLength":1,"maxLength":300},"url":{"type":"string","maxLength":2000,"format":"uri"}},"required":["source","id"]}},"required":["type"]}},"external_ids":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"source":{"type":"string","minLength":1,"maxLength":100},"id":{"type":"string","minLength":1,"maxLength":300},"url":{"type":"string","maxLength":2000,"format":"uri"}},"required":["source","id"]}},"remove":{"type":"object","properties":{"credits":{"default":[],"maxItems":200,"type":"array","items":{"type":"object","properties":{"role":{"type":"string","minLength":1,"maxLength":50},"entity_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["role","entity_id"]}},"terms":{"default":[],"maxItems":200,"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","minLength":1,"maxLength":50},"name":{"type":"string","minLength":1,"maxLength":200}},"required":["kind","name"]}},"relations":{"default":[],"maxItems":200,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["expansion_of","supplement_for","set_of","edition_of","reimplements","integrates_with","accessory_for","contains"]},"item_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["type","item_id"]}},"external_ids":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"source":{"type":"string","minLength":1,"maxLength":100},"id":{"type":"string","minLength":1,"maxLength":300},"url":{"type":"string","maxLength":2000,"format":"uri"}},"required":["source","id"]}},"images":{"default":[],"maxItems":200,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}}}}},"source":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":200},"name":{"type":"string","minLength":1,"maxLength":300},"kind":{"type":"string","enum":["manufacturer","open_data","community","other"]},"url":{"type":"string","maxLength":2000,"format":"uri"},"license":{"type":"string","maxLength":200}},"required":["key","name","kind"]},"source_url":{"type":"string","maxLength":2000,"format":"uri"},"note":{"type":"string","maxLength":2000}},"required":["action","payload"]}}}},"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"Your submissions; admins see everyone’s","tags":["submissions"],"parameters":[{"schema":{"type":"string","enum":["pending","approved","rejected"]},"in":"query","name":"status","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/v1/submissions/{id}":{"get":{"summary":"One submission","tags":["submissions"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/images":{"post":{"summary":"Upload a photo for an item or for your pending submission","tags":["images"],"description":"multipart/form-data with a `file` part plus fields: item_id or submission_id, kind (box_front, box_back, box_side, components, detail, gameplay, other), caption, sort_order, source_url (the original image), source_page_url (the page it came from), license, attribution. Photos from regular users wait for an admin.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"item_id":{"type":"string","format":"uuid"},"submission_id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["box_front","box_back","box_side","components","detail","gameplay","other"],"default":"other"},"caption":{"type":"string"},"sort_order":{"type":"integer","default":0},"source":{"type":"string","description":"Source key (bots and admins)"},"source_url":{"type":"string","format":"uri"},"source_page_url":{"type":"string","format":"uri"},"license":{"type":"string"},"attribution":{"type":"string"}}}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/images/{id}/file":{"get":{"summary":"The image file","tags":["images"],"description":"Without `size`, the original. With it, a WebP resized to fit 320px (thumb) or 1024px (medium) wide.","parameters":[{"schema":{"type":"string","enum":["thumb","medium"]},"in":"query","name":"size","required":false},{"schema":{"type":"string","maxLength":20},"in":"query","name":"exp","required":false,"description":"Signed links from the API carry exp and sig and need no key"},{"schema":{"type":"string","maxLength":200},"in":"query","name":"sig","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}}},"security":[{"apiKey":[]}]}