List services
The appointments engine's bookable services. Engine-guarded: a key from a table-reservations organization gets 403 wrong_vertical even if it holds services:read; the boundary is about what the organization is, not what happens to be stored for it.
Ordered by id, which is stable but arbitrary. A business sells tens of services, so the first page of 200 is the whole list in practice; sort them yourself if you want them alphabetical.
active: false services ARE returned, so a program reconciling against its own copy sees a service that was switched off instead of having it silently disappear. The public booking endpoints are where inactive services are filtered out.
Authorization
bearerApiKey services:readBuild with a test key (sk_test_...): it works only in your API sandbox and never emails or texts anyone. Scopes, errors and limits.
In: header
Scope: services:read
Query Parameters
Clamped, never rejected: values below 1 or unparseable fall back to 50, values above 200 become 200. A ?limit=1e9 from a program is far more likely to be a client bug than an attack, and answering 200 rows beats answering an error it retries in a loop.
1 <= value <= 20050The nextCursor from the previous response, passed back unchanged. Omit it for the first page. Opaque: it is base64url of an internal position and the encoding is not part of the contract; treat it as a token, do not construct one. A cursor this API did not issue is a 400 invalid_cursor rather than a silently-ignored parameter, because silently restarting at page one is how a paging loop becomes an infinite one.
The scheme is keyset (seek) paging on (order column, id), not OFFSET. OFFSET is wrong under concurrent writes: a booking created between page 1 and page 2 shifts every later row back by one, and the caller silently never sees whichever row slid across the boundary. Filters and limit may change between pages; the cursor only says where you got to.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/services"{ "data": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "description": "string", "durationMinutes": 0, "price": 0, "color": "string", "active": true, "imageUrl": "string", "onlineBookable": true } ], "nextCursor": "string"}Book an appointmentPOST
Books an appointment for a client through the booking page's own writer: the time is re-checked against working hours, rotation, overrides, venue and special hours, blocks and the booking window, and the database refuses an overlap. The client gets the business's usual confirmation. The booking's `source` is `api`. **`Idempotency-Key` header required**: a UUID you generate once per booking attempt and resend unchanged on every retry. The first answer is stored and every retry with the same key, from the same API key, with the same body gets that answer back, so a retried create never books twice. The same UUID with a different body, or from a different API key, is a `409`. Stored answers include refusals: a `409` for a taken time replays as a `409`, so a new attempt needs a new key. Answers are kept for at least a day. A business that takes a deposit or a card is answered `402 payment_required` with a link, never with an unpaid booking. The client's marketing consent is never set by this call.
List staffGET
The appointments engine's staff members. Engine-guarded, ordered by `id`: see `GET /api/v1/services` for why. **`serviceIds` lists the services each staff member performs**, the fact a program needs before it can offer anyone a slot. It is filtered to the key's own organization like every other field.