Developers

REST API v1

Public REST for locations, queues, and entries

Server-to-server HTTP on the Esperaly API host. Staff still sign in with WorkOS AuthKit; integrations use Bearer API keys.

Base URL

All routes use this base URL. The same host is shown in Organisation settings → Integrations.

https://api.esperaly.com/v1

Authentication

  1. In Esperaly: Organisation settings → Integrations (admin or owner).
  2. Create an API key. Copy it once — Esperaly stores a hash, not the secret.
  3. Send it on every request.
Authorization: Bearer esperaly_live_<secret>

Keys can be scoped and optionally restricted to specific locations. Demo organisations reject API keys. Never log the raw key. Revoked, expired, or unknown keys return 401.

Scopes

ScopeAllows
locations:readList organisation locations
queues:readList queues and fetch one queue
queue_entries:readList and get ticket entries
queue_entries:writeCreate, call, cancel, and complete entries
counters:readInclude counters on queue detail when the location uses counters
bookings:readList upcoming bookings and fetch one booking

Example

curl -sS "https://api.esperaly.com/v1/locations" \
  -H "Authorization: Bearer esperaly_live_…"

Create an entry (Idempotency-Key is stored for 24 hours):

curl -sS -X POST "https://api.esperaly.com/v1/queues/$LOCATION_ID/entries" \
  -H "Authorization: Bearer esperaly_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"serviceId":"…","customerName":"Ada Lovelace"}'

Routes

MethodPathScopeNotes
GET/locationslocations:readOrganisation locations
GET/queuesqueues:readSame locations as queues (id = location id)
GET/queues/:queueIdqueues:readWaiting/active counts; counters if counters:read
GET/queues/:queueId/entriesqueue_entries:readActive tickets, cursor pagination
POST/queues/:queueId/entriesqueue_entries:writeCreate via the same intake engine as the dashboard
GET/entries/:entryIdqueue_entries:readOne ticket
PATCH/entries/:entryId—405 in v1 (no safe patch mutation)
POST/entries/:entryId/callqueue_entries:writeMoves the ticket to the workflow Call Next status. Body { "counterId" } required when the location uses counters
POST/entries/:entryId/cancelqueue_entries:writeWorkflow leave/cancel status
POST/entries/:entryId/completequeue_entries:writeWorkflow complete status
GET/bookingsbookings:readUpcoming scheduled bookings. Optional from, to (unix ms), locationId. Default window is 7 days, max 31
GET/bookings/:bookingIdbookings:readOne booking
GET/health—Unauthenticated. { ok: true } only when the API backend answers

Pagination: ?limit=25&cursor=… (max 100). Response { data, hasMore, cursor }.

Idempotency-Key on POST create: same key + same path returns the same ticket for 24 hours.

Entry objects include optional origin (walk_in or appointment) and scheduledAt (unix ms) when those fields are present on the ticket.

Errors

{ "error": { "code": "unauthorized", "message": "Invalid or missing API key", "requestId": "…" } }

CORS allows the Esperaly site origin only (not *). Server-to-server callers (curl, Zapier, your backend) do not need a browser origin.

MCP

A read-only MCP server is available at https://api.esperaly.com/mcp. Send JSON-RPC over HTTP with the same API key. Tools: list_locations, list_queues, get_queue, list_tickets, get_ticket, list_bookings, get_booking. Each tool requires the matching read scope. There are no write tools.

Not in this release

Product OAuth (PKCE / refresh tokens) and an official Zapier app are not shipped. Use API keys plus REST or MCP, or Webhooks by Zapier with a Catch Hook.

All developer docs · OpenAPI