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
- In Esperaly: Organisation settings → Integrations (admin or owner).
- Create an API key. Copy it once — Esperaly stores a hash, not the secret.
- 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
| Scope | Allows |
|---|---|
| locations:read | List organisation locations |
| queues:read | List queues and fetch one queue |
| queue_entries:read | List and get ticket entries |
| queue_entries:write | Create, call, cancel, and complete entries |
| counters:read | Include counters on queue detail when the location uses counters |
| bookings:read | List 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
| Method | Path | Scope | Notes |
|---|---|---|---|
| GET | /locations | locations:read | Organisation locations |
| GET | /queues | queues:read | Same locations as queues (id = location id) |
| GET | /queues/:queueId | queues:read | Waiting/active counts; counters if counters:read |
| GET | /queues/:queueId/entries | queue_entries:read | Active tickets, cursor pagination |
| POST | /queues/:queueId/entries | queue_entries:write | Create via the same intake engine as the dashboard |
| GET | /entries/:entryId | queue_entries:read | One ticket |
| PATCH | /entries/:entryId | — | 405 in v1 (no safe patch mutation) |
| POST | /entries/:entryId/call | queue_entries:write | Moves the ticket to the workflow Call Next status. Body { "counterId" } required when the location uses counters |
| POST | /entries/:entryId/cancel | queue_entries:write | Workflow leave/cancel status |
| POST | /entries/:entryId/complete | queue_entries:write | Workflow complete status |
| GET | /bookings | bookings:read | Upcoming scheduled bookings. Optional from, to (unix ms), locationId. Default window is 7 days, max 31 |
| GET | /bookings/:bookingId | bookings:read | One 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.