Carepatron Public API

The Carepatron Public API gives you programmatic access to core Carepatron functionality - the same healthcare practice-management and EHR platform your team uses in the app. Use it to integrate Carepatron with your own systems and to automate workflows.

This page is the starting point.
For the full, interactive reference - every endpoint, parameter, and schema - see the API reference.
The raw OpenAPI specification is published at /openapi.yaml and /openapi.json for tooling and code generation.

Base URL

All requests go to:

https://api.carepatron.com

Authentication

The API authenticates each request with an API key sent in a request header. Create a key at developer.carepatron.com, then send it with every call.

See the API reference for the exact header name, the key format, and the scopes each endpoint requires. These are described authoritatively in the specification, so they never drift from what the API actually enforces.

Treat API keys as secrets: never embed them in client-side code or commit them to source control. They are bearer tokens - whoever has the key can use it to do anything the API allows for the scopes the key was granted. To confine an App's keys to your own network, list your source addresses in the App's IP allowlist in the Developer Console: a request with any of its keys from anywhere else is refused with 403 ip_not_allowed. Callers that reach the API over IPv6 need their IPv6 range listed.

Signing in to the Developer Console

Login to the Developer Console occurs via a UI hosted by the same secure store (AWS Cognito) that holds user login details for the Carepatron App. This login UI affords limited design changes - while we have plans to update and improve this we are currently restricted in how we design the login form and so it does not look as polished as we would like. It is however legitimate, so long as it is hosted at auth.carepatron.com.

Versioning

The API is versioned by date. Each request carries the API version it was written against in the cp-api-version header, so your integration keeps working as the API evolves. API versions lists every supported version and what changed at each, and links each version's whole contract.

Conventions

• Errors are RFC 9457 problem documents (application/problem+json): a machine-readable type URI that opens the error reference, a human-readable title, an occurrence-specific detail, and an instance trace identifier. Branch on the code at the end of that URI rather than the whole URI - the code is immutable, the prefix is not. A refused request body carries one further member, errors - see Validation errors.
• HTTPS only: a request over plain http:// is refused with a 403, not redirected. Its API key has already crossed the network unencrypted, so replace a key you have sent that way.
• Rate limits are reported through the RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers on every response the gateway's limiter answered. A refusal before it - a missing, malformed, rejected or wrong-environment key, a tenant-path refusal, a source address outside the App's IP allowlist, a 503 - and a refusal from the edge carry none, and while the limiter's store is unavailable a request is served without them. A 429 means slow down and retry after the window resets.
• Idempotency: every POST requires an Idempotency-Key header. A resend with the same key within two hours is answered with the first response, marked Idempotent-Replayed: true, a refusal included; a request the gateway could not complete, such as one answered 504, may be executed again when resent. Every other write is a PUT or a DELETE, which is idempotent by its method, so a retry needs no key.
• Long-running work (for example, exporting contacts) returns 202 Accepted with a job you poll until it succeeds or fails.
• Request size: a request body may be at most 1 MiB (1,048,576 bytes), and a POST body at most 64 KiB (65,536 bytes). A larger body is refused with 413. These caps apply to the whole body, whatever the bounds on its individual fields allow.

Next steps

• Browse the interactive API reference.
• Download the specification: /openapi.yaml or /openapi.json.
• See what became generally available, and when, in the changelog.