# 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.

Source: https://developers.anpheros.com/guides/healthcare-api

**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.

```bash
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`.

```bash
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](https://developers.anpheros.com/guides/errors) · [Limits](https://developers.anpheros.com/guides/limits)

### Events

Signed webhooks for `resource.created`, `resource.updated`, `resource.deleted`, `consent.granted`, `consent.revoked`, `document.finalized` and `ping`. [Webhooks](https://developers.anpheros.com/guides/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](https://developers.anpheros.com/guides/medical-data-api) describes the data operations in detail.

## Related

- [Healthcare API with patient consent](https://developers.anpheros.com/guides/healthcare-api-patient-consent)
- [SMART on FHIR backend](https://developers.anpheros.com/guides/smart-on-fhir-backend)
- [Medical data API](https://developers.anpheros.com/guides/medical-data-api)
- [FHIR platform](https://developers.anpheros.com/guides/fhir)
- [Healthcare data interoperability](https://developers.anpheros.com/guides/interoperability)
- [Healthcare integrations](https://developers.anpheros.com/guides/healthcare-integrations)
- [API reference (OpenAPI)](https://developers.anpheros.com/docs) · [Authentication and OAuth](https://developers.anpheros.com/guides/authentication)