API reference
The complete, authoritative Platform API reference — generated from the OpenAPI specification.
API reference
Every endpoint below is generated from the platform OpenAPI specification, the single source of truth for the request/response shape, scopes, schemas, and status codes. Browse the resource groups in the sidebar — Platform Patients, Platform Webhooks, and the SDK Connect / records / catalog surfaces.
- Download the spec (OpenAPI 3.1):
/openapi-platform.yaml
The spec is public on purpose — the auth contract on every endpoint guards the
bytes regardless of who can read the description. It documents only the public
Platform surface (/api/platform/v1/*, /api/sdk/v1/*).
Generate a client
Because the contract is OpenAPI 3.1, you can generate types or a client in any
language from /openapi-platform.yaml. For
TypeScript, prefer the maintained @curaeai/platform-sdk — it adds the Connect
widget, the webhook sign/verify helpers, retries, idempotency, and typed
webhook unions on top of the raw types.
Surfaces at a glance
| Area | Path prefix |
|---|---|
| Patient profile (point read) | /api/platform/v1/patients/{id} |
| Webhook endpoints | /api/platform/v1/webhook-endpoints |
| Connect catalog | /api/sdk/v1/catalog/brands |
| Connections | /api/sdk/v1/connections |
| Resource search | /api/sdk/v1/observations:search, /conditions:search, /immunizations:search |
| Records export | /api/sdk/v1/records/exports |
| Signals | /api/sdk/v1/signals |
See API conventions for the cross-cutting rules (errors, pagination, idempotency, versioning) that apply to all of them.
API conventions
The cross-cutting contract — errors, pagination, idempotency, conditional reads, versioning, and rate limits — that every endpoint follows.
Retrieve a Platform patient profile GET
Retrieves the patient profile resource visible to the API key. The route enforces, in order: API-key scope (`patient:read`), Platform authorization (SpiceDB tuple-constraint resolution), tenant membership, and an RLS-backed Prisma read. Authorization-layer denials — including cross-tenant access attempts — surface as `403 PLATFORM_ACCESS_DENIED` with a uniform message that does not reveal whether the patient exists in another tenant. Resources that pass authorization but are absent from the caller's tenant via the RLS-backed read resolve as `404 NOT_FOUND`. See `Docs/architecture/PLATFORM_API_ARCHITECTURE.md` §7.4 for the tenant-leak-safe error contract.