Docs / Catalog
Search and filters
Every parameter of GET /v1/items, and how results are sorted.
GET /v1/items?q=…&kind=…&players=…&max_playtime=…&age=…&year=…&term=…&entity=…&external_id=…&sort=…&limit=…&offset=…All parameters are optional and combine with AND.
| Parameter | Type | What it does |
|---|---|---|
q | string | Full-text search on names and descriptions, plus a fuzzy match on the name |
kind | enum | One kind. Without it, editions and card sets are left out |
players | integer | Items playable with exactly this many (min_players ≤ n ≤ max_players) |
max_playtime | integer | Items that finish within this many minutes |
age | integer | Items with min_age at or below this |
year | integer | year_published equals this |
term | slug | Items tagged with this mechanic or category, e.g. deck-building. See Credits, terms, relations |
entity | UUID | Items credited to this person or organization |
external_id | string | Items with this barcode or ID in another system. See Lookup |
external_source | string | Narrow external_id to one source, e.g. gtin, wikidata, bgg |
sort | enum | relevance, popular, name, year, updated |
limit | 1–200 | Page size, default 50 |
offset | integer | Skip this many |
Sorting
Without sort, results are ordered by relevance when there is a q, and by popular otherwise. "Popular" means well-linked, photographed, complete items first; it is a measure of how much we know, not of how good a game is.
Response
{ "total": 471, "items": [ … ] }Each item in the list has id, kind, name, slug, data, updated_at, and image (the box front's thumb_url, medium_url, and url, or null). Fetch GET /v1/items/{slug} for the rest.
Examples
Two-player games under 45 minutes, newest first:
curl "https://tablearchive.dev/v1/items?players=2&max_playtime=45&sort=year" -H "Authorization: Bearer $TA_KEY"Everything by one designer:
curl "https://tablearchive.dev/v1/entities?q=uwe+rosenberg" -H "Authorization: Bearer $TA_KEY"
curl "https://tablearchive.dev/v1/items?entity=<id from above>" -H "Authorization: Bearer $TA_KEY"