Skip to content

Served for developers

Read a venue's bookings, guests and availability, and hear about every booking change the moment it happens. Venue owners create the keys; nothing goes through a partner programme.

Authentication

An owner of the venue creates an API key in Served: Settings, Developers. A key starts with sv_live_, belongs to one venue and is shown once. Served keeps only a hash of it.

Send the key as a Bearer token on every request. A missing, unknown or revoked key gets 401. Revoke a key in the same place; it stops working at once.

curl "https://served.global/api/v1/bookings?from=2026-11-14&to=2026-11-15" \
  -H "Authorization: Bearer sv_live_..."
Open Settings, Developers

Scopes

Each key has one or more read scopes. A request outside them gets 403 insufficient_scope.

  • bookings:read Bookings: GET /bookings and GET /bookings/{id}.
  • guests:read Guests: GET /guests and GET /guests/{id}, with names, contact details, marketing consent and visit counts.
  • availability:read Availability: GET /availability, the slots the venue's own booking page offers.

Limits and errors

  • 120 requests a minute per key. Past that you get 429 rate_limited with a Retry-After header in seconds.
  • Lists come in pages of up to 100 rows, 50 unless you set limit. When next_cursor is not null, pass it as cursor to get the next page.
  • Every response is JSON, sent with Cache-Control: no-store and no cookies. Times are ISO 8601 in UTC.

Errors share one shape, with a code to branch on:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key does not have the guests:read scope."
  }
}
unauthorized
401: no Bearer key was sent.
invalid_key
401: the key is unknown or revoked.
insufficient_scope
403: the key lacks the endpoint's scope.
plan_required
403: the venue is on Served Start.
rate_limited
429: more than 120 requests in a minute.
invalid_request
400: a query parameter is not valid; the message says which.
not_found
404: no such record at this venue.
unavailable
503: try again shortly.

Plans

Every paid Served plan includes the API and webhooks at no extra cost. Served Start does not: its requests get 403 plan_required, and its owners see an upgrade prompt instead of keys. The plan is checked on every request.

Endpoints

Base URL: https://served.global/api/v1. Every endpoint reads the key's own venue only.

List bookings

GET /api/v1/bookings

Bookings by start time, oldest first.

Scope: bookings:read

Query parameters

from
Start at or after this date or date-time.
to
Start before this date or date-time.
status
pending, requested, held, confirmed, seated, completed, cancelled or no_show.
limit
1 to 100, default 50.
cursor
next_cursor from the previous page.

Example response

{
  "data": [
    {
      "id": "3f1c2b9e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
      "reference": "K7Q2M9XA",
      "status": "confirmed",
      "party": 4,
      "starts_at": "2026-11-14T18:30:00.000Z",
      "ends_at": "2026-11-14T20:00:00.000Z",
      "channel": "online",
      "via": "instagram",
      "table": {
        "id": "8b2e4c6a-1d3f-4a5b-8c7d-9e0f1a2b3c4d",
        "label": "T12"
      },
      "deposit_status": "paid",
      "guest_id": "6d9a1f3e-2b4c-4d5e-8f7a-0b1c2d3e4f5a",
      "created_at": "2026-11-02T09:12:44.000Z",
      "updated_at": "2026-11-02T09:12:44.000Z"
    }
  ],
  "next_cursor": "WyIyMDI2LTExLTE0VDE4OjMwOjAwKzAwOjAwIiwiM2YxYzJiOWUtN2E0ZC00ZThiLTljMjEtNWQ2ZTdmOGE5YjBjIl0"
}

Get a booking

GET /api/v1/bookings/{id}

One booking by its id.

Scope: bookings:read

Example response

{
  "data": {
    "id": "3f1c2b9e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
    "reference": "K7Q2M9XA",
    "status": "confirmed",
    "party": 4,
    "starts_at": "2026-11-14T18:30:00.000Z",
    "ends_at": "2026-11-14T20:00:00.000Z",
    "channel": "online",
    "via": "instagram",
    "table": {
      "id": "8b2e4c6a-1d3f-4a5b-8c7d-9e0f1a2b3c4d",
      "label": "T12"
    },
    "deposit_status": "paid",
    "guest_id": "6d9a1f3e-2b4c-4d5e-8f7a-0b1c2d3e4f5a",
    "created_at": "2026-11-02T09:12:44.000Z",
    "updated_at": "2026-11-02T09:12:44.000Z"
  }
}

List guests

GET /api/v1/guests

Guests in the venue's guest book by last update, oldest first, so you can sync changes.

Scope: guests:read

Query parameters

updated_since
Updated at or after this date or date-time.
limit
1 to 100, default 50.
cursor
next_cursor from the previous page.

Example response

{
  "data": [
    {
      "id": "6d9a1f3e-2b4c-4d5e-8f7a-0b1c2d3e4f5a",
      "first_name": "Ola",
      "last_name": "Nowak",
      "email": "ola@example.com",
      "phone": "+48 600 000 000",
      "marketing": {
        "email": true,
        "consent_status": "granted"
      },
      "visit_count": 6,
      "created_at": "2026-03-08T19:02:10.000Z",
      "updated_at": "2026-11-02T09:12:44.000Z"
    }
  ],
  "next_cursor": null
}

Get a guest

GET /api/v1/guests/{id}

One guest by its id.

Scope: guests:read

Example response

{
  "data": {
    "id": "6d9a1f3e-2b4c-4d5e-8f7a-0b1c2d3e4f5a",
    "first_name": "Ola",
    "last_name": "Nowak",
    "email": "ola@example.com",
    "phone": "+48 600 000 000",
    "marketing": {
      "email": true,
      "consent_status": "granted"
    },
    "visit_count": 6,
    "created_at": "2026-03-08T19:02:10.000Z",
    "updated_at": "2026-11-02T09:12:44.000Z"
  }
}

Get availability

GET /api/v1/availability

The slots for one date and party size, from the same service as the venue's booking page.

Scope: availability:read

Query parameters

date
Required, YYYY-MM-DD in the venue's calendar.
party
1 to 20, default 2.

Example response

{
  "data": {
    "date": "2026-11-14",
    "party": 4,
    "capacity_known": true,
    "slots": [
      {
        "time": "18:00",
        "available": true
      },
      {
        "time": "18:30",
        "available": false
      },
      {
        "time": "19:00",
        "available": true
      }
    ]
  }
}

Webhooks

An owner adds an https endpoint and picks its events in Settings, Developers. Served shows the endpoint's signing secret once.

Served posts JSON to the endpoint within about a minute of the change. Any 2xx answer acknowledges it. The event id stays the same on every retry, so use it to skip duplicates.

Events

  • booking.created: a booking was made, by a guest or by staff. data is the booking.
  • booking.changed: its status, party, time, length or table changed. data is the booking.
  • booking.cancelled: it was cancelled. data is the booking.
  • guest.created: a guest was added to the guest book. data holds the id and consent only; read the guest with GET /guests/{id}.

Headers on every delivery

Served-Signature
t=<unix seconds>,v1=<signature>, see below.
Served-Event
The event type.
Served-Delivery
The delivery id, for support.

Example delivery

{
  "id": "0b7e9d2c-5a1f-4c3e-9d8b-7a6f5e4d3c2b",
  "type": "booking.created",
  "created_at": "2026-11-02T09:12:45.000Z",
  "data": {
    "id": "3f1c2b9e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
    "reference": "K7Q2M9XA",
    "status": "confirmed",
    "party": 4,
    "starts_at": "2026-11-14T18:30:00.000Z",
    "ends_at": "2026-11-14T20:00:00.000Z",
    "channel": "online",
    "via": "instagram",
    "table": {
      "id": "8b2e4c6a-1d3f-4a5b-8c7d-9e0f1a2b3c4d",
      "label": "T12"
    },
    "deposit_status": "paid",
    "guest_id": "6d9a1f3e-2b4c-4d5e-8f7a-0b1c2d3e4f5a",
    "created_at": "2026-11-02T09:12:44.000Z",
    "updated_at": "2026-11-02T09:12:44.000Z"
  }
}

Served only sends to public https hosts: no IP addresses, no private or local networks. It does not follow redirects, waits 5 seconds for an answer and reads at most 1 KB of it.

Checking signatures

Served signs "<t>.<raw body>" with HMAC-SHA256 and the endpoint's secret, and sends the hex digest as v1. Check it against the raw body before you parse it, compare in constant time, and refuse a t older than 5 minutes.

import { createHmac, timingSafeEqual } from 'node:crypto'

// rawBody: the request body exactly as received, before JSON.parse.
export function verifyServedSignature(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
  if (!signatureHeader) return false
  const parts = signatureHeader.split(',').map((part) => part.trim().split('='))
  const timestamp = Number(parts.find(([key]) => key === 't')?.[1])
  if (!Number.isInteger(timestamp)) return false
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false
  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest()
  return parts.some(([key, value]) => {
    if (key !== 'v1' || !value) return false
    const given = Buffer.from(value, 'hex')
    return given.length === expected.length && timingSafeEqual(given, expected)
  })
}

// Express: keep the raw body on the webhook route.
app.post('/served-webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const body = req.body.toString('utf8')
  if (!verifyServedSignature(body, req.get('Served-Signature'), process.env.SERVED_WEBHOOK_SECRET)) {
    return res.sendStatus(400)
  }
  const event = JSON.parse(body)
  // event.id is the same on every retry: skip one you have handled.
  res.sendStatus(200)
})

Retries

A delivery that fails (no answer within 5 seconds, a redirect, or any status outside 2xx) is tried again after:

  1. 1 minute
  2. 5 minutes
  3. 30 minutes
  4. 2 hours
  5. 6 hours
  6. 24 hours

If the last of those fails too, Served gives up on that delivery. An endpoint that has failed for 3 days without one success is turned off until an owner turns it on again. The console's delivery log shows every try, and an owner can send one again. Deliveries and events are kept for 30 days.

What the API never sends

  • Notes, allergies, diet or health details, on a booking or a guest.
  • A booking's guest name or contact details: a booking names its guest by guest_id, which guests:read resolves.
  • Tags, cancellation reasons, staff notes or any other free text.

OpenAPI

The whole API, its webhooks and their fields are described in OpenAPI 3.1, ready for Postman, Insomnia or code generators.

Open openapi.json

Optional analytics helps us improve Served: Google Analytics on this site, product analytics in the app and, on venue booking pages, the venue’s ad pixels (Meta, Google, TikTok). Declining does not limit any feature. Cookie Policy