Skip to content

List tables

GET
/api/v1/tables

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.

Authorization

bearerApiKey tables:read
AuthorizationBearer <token>

Build 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: tables:read

Query Parameters

limit?integer

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.

Range1 <= value <= 200
Default50
cursor?string

The 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.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/tables"
{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "areaId": "ebbb2a49-d827-4796-8d8a-108c229835e9",      "seatsMin": 0,      "seatsMax": 0,      "active": true    }  ],  "nextCursor": "string"}

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.

Change a reservationPATCH

A new time (or, for a table, a new party size) goes through the same change function as the guest's own change on their manage link: the venue's allocator, layouts, locks, hours and every other booking, leaving this booking out of its own way, then the deposit for the new time and party size; the booking window binds a new time. A change never takes money: one that would owe a deposit or a card the booking does not hold (a new time's service-period deposit, or a bigger party crossing the venue's deposit or card rule) is a `409 payment_required`. A party size change on a booking that already holds a deposit or a card is refused outright, for the venue to settle. The guest is told about a new time with the venue's usual change notice. Only a `confirmed` or `pending` booking that has not started can change. Send only the fields you are changing.