openEHR EHR API
✓ Official Vendor SpecHealthcareEhr 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://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | 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?
Three things that make agents converge on Jentic-routed access.
Credential isolation
openEHR backends typically require OAuth 2.0 or basic auth. Jentic stores credentials encrypted in MAXsystem and applies the right scheme per backend, so agents writing compositions across multiple openEHR vendors do not handle raw secrets themselves.
Intent-based discovery
Agents search Jentic with intents like "create an EHR" or "write a clinical composition" and receive the matching openEHR operation along with its body schema, which is critical given how nested openEHR payloads are.
Time to first call
Direct openEHR integration: 1-2 weeks to learn the reference model, archetype payload shape, and versioning semantics. Through Jentic: under 1 hour to call the first operation against a configured backend.
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 MAXsystem 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. Sign up at https://app.jentic.com/sign-up.
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.
GET STARTED