API reference

Appointments

Bookings at a venue. 4 operations under /public/v1, with parameters, request bodies and example responses.

Paths are relative to the API host: https://sandbox-api.clivehealth.app for the sandbox, https://api.clivehealth.app for production. Send Authorization: Bearer <token> on every request (Getting started).

Operations

GET/public/v1/appointmentsList appointments
POST/public/v1/appointmentsBook an appointment
GET/public/v1/appointments/{id}Get an appointment
POST/public/v1/appointments/{id}/cancelCancel an appointment

List appointments

GET/public/v1/appointments

Scope appointments:readOperation listAppointments

Ordered by updated_at then id. from and to filter on start_time.

Requires scope appointments:read.

Parameters

listAppointments parameters
Name	In	Type	Description
`limit`	query	`integer`	Page size, 1 to 200. Default `50`.
`cursor`	query	`string`	Opaque cursor from the previous page's `next_cursor`.
`updated_since`	query	`string (date-time)`	ISO 8601 timestamp: only records updated at or after it. Lists are ordered by `updated_at` then `id`, so this plus `cursor` is a change feed.
`member_id`	query	`string (uuid)`
`venue_id`	query	`string (uuid)`
`from`	query	`string (date-time)`	Appointments starting at or after this time.
`to`	query	`string (date-time)`	Appointments starting before this time.
`status`	query	`"scheduled" \| "confirmed" \| "checked_in" \| "in_progress" \| "completed" \| "cancelled" \| "no_show"`

Responses

200A page of appointments.Returns AppointmentPage.

listAppointments 200 response
Field	Type	Description
`data`required	`array of Appointment`
`id`required	`string (uuid)`
`member_id`required	`string (uuid)`
`venue_id`required	`string (uuid)`
`practitioner_id`required	`string (uuid)`
`start_time`required	`string (date-time)`
`end_time`required	`string (date-time)`
`duration_minutes`required	`integer`
`type`required	`string`	Service or treatment type.
`status`required	`"scheduled" \| "confirmed" \| "checked_in" \| "in_progress" \| "completed" \| "cancelled" \| "no_show"`
`cancel_reason`required	`string or null`
`source`required	`string or null`	How it was booked: `partner_api`, `online_booking`, `manual`, ...
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`
`next_cursor`required	`string or null`	Pass as `cursor` to fetch the next page; null on the last page.
`has_more`required	`boolean`

Response 200JSON

{
  "data": [
    {
      "id": "c41f7a52-8d1e-4b2a-9f3c-6e5d4c3b2a10",
      "member_id": "0b8e3c6a-2d4f-4e1b-9a7c-5d3e1f2a4b6c",
      "venue_id": "c41f7a52-8d1e-4b2a-9f3c-6e5d4c3b2a10",
      "practitioner_id": "3f6b8d0a-2c4e-4f1a-9b3d-5e7f9a1c3e5b",
      "start_time": "2026-10-24T01:30:00.000Z",
      "end_time": "2026-10-24T02:00:00.000Z",
      "duration_minutes": 30,
      "type": "consultation",
      "status": "scheduled",
      "cancel_reason": null,
      "source": "partner",
      "created_at": "2026-10-01T00:00:00.000Z",
      "updated_at": "2026-10-24T02:15:09.123Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

listAppointments error responses
Status	Meaning
400	Malformed request or invalid cursor.
401	Missing, invalid or expired access token, or the API client was revoked (INVALID_TOKEN).
403	The token lacks the scope this operation needs (INSUFFICIENT_SCOPE).
422	Validation failed (VALIDATION_ERROR).
429	Per-client rate limit exceeded (RATE_LIMITED).
500	Unexpected error (INTERNAL_ERROR).

Every error body is the error envelope; branch on its code.

Book an appointment

POST/public/v1/appointments

Scope appointments:writeOperation createAppointment

Books the member at the venue. 409 SLOT_TAKEN when the practitioner (or every practitioner at the venue) is busy.

Requires scope appointments:write.

Parameters

createAppointment parameters
Name	In	Type	Description
`Idempotency-Key`required	header	`string`	Unique key for this operation (a UUID is a good choice). Retrying with the same key and request replays the first response for 24 hours.

Request body `AppointmentCreate`

createAppointment request body
Field	Type	Description
`member_id`required	`string (uuid)`
`venue_id`required	`string (uuid)`
`start_time`required	`string (date-time)`	ISO 8601 with offset; must be in the future.
`duration_minutes`	`integer`	Defaults to the clinic's slot length.
`type`required	`string`
`practitioner_id`	`string (uuid)`	A specific practitioner; otherwise the first free practitioner at the venue is assigned.

Example requestJSON

{
  "member_id": "0b8e3c6a-2d4f-4e1b-9a7c-5d3e1f2a4b6c",
  "venue_id": "c41f7a52-8d1e-4b2a-9f3c-6e5d4c3b2a10",
  "start_time": "2026-10-24T01:30:00.000Z",
  "duration_minutes": 30,
  "type": "consultation",
  "practitioner_id": "3f6b8d0a-2c4e-4f1a-9b3d-5e7f9a1c3e5b"
}

Responses

201The new appointment.Returns Appointment.

createAppointment 201 response
Field	Type	Description
`id`required	`string (uuid)`
`member_id`required	`string (uuid)`
`venue_id`required	`string (uuid)`
`practitioner_id`required	`string (uuid)`
`start_time`required	`string (date-time)`
`end_time`required	`string (date-time)`
`duration_minutes`required	`integer`
`type`required	`string`	Service or treatment type.
`status`required	`"scheduled" \| "confirmed" \| "checked_in" \| "in_progress" \| "completed" \| "cancelled" \| "no_show"`
`cancel_reason`required	`string or null`
`source`required	`string or null`	How it was booked: `partner_api`, `online_booking`, `manual`, ...
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`

Response 201JSON

{
  "id": "c41f7a52-8d1e-4b2a-9f3c-6e5d4c3b2a10",
  "member_id": "0b8e3c6a-2d4f-4e1b-9a7c-5d3e1f2a4b6c",
  "venue_id": "c41f7a52-8d1e-4b2a-9f3c-6e5d4c3b2a10",
  "practitioner_id": "3f6b8d0a-2c4e-4f1a-9b3d-5e7f9a1c3e5b",
  "start_time": "2026-10-24T01:30:00.000Z",
  "end_time": "2026-10-24T02:00:00.000Z",
  "duration_minutes": 30,
  "type": "consultation",
  "status": "scheduled",
  "cancel_reason": null,
  "source": "partner",
  "created_at": "2026-10-01T00:00:00.000Z",
  "updated_at": "2026-10-24T02:15:09.123Z"
}

createAppointment error responses
Status	Meaning
400	Malformed request, invalid cursor, or missing Idempotency-Key (IDEMPOTENCY_KEY_REQUIRED).
401	Missing, invalid or expired access token, or the API client was revoked (INVALID_TOKEN).
403	The token lacks the scope this operation needs (INSUFFICIENT_SCOPE).
409	Conflict, or a request with the same Idempotency-Key is still in flight (IDEMPOTENCY_IN_PROGRESS).
422	Validation failed (VALIDATION_ERROR), or the Idempotency-Key was used for a different request (IDEMPOTENCY_KEY_REUSED).
429	Per-client rate limit exceeded (RATE_LIMITED).
500	Unexpected error (INTERNAL_ERROR).

Every error body is the error envelope; branch on its code.

Get an appointment

GET/public/v1/appointments/{id}

Scope appointments:readOperation getAppointment

Requires scope appointments:read.

Parameters

getAppointment parameters
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200The appointment.Returns Appointment.

getAppointment 200 response
Field	Type	Description
`id`required	`string (uuid)`
`member_id`required	`string (uuid)`
`venue_id`required	`string (uuid)`
`practitioner_id`required	`string (uuid)`
`start_time`required	`string (date-time)`
`end_time`required	`string (date-time)`
`duration_minutes`required	`integer`
`type`required	`string`	Service or treatment type.
`status`required	`"scheduled" \| "confirmed" \| "checked_in" \| "in_progress" \| "completed" \| "cancelled" \| "no_show"`
`cancel_reason`required	`string or null`
`source`required	`string or null`	How it was booked: `partner_api`, `online_booking`, `manual`, ...
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`

Response 200JSON

{
  "id": "c41f7a52-8d1e-4b2a-9f3c-6e5d4c3b2a10",
  "member_id": "0b8e3c6a-2d4f-4e1b-9a7c-5d3e1f2a4b6c",
  "venue_id": "c41f7a52-8d1e-4b2a-9f3c-6e5d4c3b2a10",
  "practitioner_id": "3f6b8d0a-2c4e-4f1a-9b3d-5e7f9a1c3e5b",
  "start_time": "2026-10-24T01:30:00.000Z",
  "end_time": "2026-10-24T02:00:00.000Z",
  "duration_minutes": 30,
  "type": "consultation",
  "status": "scheduled",
  "cancel_reason": null,
  "source": "partner",
  "created_at": "2026-10-01T00:00:00.000Z",
  "updated_at": "2026-10-24T02:15:09.123Z"
}

getAppointment error responses
Status	Meaning
400	Malformed request or invalid cursor.
401	Missing, invalid or expired access token, or the API client was revoked (INVALID_TOKEN).
403	The token lacks the scope this operation needs (INSUFFICIENT_SCOPE).
404	No such record in this clinic (NOT_FOUND).
422	Validation failed (VALIDATION_ERROR).
429	Per-client rate limit exceeded (RATE_LIMITED).
500	Unexpected error (INTERNAL_ERROR).

Every error body is the error envelope; branch on its code.

Cancel an appointment

POST/public/v1/appointments/{id}/cancel

Scope appointments:writeOperation cancelAppointment

Cancelling an already-cancelled appointment returns it unchanged. Appointments in progress or completed can't be cancelled (409).

Requires scope appointments:write.

Parameters

cancelAppointment parameters
Name	In	Type	Description
`id`required	path	`string (uuid)`
`Idempotency-Key`required	header	`string`	Unique key for this operation (a UUID is a good choice). Retrying with the same key and request replays the first response for 24 hours.

Request body `AppointmentCancel`

cancelAppointment request body
Field	Type	Description
`reason`	`string`

Example requestJSON

{
  "reason": "Member requested"
}

Responses

200The cancelled appointment.Returns Appointment.

cancelAppointment 200 response
Field	Type	Description
`id`required	`string (uuid)`
`member_id`required	`string (uuid)`
`venue_id`required	`string (uuid)`
`practitioner_id`required	`string (uuid)`
`start_time`required	`string (date-time)`
`end_time`required	`string (date-time)`
`duration_minutes`required	`integer`
`type`required	`string`	Service or treatment type.
`status`required	`"scheduled" \| "confirmed" \| "checked_in" \| "in_progress" \| "completed" \| "cancelled" \| "no_show"`
`cancel_reason`required	`string or null`
`source`required	`string or null`	How it was booked: `partner_api`, `online_booking`, `manual`, ...
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`

Response 200JSON

{
  "id": "c41f7a52-8d1e-4b2a-9f3c-6e5d4c3b2a10",
  "member_id": "0b8e3c6a-2d4f-4e1b-9a7c-5d3e1f2a4b6c",
  "venue_id": "c41f7a52-8d1e-4b2a-9f3c-6e5d4c3b2a10",
  "practitioner_id": "3f6b8d0a-2c4e-4f1a-9b3d-5e7f9a1c3e5b",
  "start_time": "2026-10-24T01:30:00.000Z",
  "end_time": "2026-10-24T02:00:00.000Z",
  "duration_minutes": 30,
  "type": "consultation",
  "status": "scheduled",
  "cancel_reason": null,
  "source": "partner",
  "created_at": "2026-10-01T00:00:00.000Z",
  "updated_at": "2026-10-24T02:15:09.123Z"
}

cancelAppointment error responses
Status	Meaning
400	Malformed request, invalid cursor, or missing Idempotency-Key (IDEMPOTENCY_KEY_REQUIRED).
401	Missing, invalid or expired access token, or the API client was revoked (INVALID_TOKEN).
403	The token lacks the scope this operation needs (INSUFFICIENT_SCOPE).
404	No such record in this clinic (NOT_FOUND).
409	Conflict, or a request with the same Idempotency-Key is still in flight (IDEMPOTENCY_IN_PROGRESS).
422	Validation failed (VALIDATION_ERROR), or the Idempotency-Key was used for a different request (IDEMPOTENCY_KEY_REUSED).
429	Per-client rate limit exceeded (RATE_LIMITED).
500	Unexpected error (INTERNAL_ERROR).

Every error body is the error envelope; branch on its code.

Operations

List appointments

Parameters

Responses

Book an appointment

Parameters

Request body AppointmentCreate

Responses

Get an appointment

Parameters

Responses

Cancel an appointment

Parameters

Request body AppointmentCancel

Responses

Request body `AppointmentCreate`

Request body `AppointmentCancel`