The availability API

Create a key

Create a key at /app/api-keys for your venue. Leave Scope on Availability and the key carries the single availability:write scope — there’s nothing else it can do. (The other choice, Host, mints a reservations key for a host stand; it cannot touch availability.) The full key (qk_…) is shown once at creation; only its prefix is shown afterward, and Revoke cuts it off immediately.

Update one item

curl -X PATCH https://app.qaema.ai/v1/items/<item_id>/availability \
  -H "authorization: Bearer qk_…" \
  -H "content-type: application/json" \
  -d '{"available": false, "until": null, "reason": "Out of lamb"}'

available is required; until is an ISO timestamp or null for “until I say” (the default); reason is optional, up to 200 characters. A successful call returns the updated item and a change id.

Update several at once

POST /v1/items/availability takes the same fields plus item_ids and/or section_ids arrays in place of a path id — useful for taking a whole section out together. At least one of the two lists is required, or the request is rejected.

Read the public sold-out map

GET /v1/venues/<slug>/availability.json needs no key — it’s the same data the public menu polls, cached for 30 seconds. It returns only the items currently unavailable, keyed by item id, each with until and reason; an item whose sold-out window has already passed is dropped from the response before it’s sent.

Error codes

A missing, unrecognized or revoked key gets 401. A key without the availability:write scope, or used against an item or section outside its own venue, gets 403. A malformed request body gets 400.

Keys and deleted venues

A key belongs to one venue. Delete that venue and every key issued for it stops authenticating — it’s rejected exactly like a revoked key, with no way to tell the two cases apart from the response.