Developers

Changelog

Every change to the Claro public API contract, newest first.

2026-10-31: a host per region, and keys that name theirs#

  • The API's hosts are now https://api-au.claro.clinic/api/public/v1 and https://api-us.claro.clinic/api/public/v1. The spec's servers name them.
  • New API keys carry their region: claro_sk_live_au_…, claro_sk_live_us_…, and claro_sk_test_au_… / claro_sk_test_us_… on the sandbox.
  • A key sent to the other region gets 421 wrong_region, with the right base URL in param.
  • Older claro_k keys work as before.

2026-10-31: catch-up, and public IDs in webhooks#

  • New: GET /events lists what one webhook subscription was sent, with the same webhook-ids. It needs the new events:read scope.
  • Webhook subscriptions have a public ID, whsub_….
  • Webhook payloads now carry clinic_public_id, patient_public_id, appointment_public_id and practitioner_public_id beside the internal references, so you can re-fetch each record.

2026-10-31: one error shape on every path#

  • An unknown path gets 404 route_not_found under any method.
  • A known path with the wrong method gets 405 method_not_allowed, with an Allow header.

2026-10-31: new clinic controls in Claro#

  • Apps that can read clinical content, in Manage → Integrations: where a clinic allows or withdraws your app's clinical-content access.
  • The key picker offers Read practitioners, Read webhook events (catch-up) and Read clinical content.
  • Change signing secret on each webhook, with a 24-hour overlap or an immediate end for a leaked secret.

2026-10-31: v1 launches#

Claro-Version: 2026-11-01. Live in Australia and the United States.

  • Read endpoints for clinics, practitioners, patients and appointments, each as a list and by ID.
  • Cursor pagination on every list, and updated_since on patients and appointments.
  • One error format, RateLimit-* headers, and Idempotency-Key support ready for writes.
  • Three data classes: operational, clinical metadata and clinical content.
  • New API keys: claro_sk_live_…, and claro_sk_test_… for the sandbox.
  • New scopes: practitioners:read and clinical_content:read.
  • external_ids on every object.
  • The OpenAPI document and llms.txt, served by the API with no key.

2026-10-30: webhooks follow Standard Webhooks#

  • Every delivery carries webhook-id, webhook-timestamp and webhook-signature.
  • New signing secrets start whsec_, so Standard Webhooks libraries take them as they are.
  • Rotating a secret keeps the old one signing for an overlap window, 24 hours by default.
  • The older x-claro-signature header is still sent.