List reservations
The hospitality engine's table reservations. The mirror of GET /api/v1/appointments (same envelope, same paging, same filters), and deliberately not the same endpoint with a flag: the two engines share plumbing, never booking logic.
Engine-guarded: a key from an appointments organization gets 403 wrong_vertical before its scope is even checked.
Newest first; use from and to for a service, a day or a week. holdExpiresAt is exposed because a hold whose hold has expired is not a booking, and a program reading reservations has to be able to tell.
Three clocks in one object, and they are not interchangeable. startsAt and endsAt are the venue's wall clock wearing a +00 suffix; holdExpiresAt and createdAt are true UTC instants. All four serialise identically, so a caller that parses them alike is wrong about some of them by the venue's entire UTC offset. The sharpest edge is holdExpiresAt, the one field here meant to be compared against the current real instant. from and to filter on the same wall clock startsAt does. Read the venue's zone from timezone on GET /api/v1/organization, which needs the separate organization:read scope.
Three fields are deliberately withheld: the guest's manage token (the whole credential for their self-service link), the venue's private internal note, and the payment processor's identifier.
Authorization
bearerApiKey reservations:readBuild with a test key (sk_test_...): it works only in your API sandbox and never emails or texts anyone. Scopes, errors and limits.
In: header
Scope: reservations:read
Query Parameters
Clamped, never rejected: values below 1 or unparseable fall back to 50, values above 200 become 200. A ?limit=1e9 from a program is far more likely to be a client bug than an attack, and answering 200 rows beats answering an error it retries in a loop.
1 <= value <= 20050The nextCursor from the previous response, passed back unchanged. Omit it for the first page. Opaque: it is base64url of an internal position and the encoding is not part of the contract; treat it as a token, do not construct one. A cursor this API did not issue is a 400 invalid_cursor rather than a silently-ignored parameter, because silently restarting at page one is how a paging loop becomes an infinite one.
The scheme is keyset (seek) paging on (order column, id), not OFFSET. OFFSET is wrong under concurrent writes: a booking created between page 1 and page 2 shifts every later row back by one, and the caller silently never sees whichever row slid across the boundary. Filters and limit may change between pages; the cursor only says where you got to.
Inclusive lower bound on startsAt. Any timestamp Postgres accepts; a value it rejects is a 400. Combine with to for a day or a week.
Compared against startsAt, so it is in the venue's wall clock, not UTC, whatever offset you write on it. from=2026-08-20T00:00:00Z means midnight at the venue, not midnight UTC, and the Z is not honoured. To ask for a venue's day, write that day's local midnight and ignore the offset. Asking in real UTC instead returns a window shifted by the venue's offset, which for an Australian venue is most of a different day.
date-timeEXCLUSIVE upper bound on startsAt. Exclusive so that from=2026-07-26T00:00:00&to=2026-07-27T00:00:00 is exactly one day with no double-counting at the seam. That day is the venue's, not UTC: like from, this is compared against the venue's wall clock and any offset you write is ignored.
date-timeResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/reservations"{ "data": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "startsAt": "2019-08-24T14:15:22Z", "endsAt": "2019-08-24T14:15:22Z", "status": "hold", "partySize": 0, "turnMinutes": 0, "occasion": "string", "notes": "string", "tableId": "073fbfcb-cd05-4203-be18-a1ce6f8e4d2d", "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac", "holdExpiresAt": "2019-08-24T14:15:22Z", "depositStatus": "none", "depositAmountCents": 0, "createdAt": "2019-08-24T14:15:22Z", "reconfirmRequestedAt": "2019-08-24T14:15:22Z", "reconfirmedAt": "2019-08-24T14:15:22Z" } ], "nextCursor": "string"}Cancel an appointmentPOST
Cancels on the guest's behalf, recorded as cancelled by the guest. The row is kept, the guest gets the venue's usual cancellation notice, and a paid deposit is settled by the venue's own refund window: `depositOutcome` says whether it was `refunded`, `forfeited`, `none`, or `failed` (the booking IS cancelled; the money needs a person). Only a `confirmed` or `pending` booking can be cancelled.
Book a tablePOST
Books a table for a guest, in one call: the venue's own allocator picks the table (layouts, locks, combinations, special hours, the booking window and the online party ceiling all apply, exactly as on the booking page), then the guest is attached and the booking confirmed, and the guest gets the venue's usual confirmation. The booking's `source` is `api`. **`Idempotency-Key` header required**: a UUID you generate once per booking attempt and resend unchanged on every retry. The first answer is stored and every retry with the same key, from the same API key, with the same body gets that answer back, so a retried create never books twice. The same UUID with a different body, or from a different API key, is a `409`. Stored answers include refusals: a `409` for a taken time replays as a `409`, so a new attempt needs a new key. Answers are kept for at least a day. A venue that takes a deposit or a card is answered `402 payment_required` with a link, never with an unpaid booking. A venue that asks booking-time questions needs `intakeAnswers`; without them a required question is a `400`. Pre-ordered `extras` follow the booking page's rules, and a time with a required extra is `400 extras_required` until it is sent. A venue can confirm parties only up to a size it chooses ("confirm automatically up to N guests"). A larger party, still within the online ceiling, is booked as a request: the response is still `201` but `status` is `pending`, the table is held, the guest is emailed that the request was received, and the venue accepts (`booking.updated`, status `confirmed`) or declines (`booking.cancelled`) it. No deposit or card is asked for a request, so it is never a `402`. Read `status` rather than assuming `confirmed`. The guest's marketing consent is never set by this call.