API for AI agents

Read

• GET /api/trickortreat/summary?city=dc|nyc|sf&hood=…: {city,hood,name,window:{state:"before"|"soon"|"open"|"closed"|"after",night:"2026-10-31",sunset,opens_at,closes_at,tz},blocks:[{id,label,status:"giving"|"low"|"out",households,some_low}],blocks_lit,blocks_total,small_counts:"lt5 means 1 to 4 households",people_only:true,is_ai_counted:false,writes_open,credit}. households is 0 (all out), the string "lt5" for 1 to 4, or "5plus" for 5 or more. Exact counts are never shown. A block that neighbors on 3 different networks reported has status:"reported" and households:null. There is no neighborhood household total.
• GET /api/trickortreat/weather?city=…: National Weather Service hourly forecast for 5–9 PM local on Oct 31, when available.
• GET /api/trickortreat/justincase?city=…&hood=…: up to two pharmacies, two urgent care places and the nearest emergency room (kind:"Pharmacy"|"Urgent care"|"Emergency room", each with its street address or null; places known to be closed are left out), from who else? Still open?. status is for Saturday Oct 31 at 7 PM from listed opening hours: "open_sat", "closed_sat" or "hours_unknown", with status_text.

Neighborhoods: DC capitolhill, chevychase, clevelandpark, petworth, brookland, takoma, mountpleasant, georgetown, gloverpark; NYC parkslope, brooklynheights, carrollgardens, ditmaspark, uws, westvillage, astoria, jacksonheights, bayridge; SF noevalley, bernal, colevalley, innersunset, innerrichmond, glenpark, castro, potrero, pacificheights. Block labels are a street between two cross streets from an OpenStreetMap snapshot (© OpenStreetMap contributors, ODbL), at /trick-or-treat/data/{city}-{hood}.json.

Writes

POST /api/trickortreat/post
content-type: application/json
{"city":"dc","hood":"capitolhill","block":"…","until":"21:00","adult":true,
 "client_id":"my-agent-0123456789","is_ai":true}
→ 403 {"code":"ai_read_only"}

• Every write with "is_ai": true or a client_id returns 403 ai_read_only. AI agents never count as households.
• Writes (post, update, remove, report) need the signed, HttpOnly device cookie the app gets on its first read; without it they return 401 no_device. A device id in the body is ignored. The cookie is bound to its namespace (live or one test namespace). Per-phone limits also apply per network address, so a fresh cookie doesn’t reset them.
• One post per phone, one per network address per block, a few per network per block, and new households on a busy block are let in a few at a time every 10 minutes.
• POST /api/trickortreat/report {"city","hood","block"}: “Report this block”, no text. Lit blocks only (422 not_lit). One counted report per network per block; each address can report 2 blocks and each network 3 blocks per neighborhood per night (429 report_limit). A block greys out when at least 3 networks, and at least as many networks as posted it, report it.
• Posts are accepted only on Oct 31 from 30 minutes before local sunset until 9 PM local; otherwise 422 not_open. Everything expires at 9 PM and rows are deleted after they expire.
• Only the fields above. Any other field (names, house numbers, kids, photos, notes) returns 422 no_free_text.

Safety

Block-level only: no house numbers, addresses or pins on homes. No kid profiles, photos, child counts, free text or messages. Posting is 18+.

Back to Trick-or-treat