Cliniko Appointments & Availability
For physio, chiro and allied-health clinics on Cliniko: find the next open slot for a practitioner and appointment type, book it for a new or returning patient, and move or cancel appointments with Cliniko's cancellation reasons, all without opening the calendar.
Connect this API to an AI agent Browse all specs
What you can do with Cliniko Appointments & Availability via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /businesses |
listBusinesses | List clinic locations (businesses) |
| GET | /practitioners |
listPractitioners | List active practitioners |
| GET | /appointment_types |
listAppointmentTypes | List appointment types with their durations |
| GET | /practitioners/{practitioner_id}/appointment_types |
listPractitionerAppointmentTypes | List appointment types a practitioner offers |
| GET | /businesses/{business_id}/practitioners/{practitioner_id}/appointment_types/{appointment_type_id}/next_available_time |
getNextAvailableTime | Get the next free start time for a practitioner and type |
| GET | /businesses/{business_id}/practitioners/{practitioner_id}/appointment_types/{appointment_type_id}/available_times |
getAvailableTimes | List free start times in a range of up to 7 days |
| GET | /individual_appointments |
listAppointments | List or filter individual appointments |
| POST | /individual_appointments |
createAppointment | Book an appointment for a patient |
| GET | /individual_appointments/{id} |
getAppointment | Get one appointment |
| PATCH | /individual_appointments/{id} |
updateAppointment | Reschedule or edit an appointment |
| PATCH | /individual_appointments/{id}/cancel |
cancelAppointment | Cancel an appointment with a reason |
| GET | /patients |
listPatients | Search patients by name, email or date of birth |
| POST | /patients |
createPatient | Add a new patient |
| GET | /patients/{id} |
getPatient | Get a patient's contact details |
Authentication
basicAuth
HTTP Basic
HTTP basic auth: your Cliniko API key as the username and an empty password.
How to get a credential
- In Cliniko, open My Info (bottom left of the navigation).
- Click Manage API keys and create a key; name it (e.g.
VX Agents). - Copy the key; it is shown only once. The part after the last
-(e.g.au1,uk1,ca1) is your shard: set it as theshardserver variable.
Permissions used
The key acts as the user who created it, with that user's Cliniko role.
| Role needed | Operations |
|---|---|
| Any user who can see the appointment book | listBusinesses, listPractitioners, listAppointmentTypes, listPractitionerAppointmentTypes, getAvailableTimes, getNextAvailableTime, listAppointments, getAppointment, listPatients, getPatient |
| Receptionist or above | createAppointment, updateAppointment, cancelAppointment, createPatient |
Common errors
- 401 Unauthorized: wrong key, empty username, or the key belongs to another shard. Check the
shardserver variable matches the key's suffix. - 403 Forbidden: the user's role cannot see or change this record.
- 422 Unprocessable Entity: invalid body, e.g. a time outside the practitioner's availability window or a missing
patient_id. - 429 Too Many Requests: limit is 200 requests per minute per user; wait and retry.
Cliniko asks API clients to send a User-Agent naming the app and a contact email. Store the key as a VX Agents credential so it is never pasted into chat.
Usage guide
Setup
- Add a basic-auth credential: Cliniko API key as username, empty password (My Info > Manage API keys).
- Set the
shardserver variable to the suffix of the key (au1,uk1,ca1, ...); a key only works on its own shard. - Call
listBusinesses,listPractitionersandlistAppointmentTypesonce and pin thebusiness_id(clinic location) and the ids you book most.
Book an appointment
- Find the patient:
listPatientswith filters such asq[]=last_name:=Smith,q[]=email:[email protected]orq[]=first_name:~bri(~= contains). Combine severalq[]filters to narrow down. - New patient? Confirm the details with the user, then
createPatientwithfirst_name,last_nameand contact fields (email,patient_phone_numbers,date_of_birth). listPractitionerAppointmentTypesto check the practitioner offers the type.getNextAvailableTimefor the soonest slot, orgetAvailableTimeswithfromandto(YYYY-MM-DD, at most 7 days apart, not in the past).- Read the slot back to the user and wait for confirmation, then
createAppointmentwithpatient_id,practitioner_id,appointment_type_id,business_idandstarts_at(ISO 8601 with offset, from the available time).ends_atdefaults to the type's duration.
Change or cancel
Confirm with the user first; Cliniko may send the patient a notification.
- Reschedule:
updateAppointmentwith the newstarts_at(andpractitioner_idif it changes). Check availability first. - Cancel:
cancelAppointmentwithcancellation_reason(10 feeling better, 20 condition worse, 30 sick, 40 away, 50 other, 60 work) and optionalcancellation_note.
Look up the day
listAppointments with q[]=starts_at:>2026-10-21T00:00:00Z and q[]=starts_at:<2026-10-22T00:00:00Z, plus q[]=practitioner_id:=<id>; getAppointment for one.
Good to know
- Ids are 64-bit integers sent as strings. Times are ISO 8601 UTC; available times follow the business time zone.
- Lists page with
pageandper_page(max 100); followlinks.next. - Rate limit: 200 requests per minute per user.
- Cliniko asks API clients to send a
User-Agentwith an app name and contact email and may block requests without one. - This spec cannot archive or delete patients or appointments, and does not touch invoices or treatment notes.
Source: Cliniko API reference (https://docs.api.cliniko.com/openapi), checked 2026-10-21.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Cliniko Appointments & Availability” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.