TableArchive
Log in

Docs / Contributing

Submissions

Adding items and correcting facts through the API, and what happens next.

Everything that changes the catalog is a submission: a new item or an update to one. Regular users' submissions wait for an admin to approve them; bots' are published at once unless flagged.

Create an item

curl -X POST "https://tablearchive.dev/v1/submissions" \
  -H "Authorization: Bearer $TA_KEY" -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "payload": {
      "kind": "board_game",
      "name": "Cascadia",
      "data": { "year_published": 2021, "min_players": 1, "max_players": 4, "min_playtime": 30, "max_playtime": 45, "min_age": 10 },
      "credits": [{ "role": "designer", "name": "Randy Flynn" }, { "role": "publisher", "name": "Flatout Games", "kind": "organization" }],
      "terms": [{ "kind": "mechanic", "name": "Tile placement" }],
      "external_ids": [{ "source": "bgg", "id": "295947" }, { "source": "gtin", "id": "850014195151" }]
    },
    "source_url": "https://www.flatout.games/cascadia",
    "note": "From the publisher's page"
  }'

Returns 201 with the submission, including its status (pending or approved) and, once approved, the item_id.

A create whose external_ids match an item already in the catalog becomes an update of that item, so re-running an import is safe.

Update an item

Send action: "update" with the item_id and only the fields that change. null removes a field.

{
  "action": "update",
  "item_id": "fc0f21c4-…",
  "payload": { "data": { "max_playtime": 90, "language": null } },
  "note": "Box says 75–90 minutes"
}

Credits, terms, relations, and external IDs in an update are added. To take something off, list it under remove:

{ "action": "update", "item_id": "…", "payload": { "remove": { "credits": [{ "role": "publisher", "entity_id": "…" }] } } }

Removals always wait for a human, even from a bot.

Payload reference

FieldNotes
kind, nameRequired for create
dataThe known fields plus any extra keys; at most 100,000 characters as JSON
credits[]role, name, kind (person or organization), optional external_ids, or entity_id to credit an existing entity
terms[]kind and name
relations[]type plus either item_id or an external_id of the other item
external_ids[]source, id, optional url. Barcodes are validated
removeLists of credits, terms, relations, external_ids, and image ids to take off

Top-level: action, item_id (for updates), payload, source_url (where the facts came from), and a note for the reviewer.

Your submissions

GET /v1/submissions lists yours, with status and the reviewer's review_note. Filter with status=pending. GET /v1/submissions/{id} returns one.

What bots may do

A bot's unreviewed update only fills empty fields or refreshes fields its own source set earlier. It never overwrites another source's value. New items with the same name and kind as an existing one are flagged as possible duplicates and wait for review.

Previous← History and provenance