# Claro Developers

> Documentation for the Claro public API v1: a read-only REST API over clinics, practitioners, patients and appointments, with signed webhooks and a catch-up list of webhook events. Served separately in Australia (https://api-au.claro.clinic/api/public/v1) and the United States (https://api-us.claro.clinic/api/public/v1); an API key names its region (claro_sk_live_au_..., claro_sk_live_us_...). Current Claro-Version: 2026-11-01.

The API publishes its own machine-readable contract. Prefer it for exact shapes:

- [API llms.txt (AU)](https://api-au.claro.clinic/api/public/v1/llms.txt): the API's own summary, served by the API
- [OpenAPI document (AU)](https://api-au.claro.clinic/api/public/v1/openapi.json): the full contract
- [OpenAPI document (US)](https://api-us.claro.clinic/api/public/v1/openapi.json): the same contract, US realm
- [All guides in one file](https://developers.clarohealth.app/llms-full.txt)

## Start here

- [Quickstart](https://developers.clarohealth.app/guides/quickstart.md): Make an API key in Claro, then read your clinic and its patients.
- [Regions](https://developers.clarohealth.app/guides/regions.md): Australia and the United States are separate deployments, each at its own host. A key, and every ID it sees, belongs to one.
- [Authentication and scopes](https://developers.clarohealth.app/guides/authentication.md): Send a key or an OAuth token as a bearer token. Scopes decide which endpoints answer; data classes decide which fields come back.
- [Choosing a clinic](https://developers.clarohealth.app/guides/clinics.md): Every request reads one clinic. Name it in the Claro-Clinic header when your credential reaches more than one.

## Reading data

- [Pagination and incremental sync](https://developers.clarohealth.app/guides/pagination.md): Lists are cursor-paginated. Patients and appointments also take updated_since, so a sync can fetch only what changed.
- [External IDs and matching records](https://developers.clarohealth.app/guides/external-ids.md): Match records by ID, never by name. Every object carries the IDs other systems know it by.
- [Webhooks](https://developers.clarohealth.app/guides/webhooks.md): Claro sends a signed POST when something changes. Verify it with a Standard Webhooks library, skip repeats by webhook-id, then re-fetch.

## Handling responses

- [Errors](https://developers.clarohealth.app/guides/errors.md): Every error has one shape. Branch on type and code; show message to developers only.
- [Rate limits](https://developers.clarohealth.app/guides/rate-limits.md): Each credential has its own budget per 60-second window. The response headers say how much is left.
- [Idempotency keys](https://developers.clarohealth.app/guides/idempotency.md): Send an Idempotency-Key with every POST, so a retry never does the work twice.

## Policies

- [Versioning and changelog](https://developers.clarohealth.app/guides/versioning.md): v1 grows without breaking you. Every response names its version in Claro-Version.
- [Privacy and security](https://developers.clarohealth.app/guides/privacy-security.md): The clinic controls its records. Every read is audited, every field is allowlisted, and some data never leaves.

## Optional

- [Changelog](https://developers.clarohealth.app/changelog.md): every change to the API contract
- [API reference](https://developers.clarohealth.app/reference/): the rendered OpenAPI document (needs JavaScript)