Server-side HTTP reference

This is a language-neutral reference for driving SeatBuilder directly over HTTP — for backends with no JavaScript SDK (a PHP/Guzzle service, a Python worker, a Ruby or Go API). Every operation below is a plain REST call you can reproduce in any HTTP client, shown here as copy-paste curl.

Use this page when your server owns the whole seat lifecycle (the headless / server-authoritative flow): it holds seats, books them at checkout, and releases anything abandoned. For the concepts and the full JSON response shapes, see Hold and book lifecycle; for the two-key credential model and when the server vs. the browser takes the initial hold, see Server-side integration.

Base URL and auth

All calls go to https://seatbuilder.org under the global prefix /api/v1. Authenticate every request with the X-Api-Key header — there is no OAuth, session cookie, or JWT for API consumers.

Call these routes from your server with your secret key (sk_live_…) and keep it off the browser. The write routes also accept a public key (pk_live_…), but the secret key is the correct server-side credential — the public key exists for browser code where the value is unavoidably visible. Read routes (status, get event) work with either key.

curl -H "X-Api-Key: sk_live_xxx" \
  https://seatbuilder.org/api/v1/events/evt_q3-2026-jazz-night/status

All write routes now accept a canonical objectLabels array. The legacy singular objectLabel on /hold and labels on /extend are still accepted as deprecated aliases for backward compatibility (they will be removed in a future major version) — prefer objectLabels in new integrations. When both are sent, objectLabels wins. The examples below show the current canonical field for each operation. See Error model for the 4xx envelope.

Hold a seat

Take a hold on one or more seats. POST /api/v1/events/{eventKey}/seats/hold accepts an objectLabels array plus your session holdToken. ttlSeconds is optional and defaults to 900 (15 minutes) when omitted.

# Hold one or more seats atomically (all-or-nothing) with objectLabels[]:
curl -X POST https://seatbuilder.org/api/v1/events/evt_q3-2026-jazz-night/seats/hold \
  -H "X-Api-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"objectLabels":["A-12","A-13"],"holdToken":"7f6c3a91-b1ef-4d0a-9c84-3f12a8e0b5d2","ttlSeconds":900}'

Passing objectLabels[] holds every listed seat atomically under one holdToken — if any seat cannot be held the whole request fails 409 and nothing is held. The response mirrors the input: an array objects[]. The legacy { "objectLabel": "A-12" } single-seat form still works and returns the original flat single-object response. GA-area holds keep the singular objectLabel + objectType: "generalAdmission" + quantity form.

Extend a hold

Refresh the expiry of seats a token already holds (for example when the buyer reaches the payment screen). POST /api/v1/events/{eventKey}/seats/extend takes an optional objectLabels array — omit it to extend every seat currently held by the token. ttlSeconds is capped at 3600 (1 hour).

curl -X POST https://seatbuilder.org/api/v1/events/evt_q3-2026-jazz-night/seats/extend \
  -H "X-Api-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"objectLabels":["A-12","A-13"],"holdToken":"7f6c3a91-b1ef-4d0a-9c84-3f12a8e0b5d2","ttlSeconds":600}'

The legacy singular labels array is still accepted as a deprecated alias; when both are sent, objectLabels wins.

Book the held seats

Promote holds to permanent bookings in one atomic call. POST /api/v1/events/{eventKey}/seats/book takes an objectLabels array plus the shared holdToken — it is all-or-nothing: every listed label must currently be held by that token or the whole request fails.

curl -X POST https://seatbuilder.org/api/v1/events/evt_q3-2026-jazz-night/seats/book \
  -H "X-Api-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"objectLabels":["A-12","A-13"],"holdToken":"7f6c3a91-b1ef-4d0a-9c84-3f12a8e0b5d2"}'

Release seats

Give seats back to inventory. POST /api/v1/events/{eventKey}/seats/release takes an objectLabels array; the seats return to free.

curl -X POST https://seatbuilder.org/api/v1/events/evt_q3-2026-jazz-night/seats/release \
  -H "X-Api-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"objectLabels":["A-12","A-13"]}'

Read seat status

Poll the current state of every seat in an event. GET /api/v1/events/{eventKey}/status is a read-only call with no request body — a public key suffices.

curl https://seatbuilder.org/api/v1/events/evt_q3-2026-jazz-night/status \
  -H "X-Api-Key: pk_live_xxx"

Pass ?labels=A-12,A-13 (comma-separated, max 200) to narrow the status response to specific seats for large venues:

curl "https://seatbuilder.org/api/v1/events/evt_q3-2026-jazz-night/status?labels=A-12,A-13" \
  -H "X-Api-Key: pk_live_xxx"

Free seats are still omitted — use /objects for the full layout including free seats.

List objects and categories

Read the full published-chart layout — every object plus its category definitions — independent of live status. GET /api/v1/events/{eventKey}/objects is a read-only call (a public key suffices). Use it to map each categoryKey to your own price, including for free seats, before any seat is held.

# Read the full published-chart layout (objects + categories) independent of live status —
# use it to map each categoryKey to your own price, including for FREE seats:
curl https://seatbuilder.org/api/v1/events/evt_q3-2026-jazz-night/objects \
  -H "X-Api-Key: pk_live_xxx"

# Narrow to specific seats with ?labels= (comma-separated, max 200):
curl "https://seatbuilder.org/api/v1/events/evt_q3-2026-jazz-night/objects?labels=A-12,A-13" \
  -H "X-Api-Key: pk_live_xxx"

The response is { eventKey, categories: [{ key, label }], objects: [{ objectLabel, categoryKey, objectType, ... }] }. An unpublished chart returns empty arrays ({ "categories": [], "objects": [] }) with a 200 — not a 404. Unknown labels passed to ?labels= are silently omitted rather than rejected.

Get event

Fetch an event's metadata, including the chart it renders and the published chart version it is pinned to. GET /api/v1/events/{eventKey} is also a read-only call.

curl https://seatbuilder.org/api/v1/events/evt_q3-2026-jazz-night \
  -H "X-Api-Key: pk_live_xxx"

Response shapes

For the full JSON request and response bodies of each endpoint — including the holdExpiresAt, booked[], releasedAt, and status object shapes — see Hold and book lifecycle, which documents every response verbatim from the API contract.