Board games · APIApp

API for AI agents

Free, no key. JSON over HTTPS. Read only for AI agents: a table means people will sit down at the place, so tables and seats come from people in the app.

Read

GET /api/boardgames/summary?city=dc|nyc|sf: tables per place this week. {places:{id:{tables,people,open_seats}},tables,people,is_ai_counted:false}
GET /api/boardgames/place?city=sf&id=n4071080690: one place. {name,kind,tables:[{id,host,game,game_label,hours,starts,ends,seats_total,seats_left,seated:[{handle}]}],people,week_options}. Handles are random words, never names.

Seats count the host. seats_left is what others can still take. Game ids come from a fixed, hand-picked list (for example catan, codenames, chess, mahjong, any for bring-your-own, learn for learning a new one), each with its own seat range.

Place ids, names and facts come from the static snapshot at /boardgames/data/<city>.json (© OpenStreetMap contributors, ODbL 1.0): game cafés, game shops, game clubs, bars tagged for games, and the public libraries from Cowork who else?. Bars have "adult":true. hours is the raw OSM opening_hours string or null; check hours with the place.

Writes

POST /api/boardgames/post
content-type: application/json
{"city":"sf","id":"n4071080690","game":"catan","seats":4,
 "hours":"2","day":"2026-10-31","time":"19:00",
 "client_id":"my-agent-0123456789","is_ai":true}
→ 403 {"code":"ai_read_only"}

Every write with "is_ai": true returns 403 ai_read_only. AI agents never count as players.
People post, take a seat, give it up and cancel in the app, after confirming they are 18 or older (at every place, bars included). day is one of the next 7 days in the city’s time zone; time is on the hour or half hour, 10am to 10pm, at least 15 minutes away; hours is 1, 2 or 3. Seats can be taken until the table starts. We send no messages, emails or notifications.
Allowed fields only: city, id, slot, game, seats, hours, day, time, adult, device, client_id, is_ai. Any other field (name, note, phone…) returns 422 no_free_text and nothing is stored. Files and non-JSON bodies return 415.
Other refusals: 422 bad_game, bad_seats (outside the game’s seat range), bad_hours, bad_time, place_closed (the place’s mapped hours don’t cover the whole slot; unknown hours are allowed), adult_required; 409 full, started, own_slot, already_seated, overlap, max_open (3 upcoming tables per host); 429 when a daily limit is reached; 503 boardgames_off when the kill switch is on (reads keep working, writes_open:false).

Limits

Per device per day: 6 posts, 12 seats taken, 20 leaves, 20 cancels; at most 3 upcoming tables you host, and nothing that overlaps your other tables. 80 writes per network per day, 5,000 writes per day for the app.
Tables disappear when they end. Rows are deleted about 2 days later.