Healthcare API
What a healthcare API is, what to look for in one, and the Anpheros API at a glance: FHIR R4, REST v1, OAuth 2.1, patient-side endpoints, idempotent writes, errors, limits and events.
A healthcare API is a programmatic interface through which software reads and writes health data — patient records, observations, diagnoses, medications, documents — and through which access to that data is authorised. The Anpheros Platform API is a healthcare API over a patient-controlled HL7 FHIR R4 record: applications use it to store and retrieve medical data, to obtain a patient's consent and to be notified of changes.
Kinds of healthcare APIs
| Kind | What it exchanges | Typical use |
|---|---|---|
| FHIR REST APIs | FHIR resources over HTTP (GET /Observation?patient=…) |
the modern standard for clinical data exchange |
| SMART on FHIR / OAuth | authorisation for FHIR APIs | letting third-party apps reach a record with the user's permission |
| HL7 v2 messaging | pipe-delimited messages (ORU^R01 for results, ADT for admissions) |
laboratory and hospital systems, often over interfaces rather than HTTP |
| Document exchange | clinical documents (PDF, CDA, FHIR document bundles) | summaries, discharge letters, referrals |
| Proprietary REST APIs | vendor-specific JSON | a single product's own mobile app or integrations |
Anpheros combines the first two as its core, accepts HL7 v2 laboratory results as input, stores documents with their originals and produces FHIR document bundles (the International Patient Summary). It also offers a simpler REST API over the same data for developers who do not want to work with FHIR directly.
What to look for in a healthcare API
- A standard data model, so data can move between systems without custom mapping.
- Authorisation that the patient controls, not only credentials that the application controls.
- Provenance: who wrote each value, on whose behalf, from which system.
- History: versions instead of silent overwrites.
- Auditability of reads, not only of writes.
- Safe retries (idempotency) and predictable errors, because health data must not be duplicated or lost.
- Isolation between the applications that share the same infrastructure.
- Data residency that matches where the patients are.
The rest of this page shows how each of these appears in the Anpheros API.
The Anpheros API at a glance
| Surface | Base path | Purpose |
|---|---|---|
| FHIR R4 | /fhir/R4 |
26 resource types; read, search, create, update, delete, history, transactions, $everything, $summary, $validate |
| REST v1 | /v1 |
patients, observations, conditions, medications, documents, timeline, provenance, AI context, lab import, terminology, webhooks |
| OAuth 2.1 | /oauth |
consent page, tokens (PKCE), revocation, OpenID Connect keys |
| Patient side | /me |
a person's own records, who has access, access log, revoke |
| Discovery | /fhir/R4/metadata, /fhir/R4/.well-known/smart-configuration, /openapi.json |
machine-readable descriptions of the API |
Base URL: https://platform.anpheros.com. The sandbox and production share it; the key decides the data plane.
Authentication
- API keys (
sk_test_…,sk_live_…) for your servers; they see the patients your project created. - OAuth access tokens (
at_…) for an application acting for one patient under a consent.
curl https://platform.anpheros.com/v1/patients -H "Authorization: Bearer $KEY"
Writing safely
POST requests accept an Idempotency-Key: a retried request with the same key returns the original response and creates nothing. Every write gets a Provenance; the author type is sent in the body (author_type) or in headers such as X-Anpheros-Author-Type, X-Anpheros-Source-System, X-Anpheros-Origin-Id and X-Anpheros-On-Behalf-Of.
curl -X POST https://platform.anpheros.com/v1/patients/$PID/observations \
-H "Authorization: Bearer $KEY" -H 'content-type: application/json' -H "Idempotency-Key: $(uuidgen)" \
-d '{"code": "29463-7", "display": "Body weight", "category": "vital-signs",
"value": 71.4, "unit": "kg", "effective_at": "2026-09-28T07:30:00Z", "author_type": "patient"}'
Errors and limits
FHIR endpoints answer with OperationOutcome; the others with {"error": {"type", "message", "field"}}. Every response carries Anpheros-Request-Id. The default limit is 600 requests per minute per key and per IP. Errors · Limits
Events
Signed webhooks for resource.created, resource.updated, resource.deleted, consent.granted, consent.revoked, document.finalized and ping. Webhooks
Choosing between FHIR and REST v1
Use FHIR when you already work with FHIR, need resource types that /v1 does not cover (for example Immunization, Procedure or CarePlan), or exchange data with other FHIR systems. Use REST v1 for application code that wants flat JSON for the common cases. Both read and write the same resources with the same ids, so a project can mix them. Medical data API describes the data operations in detail.