{"openapi":"3.1.0","info":{"title":"Cliniko (BYOK) API","version":"0.1.0","description":"Cliniko (BYOK) lets an AI assistant read your own Cliniko data through the Cliniko API with a key you supply (Cliniko API key). Read-only: 9 tools (get_authenticated_user, get_public_settings, list_businesses, list_practitioners, list_appointment_types, list_appointments, get_available_times, list_billable_items, list_products). The BYOK key travels with each request, is used for that one call...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-cliniko.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-cliniko/docs"},"termsOfService":"https://connectorbay.com/byok-cliniko/terms"},"servers":[{"url":"https://byok-cliniko.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-cliniko/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_authenticated_user":{"post":{"operationId":"get_authenticated_user","summary":"Show the Cliniko user the API key belongs to: name, role, active flag and time zone. Use for \"Which Cliniko user is my A","description":"Show the Cliniko user the API key belongs to: name, role, active flag and time zone. Use for \"Which Cliniko user is my API key connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shard":{"description":"Cliniko shard of the account: the suffix at the end of the API key, for example 'au2' (au1 to au5, ca1, uk1 to uk3, us1, eu1). Keys without a suffix use 'au1'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Shard","type":"string"}},"required":["shard"],"title":"get_authenticated_userArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_public_settings":{"post":{"operationId":"get_public_settings","summary":"Get the Cliniko account's public settings: account name, country, currency, calendar hours and slot size, online booking","description":"Get the Cliniko account's public settings: account name, country, currency, calendar hours and slot size, online booking rules and whether it says patient or client. Use for \"What are my Cliniko calendar hours and online booking settings\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shard":{"description":"Cliniko shard of the account: the suffix at the end of the API key, for example 'au2' (au1 to au5, ca1, uk1 to uk3, us1, eu1). Keys without a suffix use 'au1'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Shard","type":"string"}},"required":["shard"],"title":"get_public_settingsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_businesses":{"post":{"operationId":"list_businesses","summary":"List the businesses (clinic locations) of the account with name, address, time zone and whether they appear in online bo","description":"List the businesses (clinic locations) of the account with name, address, time zone and whether they appear in online bookings. Use for \"What locations does my Cliniko account have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shard":{"description":"Cliniko shard of the account: the suffix at the end of the API key, for example 'au2' (au1 to au5, ca1, uk1 to uk3, us1, eu1). Keys without a suffix use 'au1'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Shard","type":"string"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Results per page (1 to 100, default 50).","title":"Per Page"}},"required":["shard"],"title":"list_businessesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_practitioners":{"post":{"operationId":"list_practitioners","summary":"List the practitioners (staff who take appointments) with name, title, designation, active flag and online booking visib","description":"List the practitioners (staff who take appointments) with name, title, designation, active flag and online booking visibility. Use for \"Which practitioners work at my Cliniko clinic\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shard":{"description":"Cliniko shard of the account: the suffix at the end of the API key, for example 'au2' (au1 to au5, ca1, uk1 to uk3, us1, eu1). Keys without a suffix use 'au1'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Shard","type":"string"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Results per page (1 to 100, default 50).","title":"Per Page"}},"required":["shard"],"title":"list_practitionersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_appointment_types":{"post":{"operationId":"list_appointment_types","summary":"List appointment types with name, category, duration in minutes, maximum attendees, telehealth and online booking flags ","description":"List appointment types with name, category, duration in minutes, maximum attendees, telehealth and online booking flags and payment mode. Use for \"What appointment types and durations does my Cliniko clinic offer\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shard":{"description":"Cliniko shard of the account: the suffix at the end of the API key, for example 'au2' (au1 to au5, ca1, uk1 to uk3, us1, eu1). Keys without a suffix use 'au1'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Shard","type":"string"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Results per page (1 to 100, default 50).","title":"Per Page"}},"required":["shard"],"title":"list_appointment_typesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_appointments":{"post":{"operationId":"list_appointments","summary":"List individual appointments with start and end time, cancellation, arrival, invoice and treatment-note status and links","description":"List individual appointments with start and end time, cancellation, arrival, invoice and treatment-note status and links to the practitioner, business and appointment type. Patient names and notes are not returned. Filter by time to keep answers short. Use for \"What appointments are booked in my Cliniko clinic from 1 October 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shard":{"description":"Cliniko shard of the account: the suffix at the end of the API key, for example 'au2' (au1 to au5, ca1, uk1 to uk3, us1, eu1). Keys without a suffix use 'au1'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Shard","type":"string"},"filter":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Optional filter in Cliniko syntax 'field:operator value', for example 'starts_at:>=2026-10-01T00:00:00Z'. Filterable fields include starts_at, ends_at, practitioner_id, business_id, appointment_type_id and cancelled_at.","title":"Filter"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Results per page (1 to 100, default 50).","title":"Per Page"}},"required":["shard"],"title":"list_appointmentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_available_times":{"post":{"operationId":"get_available_times","summary":"List the open appointment start times for one practitioner, business and appointment type in a window of at most seven d","description":"List the open appointment start times for one practitioner, business and appointment type in a window of at most seven days (not in the past). Use for \"When is Cliniko practitioner 11 free for appointment type 21 at business 1 next week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shard":{"description":"Cliniko shard of the account: the suffix at the end of the API key, for example 'au2' (au1 to au5, ca1, uk1 to uk3, us1, eu1). Keys without a suffix use 'au1'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Shard","type":"string"},"business_id":{"description":"ID of the business (clinic location), from list_businesses.","maxLength":20,"title":"Business Id","type":"string"},"practitioner_id":{"description":"ID of the practitioner, from list_practitioners.","maxLength":20,"title":"Practitioner Id","type":"string"},"appointment_type_id":{"description":"ID of the appointment type, from list_appointment_types.","maxLength":20,"title":"Appointment Type Id","type":"string"},"from_date":{"description":"First day of the window, YYYY-MM-DD; not before today in the account's time zone.","maxLength":10,"title":"From Date","type":"string"},"to_date":{"description":"Last day of the window, YYYY-MM-DD; at most seven days after the first day.","maxLength":10,"title":"To Date","type":"string"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Results per page (1 to 100, default 50).","title":"Per Page"}},"required":["shard","business_id","practitioner_id","appointment_type_id","from_date","to_date"],"title":"get_available_timesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_billable_items":{"post":{"operationId":"list_billable_items","summary":"List billable items (services and products that can be put on invoices) with code, type and price. Use for \"What service","description":"List billable items (services and products that can be put on invoices) with code, type and price. Use for \"What services and prices are set up in my Cliniko account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shard":{"description":"Cliniko shard of the account: the suffix at the end of the API key, for example 'au2' (au1 to au5, ca1, uk1 to uk3, us1, eu1). Keys without a suffix use 'au1'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Shard","type":"string"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Results per page (1 to 100, default 50).","title":"Per Page"}},"required":["shard"],"title":"list_billable_itemsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_products":{"post":{"operationId":"list_products","summary":"List stocked products with code, price with and without tax and current stock level. Use for \"How much stock of each pro","description":"List stocked products with code, price with and without tax and current stock level. Use for \"How much stock of each product do I have in Cliniko\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shard":{"description":"Cliniko shard of the account: the suffix at the end of the API key, for example 'au2' (au1 to au5, ca1, uk1 to uk3, us1, eu1). Keys without a suffix use 'au1'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Shard","type":"string"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Results per page (1 to 100, default 50).","title":"Per Page"}},"required":["shard"],"title":"list_productsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}