Introduction

The Service API is a read-only HTTP API for your restaurant’s reservations and guests. It is free to use and currently in beta.

It is designed for restaurants and the tools they use — custom websites, internal dashboards, CRMs, analytics pipelines, and automations — that want programmatic access to their own reservation and guest data.

Beta access — a few limitations

• Keys are provisioned on request, not yet self-serve — request one and we generate it for your restaurant.
• Webhook endpoints are also provisioned on request (see Webhooks).
• No public sandbox. There is one production base URL and keys are live; the API is read-only, so calls never change your data.
• No self-service webhook test trigger yet. Because the API is read-only, you cannot create or modify a record to make an event fire on demand; webhooks fire from real activity in the restaurant.

Base URL

All requests go to a single, dedicated host over HTTPS:

https://api.useservice.app

Every endpoint lives under the stable /v1 path prefix, for example:

GET https://api.useservice.app/v1/reservations
GET https://api.useservice.app/v1/guests

What you can do

• Reservations — list and filter reservations, retrieve a single reservation (with its table assignments and guest), and read a reservation’s lifecycle event history.
• Guests — list and search guests by phone, email, or free-text query, and retrieve a single guest with contact details, consent flags, and visit stats.
• Webhooks — subscribe to signed, real-time events for the reservation lifecycle plus guest and feedback events. See Webhooks.

Writing data (creating or modifying reservations and guests) is not part of this release.

Conventions at a glance

Area	Convention
Transport	HTTPS only, JSON request/response bodies
Auth	Authorization: Bearer sk_live_… — a per-restaurant API key
Versioning	Date-based Service-Version header, pinned per key
IDs	Opaque, prefixed strings (resv_…, gst_…) — never assume a format beyond the prefix
Timestamps	ISO-8601 with the restaurant’s UTC offset (e.g. 2026-06-27T19:30:00+02:00)
Lists	{ "object": "list", "data": [...], "has_more": true } — see Pagination
Errors	{ "error": { "type", "code", "message", "param"?, "doc_url" } } (param only when a parameter is at fault) — see Errors
Objects	Every resource carries an object field ("reservation", "guest", "list", …)

Response shape

Single resources are returned as a flat JSON object with an object discriminator:

{
  "object": "reservation",
  "id": "resv_8xKQ2m4Vd0pErJ7sN1aZ9bQ",
  "status": "confirmed",
  "party_size": 4,
  "service_date": "2026-06-27",
  "starts_at": "2026-06-27T20:00:00+02:00",
  "created_at": "2026-06-20T11:04:18+02:00",
  "updated_at": "2026-06-25T09:12:55+02:00"
}

Collections are wrapped in a list envelope:

{
  "object": "list",
  "data": [ { "object": "reservation", "id": "resv_…" } ],
  "has_more": true
}

Next steps

1. Read Authentication and get a key.
2. Skim Pagination and Errors.
3. Browse the full API reference, or grab the OpenAPI spec to generate an SDK or import it into Postman.
4. Set up Webhooks to react to changes in real time.