API reference

Venues

The clinic's branches. 2 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).

List venues

GET/public/v1/venues

Scope venues:readOperation listVenues

The clinic's active branches, ordered by updated_at then id.

Requires scope venues:read.

Parameters

listVenues 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.

Responses

200A page of venues.Returns VenuePage.

listVenues 200 response
Field	Type	Description
`data`required	`array of Venue`
`id`required	`string (uuid)`
`name`required	`string`
`address`required	`string or null`
`phone`required	`string or null`
`timezone`required	`string`	IANA time zone, e.g. Asia/Kuala_Lumpur.
`is_default`required	`boolean`	The clinic's main branch.
`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",
      "name": "Clive Clinic KL Sentral",
      "address": "1 Jalan Ampang, 50450 Kuala Lumpur",
      "phone": "+60123456789",
      "timezone": "Asia/Kuala_Lumpur",
      "is_default": true,
      "created_at": "2026-10-01T00:00:00.000Z",
      "updated_at": "2026-10-24T02:15:09.123Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

listVenues 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.

Get a venue

GET/public/v1/venues/{id}

Scope venues:readOperation getVenue

Requires scope venues:read.

Parameters

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

Responses

200The venue.Returns Venue.

getVenue 200 response
Field	Type	Description
`id`required	`string (uuid)`
`name`required	`string`
`address`required	`string or null`
`phone`required	`string or null`
`timezone`required	`string`	IANA time zone, e.g. Asia/Kuala_Lumpur.
`is_default`required	`boolean`	The clinic's main branch.
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`

Response 200JSON

{
  "id": "c41f7a52-8d1e-4b2a-9f3c-6e5d4c3b2a10",
  "name": "Clive Clinic KL Sentral",
  "address": "1 Jalan Ampang, 50450 Kuala Lumpur",
  "phone": "+60123456789",
  "timezone": "Asia/Kuala_Lumpur",
  "is_default": true,
  "created_at": "2026-10-01T00:00:00.000Z",
  "updated_at": "2026-10-24T02:15:09.123Z"
}

getVenue 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.