Reservations API

Create and manage table reservations. Reservations integrate with the tables system to automatically update table statuses.

Reservation Object

Name	Type	Required	Description
`id`	`uuid`	Required	Unique reservation identifier
`restaurant_id`	`uuid`	Required	Owning restaurant
`table_id`	`uuid`	Optional	Assigned table (can be null if unassigned)
`customer_name`	`string`	Required	Name of the guest
`customer_phone`	`string`	Optional	Guest phone number
`customer_email`	`string`	Optional	Guest email address
`party_size`	`integer`	Required	Number of guests
`reservation_date`	`string (date)`	Required	Date in YYYY-MM-DD format
`reservation_time`	`string (time)`	Required	Time in HH:MM format
`duration_minutes`	`integer`	Optional	Expected duration in minutes
`status`	`string`	Required	"pending", "confirmed", "seated", "completed", "cancelled", "no_show"
`notes`	`string`	Optional	Additional notes
`created_at`	`string (datetime)`	Required	ISO 8601 creation timestamp
`updated_at`	`string (datetime)`	Required	ISO 8601 last-update timestamp

List Reservations

GET/api/reservationsProtected

Retrieve reservations within a date range.

Query Parameters

Name	Type	Required	Description
`date_from`	`string (date)`	Required	Start date (YYYY-MM-DD)
`date_to`	`string (date)`	Optional	End date (YYYY-MM-DD). Defaults to date_from if omitted.

bash

curl -X GET __PH1__Authorization: Bearer <token>"

json

// Response 200
{
  __PH1__: [
    {
      __PH2__: "res-uuid",
      __PH4__: "table-uuid",
      __PH6__: "Schmidt, Hans",
      __PH8__: "+49 170 1234567",
      __PH10__: 4,
      __PH11__: "2026-03-20",
      __PH13__: "19:30",
      __PH15__: 120,
      __PH16__: "confirmed",
      __PH18__: "Birthday dinner",
      __PH20__: "2026-03-18T10:00:00Z",
      __PH22__: "2026-03-19T08:30:00Z"
    }
  ]
}

Get Reservation

GET/api/reservations/{id}Protected

Retrieve a single reservation by ID.

json

// Response 200
{
  __PH1__: "res-uuid",
  __PH3__: "table-uuid",
  __PH5__: "Schmidt, Hans",
  __PH7__: "+49 170 1234567",
  __PH9__: "hans@example.com",
  __PH11__: 4,
  __PH12__: "2026-03-20",
  __PH14__: "19:30",
  __PH16__: 120,
  __PH17__: "confirmed",
  __PH19__: "Birthday dinner",
  __PH21__: "2026-03-18T10:00:00Z",
  __PH23__: "2026-03-19T08:30:00Z"
}

Create Reservation

POST/api/reservationsProtected

Create a new reservation. The assigned table (if provided) will show a reserved status at the specified time.

Request Body

Name	Type	Required	Description
`customer_name`	`string`	Required	Name of the guest
`party_size`	`integer`	Required	Number of guests
`reservation_date`	`string (date)`	Required	Date in YYYY-MM-DD format
`reservation_time`	`string (time)`	Required	Time in HH:MM format
`table_id`	`uuid`	Optional	Table to assign
`customer_phone`	`string`	Optional	Guest phone number
`customer_email`	`string`	Optional	Guest email address
`duration_minutes`	`integer`	Optional	Expected duration in minutes
`notes`	`string`	Optional	Additional notes

json

// Request
{
  __PH2__: "Mueller, Anna",
  __PH4__: 2,
  __PH5__: "2026-03-21",
  __PH7__: "20:00",
  __PH9__: "table-uuid",
  __PH11__: "+49 160 9876543",
  __PH13__: 90,
  __PH14__: "Anniversary dinner"
}

// Response 201
{
  __PH16__: "new-res-uuid",
  __PH18__: "table-uuid",
  __PH20__: "Mueller, Anna",
  __PH22__: "+49 160 9876543",
  __PH24__: null,
  __PH25__: 2,
  __PH26__: "2026-03-21",
  __PH28__: "20:00",
  __PH30__: 90,
  __PH31__: "pending",
  __PH33__: "Anniversary dinner",
  __PH35__: "2026-03-20T12:00:00Z",
  __PH37__: "2026-03-20T12:00:00Z"
}

Update Reservation

PUT/api/reservations/{id}Protected

Update an existing reservation. All mutable fields can be changed.

json

// Request
{
  __PH1__: 3,
  __PH2__: "20:30",
  __PH4__: "Anniversary dinner - added +1 guest"
}

Update Reservation Status

PATCH/api/reservations/{id}/statusProtected

Transition a reservation to a new status.

Request Body

Name	Type	Required	Description
`status`	`string`	Required	"pending", "confirmed", "seated", "completed", "cancelled", or "no_show"

Status Transitions

When a reservation is moved to seated, the assigned table status automatically changes to occupied. When moved to completed, cancelled, or no_show, the table is freed.

json

// Request
{ __PH2__: "seated" }

// Response 200
{
  __PH4__: "res-uuid",
  __PH6__: "seated",
  __PH8__: "2026-03-20T19:35:00Z"
}

Delete Reservation

DELETE/api/reservations/{id}Protected

Delete a reservation. If the reservation had a table assigned, the table status is recalculated.

json

// Response 200
{
  __PH1__: "Reservation deleted successfully"
}

Get Table Reservations

GET/api/reservations/table/{tableId}Protected

Retrieve all reservations for a specific table. Optionally filter by date.

Query Parameters

Name	Type	Required	Description
`date`	`string (date)`	Optional	Filter by date (YYYY-MM-DD). Defaults to today.

bash

curl -X GET __PH1__Authorization: Bearer <token>"

json

// Response 200
{
  __PH1__: [
    {
      __PH2__: "res-uuid",
      __PH4__: "Schmidt, Hans",
      __PH6__: 4,
      __PH7__: "19:30",
      __PH9__: 120,
      __PH10__: "confirmed"
    },
    {
      __PH12__: "res-uuid-2",
      __PH14__: "Weber, Lisa",
      __PH16__: 2,
      __PH17__: "21:30",
      __PH19__: 90,
      __PH20__: "pending"
    }
  ]
}