API reference

Availability

Bookable slots. 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).

Operations

GET/public/v1/venues/{id}/availabilityA venue's opening days
GET/public/v1/availabilityBookable slots at a venue on a day

A venue's opening days

GET/public/v1/venues/{id}/availability

Scope availability:readOperation getVenueAvailability

Day by day: open intervals, or why the day is closed. At most 62 days per request; from defaults to today at the venue and to to 27 days later.

Requires scope availability:read.

Parameters

getVenueAvailability parameters
Name	In	Type
`id`required	path	`string (uuid)`
`from`	query	`string`
`to`	query	`string`

Responses

200The venue's days.Returns VenueAvailability.

getVenueAvailability 200 response
Field	Type	Description
`venue_id`required	`string (uuid)`
`timezone`required	`string`
`from`required	`string`
`to`required	`string`
`days`required	`array of VenueDay`
`date`required	`string`	YYYY-MM-DD in the venue's time zone.
`closed`required	`boolean`
`closure`required	`object or null`
`source`required	`"local" \| "holiday" \| "partner"`	Who closed it: the clinic, a partner, or a public holiday.
`reason`required	`string or null`
`open`required	`array of object`	Opening intervals as UTC instants; empty when closed.
`start`required	`string (date-time)`
`end`required	`string (date-time)`

Response 200JSON

{
  "venue_id": "c41f7a52-8d1e-4b2a-9f3c-6e5d4c3b2a10",
  "timezone": "Asia/Kuala_Lumpur",
  "from": "string",
  "to": "string",
  "days": [
    {
      "date": "2026-11-02",
      "closed": true,
      "closure": {
        "source": "local",
        "reason": null
      },
      "open": [
        {
          "start": "2026-10-24T01:30:00.000Z",
          "end": "2026-10-24T02:00:00.000Z"
        }
      ]
    }
  ]
}

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

Bookable slots at a venue on a day

GET/public/v1/availability

Scope availability:readOperation getAvailability

Requires scope availability:read.

Parameters

getAvailability parameters
Name	In	Type	Description
`venue_id`required	query	`string (uuid)`
`date`required	query	`string`	YYYY-MM-DD.

Responses

200The day's slots.Returns Availability.

getAvailability 200 response
Field	Type	Description
`venue_id`required	`string (uuid)`
`date`required	`string`	YYYY-MM-DD in the venue's time zone.
`timezone`required	`string`
`slot_minutes`required	`integer`
`slots`required	`array of Slot`	The day's slot grid; empty for a date in the past or beyond the booking horizon.
`start`required	`string (date-time)`
`end`required	`string (date-time)`
`available`required	`boolean`	Some practitioner at the venue is free for the whole slot, and it has not started.

Response 200JSON

{
  "venue_id": "c41f7a52-8d1e-4b2a-9f3c-6e5d4c3b2a10",
  "date": "2026-11-02",
  "timezone": "Asia/Kuala_Lumpur",
  "slot_minutes": 30,
  "slots": [
    {
      "start": "2026-10-24T01:30:00.000Z",
      "end": "2026-10-24T02:00:00.000Z",
      "available": true
    }
  ]
}

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