Reservations

A reservation is a party booked onto a table for one service on one service date. It is where the rest of this API arrives: an availability read says what can be booked, a hold takes a slot off sale, and both finish as a reservation.

Reading needs the reservations:read scope. Creating, modifying and cancelling need reservations:write. The shape of the object, its statuses and which of its fields your key can see are on The reservation object.

Endpoints

Endpoint	What it does
`POST /v1/reservations`	Books a table under the restaurant’s own rules. `Idempotency-Key` is required, and a `201` does not mean confirmed — read `status`.
`GET /v1/reservations`	Lists this restaurant’s bookings, cursor-paginated, filterable by service date, status, source and `updated_since`.
`GET /v1/reservations/{id}`	Retrieves one booking by its `resv_…` id.
`PATCH /v1/reservations/{id}`	Moves the day, the time, the party size or the seating area, and re-checks the booking against the rules.
`POST /v1/reservations/{id}/cancel`	Cancels the booking and gives the table back. A cancellation is a state, not a deletion.
`GET /v1/reservations/{id}/events`	The booking’s lifecycle history, oldest first.

The events feed

GET /v1/reservations/{id}/events is the one endpoint here that does not return a reservation. Each entry describes a single change rather than the booking’s current state; the shape is on The reservation event object, and what each data payload carries is in Reservation events.

Holds — take the slot before you take the booking.
Availability — what can be booked before you try.
Webhooks — the same booking arriving by push.