Skip to content

List services

GET
/api/v1/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:read
AuthorizationBearer <token>

Build 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

limit?integer

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.

Range1 <= value <= 200
Default50
cursor?string

The 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"}