Skip to content

List appointments

GET
/api/v1/appointments

The appointments engine's bookings, newest first.

Use from and to to ask for a day or a week. They are why this is one of only two v1 lists with filters: services, staff, tables and service periods are bounded by how many a business has, so one page is the whole list, while bookings are unbounded and time-shaped.

Engine-guarded: a key from a table-reservations organization gets 403 wrong_vertical, and appointments:* scopes cannot be granted to one in the first place.

Times. startsAt and endsAt are the venue's local time with its real offset (2026-08-20T19:00:00+10:00), so they parse to the true instant like createdAt does. from and to are venue-local wall clock; any offset on them is ignored.

Authorization

bearerApiKey appointments: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: appointments: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.

from?string

Inclusive lower bound on startsAt. Any timestamp Postgres accepts; a value it rejects is a 400. Combine with to for a day or a week.

Compared against startsAt, so it is in the venue's wall clock, not UTC, whatever offset you write on it. from=2026-08-20T00:00:00Z means midnight at the venue, not midnight UTC, and the Z is not honoured. To ask for a venue's day, write that day's local midnight and ignore the offset. Asking in real UTC instead returns a window shifted by the venue's offset, which for an Australian venue is most of a different day.

Formatdate-time
to?string

EXCLUSIVE upper bound on startsAt. Exclusive so that from=2026-07-26T00:00:00&to=2026-07-27T00:00:00 is exactly one day with no double-counting at the seam. That day is the venue's, not UTC: like from, this is compared against the venue's wall clock and any offset you write is ignored.

Formatdate-time

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/appointments"
{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "startsAt": "2019-08-24T14:15:22Z",      "endsAt": "2019-08-24T14:15:22Z",      "status": "pending",      "durationMinutes": 0,      "price": 0,      "notes": "string",      "serviceId": "8f8bb40f-b96b-40fe-9064-5031fbe483f9",      "providerId": "4834bcdc-4a64-444d-966b-1a6fe381da24",      "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",      "depositStatus": "none",      "depositAmountCents": 0,      "createdAt": "2019-08-24T14:15:22Z",      "reconfirmRequestedAt": "2019-08-24T14:15:22Z",      "reconfirmedAt": "2019-08-24T14:15:22Z"    }  ],  "nextCursor": "string"}