Skip to main content
GET
List appointments

Authorizations

Authorization
string
header
required

Service (M2M) access token issued by POST /auth/token using the client_credentials grant. Required scopes, where known, are listed on each operation below.

Query Parameters

patient_id
string<uuid>

Anchor the read to one patient, as returned by POST /patients. Lifts the time window — the full history is returned.

provider_id
string<uuid>

Only appointments assigned to this provider.

appointment_type_id
string<uuid>

Only appointments of this type.

status
enum<string>

Lifecycle state.

Available options:
open,
closed
outcome
enum<string>

How a closed appointment ended. unresolved is a real outcome — a reopen that found nobody to take the window leaves it — but it is not a filter value here.

Available options:
completed,
no_show,
cancelled
from
string

Inclusive lower bound on the appointment's start. An ISO 8601 timestamp with an offset, or a bare YYYY-MM-DD date (which requires timezone). Defaults to 7 days ago.

Required string length: 1 - 64
to
string

Upper bound on the appointment's start. Its meaning follows its shape: a bare YYYY-MM-DD date means through the end of that local day (so from=to returns exactly one day), while a timestamp is exclusive of that instant. Defaults to 24 days out.

Required string length: 1 - 64
timezone
string

IANA zone id (e.g. America/Los_Angeles). Required when from or to is a bare date, ignored when both are timestamps. Send what the browser reports: Intl.DateTimeFormat().resolvedOptions().timeZone. Abbreviations like PST are not zone ids.

Required string length: 1 - 64
sort
enum<string>
default:asc

Order by start time.

Available options:
asc,
desc
cursor
string

Opaque after or before value from a previous response, passed back verbatim. It carries its own direction, so there is no separate paging parameter. Validated strictly and bound to the filters it was issued for — a modified cursor, or one replayed against a different filter set, returns 400. limit is not part of that binding, so page size may change mid-walk.

Maximum string length: 8192
Pattern: ^[A-Za-z0-9_-]+$
limit
default:25

Maximum appointments per page. Defaults to 25. There is no declared maximum, so a larger value is accepted rather than rejected, but the page size is capped at 100 — ask for more and you get 100. Values below 1 return 400.

Required range: x >= 1

Response

A page of your appointments.

items
object[]
required
request_id
string
required
after
string

Cursor for the next page. Absent only when there are no further pages.

before
string

Cursor for the previous page. Absent on the first page of a walk.