Appointments

List and retrieve appointments for the current calendar day, scoped to the authenticated provider's workspace.

Cancelled sessions excluded from appointment linkage. When the appointments endpoint resolves the current session for each appointment, cancelled sessions are not considered. If every session for an appointment has been cancelled, the appointment appears with no linked session - the same state as a freshly startable appointment.

The Appointments endpoints return appointment data for the current calendar day, scoped to the authenticated provider and workspace. Each appointment includes scheduling details, patient and practitioner references, and a link to the associated session when one exists.

Appointments are sourced externally - the platform does not maintain its own appointment store. The current implementation returns a deterministic seed of appointments for the current day. A future release will source appointments from a downstream customer API through a managed External Integration, with no change to the response contract.

Endpoints

Method	Path	Operation	Description
GET	/{workspace_id}/appointments	list-appointments	List appointments over a rolling date-anchored window
GET	/{workspace_id}/appointments/{appointment_id}	get-appointment	Retrieve a single appointment by ID

List Appointments

GET /{workspace_id}/appointments

Returns a paginated list of appointments for the current calendar day. Results are scoped to the authenticated provider and workspace.

Query Parameters

Parameter	Type	Required	Default	Description
limit	integer	No	50	Maximum number of appointments to return (1-200)
continuation_token	string	No	—	Opaque token from a previous response to fetch the next page

Response

{
  "items": [
    {
      "id": "string",
      "session": "uuid or null",
      "start": "2025-07-15T08:00:00Z",
      "end": "2025-07-15T08:45:00Z",
      "duration_minutes": 45,
      "reason": "Therapy Intake",
      "appointment_type": "THERAPY INTAKE",
      "patient_name": "Riley Chen",
      "patient_entity_id": "string",
      "practitioner_name": "Levi Clark",
      "practitioner_entity_id": "string",
      "location_name": "string"
    }
  ],
  "has_more": false,
  "continuation_token": null
}

Get Appointment

GET /{workspace_id}/appointments/{appointment_id}

Returns a single appointment by its ID. Returns 404 if the appointment is not found in the current day's data.

Path Parameters

Parameter	Type	Required	Description
appointment_id	string	Yes	The appointment identifier (max 512 characters)

Response

Returns a single Appointment object (see field reference below).

Appointment Object

Field	Type	Description
id	string	Opaque external appointment identifier (max 512 characters)
session_id	uuid or null	The platform session ID recorded against this appointment, or null if no session exists yet
start	datetime	Appointment start time (UTC)
end	datetime	Appointment end time (UTC)
duration_minutes	integer	Duration in minutes (>= 0)
reason	string	Reason for the appointment (max 256 characters)
appointment_type	string	Appointment type label (max 256 characters)
patient_name	string	Patient display name (max 256 characters)
patient_entity_id	string	Patient entity identifier (max 512 characters)
practitioner_name	string	Practitioner display name (max 256 characters)
practitioner_entity_id	string	Practitioner entity identifier (max 256 characters)
location_name	string	Location display name (max 256 characters)

Session Linking

When a session has been recorded against an appointment, the session_id field contains the platform session identifier. This link is resolved by matching the appointment's id against the session's external appointment reference, scoped to the authenticated provider and workspace. Appointments with no matching session return session_id as null.

Pagination

The list endpoint uses the same offset-based pagination pattern as other list endpoints. When has_more is true, pass the returned continuation_token as a query parameter to retrieve the next page. See Pagination for details.

Error Responses

Status	Description
401	Unauthorized - missing or invalid credentials
403	Forbidden - insufficient permissions for the workspace
404	Appointment not found (get endpoint only)
422	Validation error in request parameters