canonical: https://jentic.com/apis/openehr.org/openehr

# openEHR EHR API

The openEHR EHR REST API is the standardised specification published by the openEHR Foundation for interacting with electronic health records that follow the openEHR reference model. It defines 33 endpoints covering EHR creation, EHR_STATUS, COMPOSITION versioning, DIRECTORY folder structure, CONTRIBUTION audit objects, and ITEM_TAG annotations, each with versioned history. Vendor implementations such as Better, EhrBase, and Code24 expose this surface so that clinical applications written against the openEHR standard can run on any conformant backend without rewrite.

## For AI agents

Create EHRs, write versioned compositions, manage status and directory entries, and traverse audit history on any openEHR-conformant clinical record store.

## Scope

Does not handle Archetype Query Language (AQL) queries, template upload, or system administration - use for EHR, composition, directory, and audit operations under the EHR REST spec only.

## Capabilities

- Create and retrieve electronic health records via /ehr and `/ehr/{ehr_id}`
- Write and version clinical compositions with full revision history through `/ehr/{ehr_id}/composition` and `/ehr/{ehr_id}/versioned_composition`
- Manage EHR_STATUS - patient identifier, queryable flag, modifiability - with `/ehr/{ehr_id}/ehr_status` and its versioned variant
- Organise compositions into folders using the DIRECTORY resource at `/ehr/{ehr_id}/directory`
- Record audit context for changes through CONTRIBUTION objects at `/ehr/{ehr_id}/contribution`
- Tag clinical items for cross-cutting concerns via ITEM_TAG endpoints

## Use cases

### Standards-Based Clinical App Backend

Develop a clinical application against the openEHR REST API so it runs unchanged on any conformant backend (EhrBase, Better, Code24, DIPS Arena, others). The API covers EHR lifecycle, composition CRUD with versioning, directory folders, and audit objects so the application can be vendor-independent. Used by national EHR programmes and hospital groups that want to avoid lock-in to a single vendor's proprietary API.

Example prompt: POST to /ehr with a body specifying ehr_status with subject_id "PAT-001" and namespace "hospital-ns" and capture the returned ehr_id.

### Versioned Composition Authoring

Write structured compositions (encounter notes, lab results, care-plan entries) into a patient's EHR with full audit history. The /composition endpoint accepts an openEHR composition payload validated against an archetype, and subsequent updates create new versions accessible via /versioned_composition. This lets review and corrections workflows reconstruct any historic state of the chart.

Example prompt: POST a vital-signs composition to `/ehr/{ehr_id}/composition` and then GET `/ehr/{ehr_id}/versioned_composition/{uid}/revision_history` to confirm version 1 exists.

### EHR Lookup by External ID

Locate an EHR by external subject identifier using the query parameters on /ehr - supplying subject_id and subject_namespace returns the canonical ehr_id. Useful for integration layers that hold their own master patient index and need to resolve to the openEHR identifier before reading or writing clinical data.

Example prompt: GET /ehr?subject_id=PAT-001&subject_namespace=hospital-ns and return the ehr_id from the response.

### Agent-Driven Clinical Workflow Assistance

An AI agent helping a clinician summarise a patient's record can use Jentic to discover the openEHR composition retrieval operation, then read the latest version of each composition for a patient and produce a timeline. Because the API is vendor-neutral, the same agent integration runs against multiple hospital backends without re-coding.

Example prompt: Through Jentic, find the operation for "list compositions in an EHR" and call it for the resolved ehr_id, returning composition uids and timestamps.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/ehr` | Create a new EHR |
| GET | `/ehr/{ehr_id}` | Retrieve an EHR by ID |
| GET | `/ehr/{ehr_id}/ehr_status` | Get the current EHR_STATUS |
| POST | `/ehr/{ehr_id}/composition` | Submit a new composition |
| GET | `/ehr/{ehr_id}/composition/{uid_based_id}` | Retrieve a composition |
| GET | `/ehr/{ehr_id}/versioned_ehr_status/revision_history` | List the revision history of EHR_STATUS |
| GET | `/ehr/{ehr_id}/versioned_ehr_status/version/{version_uid}` | Retrieve a specific EHR_STATUS version |

## Key resources

- **EHR** — Create and retrieve electronic health records keyed by ehr_id or external subject identifier
- **EHR_STATUS** — Patient identifier, queryable flag, and modifiability state, with full versioned history
- **COMPOSITION** — Versioned clinical compositions following openEHR archetypes
- **DIRECTORY** — Folder hierarchy organising compositions within an EHR
- **CONTRIBUTION** — Audit objects describing why and by whom changes were made
- **ITEM_TAG** — Cross-cutting tags applied to clinical items

## Why Jentic

- **Setup:** Wiring the openEHR EHR API by hand means resolving the per-backend base URL, applying whatever auth scheme each vendor requires, and constructing deeply nested composition payloads yourself. Through Jentic you install once, import the openEHR EHR API from the API Directory, store any backend credentials once, and your agent calls it.
- **Permission scoping:** The API puts the EHR id in the URL path (`/ehr/{ehr_id}`, `/ehr/{ehr_id}/composition`), so a rule can pin your agent to one EHR: it can read that EHR's status and write compositions against it. You choose the operations it may call, and nothing beyond that set runs.
- **Credential handling:** Any credentials your openEHR backend requires are stored once, encrypted, by your own Jentic One instance and applied per backend at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create an EHR' or 'write a clinical composition', and Jentic returns the matching openEHR operation with its nested body schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Epic FHIR API** — FHIR-based EHR API rather than openEHR's reference-model API, used in many US hospital systems
- **athenahealth API** — Vendor-specific cloud EHR API rather than a vendor-neutral specification
- **DrChrono API** — Vendor-specific EHR API for ambulatory and specialty practices
- **ClinicalTrials.gov API** — Public registry of clinical trials that complements EHR-side patient data

## FAQ

### What authentication does the openEHR EHR API use?

The openEHR specification itself does not mandate an auth scheme - concrete implementations (EhrBase, Better, Code24) typically front the API with OAuth 2.0 or basic auth. Jentic stores the implementation-specific credential encrypted in your Jentic One instance and applies the right scheme at execution, so the same agent code works across vendor backends.

### Can I version clinical compositions through the openEHR API?

Yes. Every composition write via `/ehr/{ehr_id}/composition` produces a new version object accessible at `/ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/revision_history.` Updates create successor versions; the API never destructively overwrites a prior version.

### What are the rate limits for the openEHR EHR API?

The openEHR specification does not define rate limits - these are set by the implementation hosting the API. Production deployments typically rate-limit per client identity, so design for retry-with-backoff and prefer batched composition writes over per-event requests.

### How do I create an EHR with the openEHR API through Jentic?

Use the Jentic search query "create a new electronic health record". Jentic returns the POST /ehr operation with its input schema; the agent supplies the ehr_status payload (subject_id, namespace, queryable flag) and Jentic executes the call against the configured backend. Run it through Jentic One, the self-hosted execution layer.

### Is the openEHR EHR API a single hosted service?

No. openEHR.org publishes the specification - actual data is held by the hospital or vendor backend implementing the spec. Jentic targets a configured base URL pointing at that backend, which is why base_url is templated.

### Can the openEHR API run an Archetype Query Language (AQL) query?

AQL is part of the broader openEHR REST surface but lives in a separate Query API spec (not these 33 EHR endpoints). For AQL access, use the openEHR query-API definition rather than this EHR-API definition.

### Can I limit what my agent is allowed to do with the openEHR EHR API?

Yes. Because you run Jentic One self-hosted, your own rules decide which openEHR operations and backend credentials the agent may use. Since the API carries the record identifier in the path (`/ehr/{ehr_id}`, `/ehr/{ehr_id}/composition`, `/ehr/{ehr_id}/ehr_status`), you can pin the agent to a single EHR and grant only the operations it needs, such as reading EHR_STATUS while allowing composition writes. Nothing outside the operation set you approve ever runs.