Book a table
/api/v1/reservationsBooks 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.
Authorization
bearerApiKey reservations:writeBuild 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:write
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/reservations" \ -H "Content-Type: application/json" \ -d '{ "startsAt": "string", "partySize": 1, "customer": { "name": "string", "email": "user@example.com" } }'{ "data": {}}List reservationsGET
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.
List tablesGET
The hospitality engine's tables. Engine-guarded, ordered by `id`: see `GET /api/v1/services` for why. `areaId` is returned, but there is no `/api/v1/areas` or `/api/v1/levels` yet: areas and levels have no scope a key can hold. The id is enough to group tables by room.