openEHR EHR API
Official vendor OpenAPI document · agent-readyHealthcareEhr Emrnone33 EndpointsREST
For Agents
Create EHRs, write versioned compositions, manage status and directory entries, and traverse audit history on any openEHR-conformant clinical record store.
Use for: Create a new EHR for a patient given an external subject namespace and ID, Retrieve the current EHR_STATUS for a patient, Submit a new clinical composition into a patient's EHR, List all versions of a composition and traverse its revision history
Not supported: 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.
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.
Install Jentic One Beta
Connect the openEHR EHR API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the openEHR EHR API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fopenehr.org%2Fopenehr" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fopenehr.org%2Fopenehr" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with openEHR EHR API.
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
Patterns agents use openEHR EHR API for, with concrete tasks.
★ 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.
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.
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.
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.
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
33 endpoints — 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.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using openEHR EHR API through Jentic.
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.
GET STARTED