openEHR

openEHR EHR API

The core openEHR record API — create and manage EHRs, compositions, directories, contributions and versioned objects. openEHR SPECIFICATION, not a callable service — 33 operation(s) across 23 path(s), served from the templated host `https://{baseUrl}/v1`.

Documentation GitHub OpenAPI

Operations 33

POST /ehr Create EHR #

GET /ehr Get EHR by subject id #

PUT /ehr/{ehr_id} Create EHR with id #

GET /ehr/{ehr_id} Get EHR by id #

GET /ehr/{ehr_id}/ehr_status/{version_uid} Get EHR_STATUS by version id #

GET /ehr/{ehr_id}/ehr_status Get EHR_STATUS at time #

PUT /ehr/{ehr_id}/ehr_status Update EHR_STATUS #

GET /ehr/{ehr_id}/versioned_ehr_status Get versioned EHR_STATUS #

GET /ehr/{ehr_id}/versioned_ehr_status/revision_history Get versioned EHR_STATUS revision history #

GET /ehr/{ehr_id}/versioned_ehr_status/version Get versioned EHR_STATUS version at time #

GET /ehr/{ehr_id}/versioned_ehr_status/version/{version_uid} Get versioned EHR_STATUS version by id #

POST /ehr/{ehr_id}/composition Create COMPOSITION #

GET /ehr/{ehr_id}/composition/{uid_based_id} Get COMPOSITION #

PUT /ehr/{ehr_id}/composition/{uid_based_id} Update COMPOSITION #

DELETE /ehr/{ehr_id}/composition/{uid_based_id} Delete COMPOSITION #

GET /ehr/{ehr_id}/versioned_composition/{versioned_object_uid} Get versioned COMPOSITION #

GET /ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/revision_history Get versioned COMPOSITION revision history #

GET /ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/version Get versioned COMPOSITION version at time #

GET /ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/version/{version_uid} Get versioned COMPOSITION version by id #

POST /ehr/{ehr_id}/directory Create directory #

PUT /ehr/{ehr_id}/directory Update directory #

DELETE /ehr/{ehr_id}/directory Delete directory #

GET /ehr/{ehr_id}/directory Get folder in directory version at time #

GET /ehr/{ehr_id}/directory/{version_uid} Get folder in directory version #

POST /ehr/{ehr_id}/contribution Create CONTRIBUTION #

GET /ehr/{ehr_id}/contribution/{contribution_uid} Get CONTRIBUTION by id #

GET /ehr/{ehr_id}/tags Get EHR tags #

GET /ehr/{ehr_id}/composition/{uid_based_id}/tags Get COMPOSITION tags #

PUT /ehr/{ehr_id}/composition/{uid_based_id}/tags Update COMPOSITION tags #

DELETE /ehr/{ehr_id}/composition/{uid_based_id}/tags/{key} Delete COMPOSITION tags #

GET /ehr/{ehr_id}/ehr_status/{uid_based_id}/tags Get EHR_STATUS tags #

PUT /ehr/{ehr_id}/ehr_status/{uid_based_id}/tags Update EHR_STATUS tags #

DELETE /ehr/{ehr_id}/ehr_status/{uid_based_id}/tags/{key} Delete EHR_STATUS tags #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/ehr"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no email required.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.0.3
info:
  title: EHR API
  version: latest
  x-status: STABLE
  x-spec: ehr
  contact:
    name: Specifications Editorial Committee openEHR
    url: https://specifications.openehr.org/
    email: info@openehr.org
  license:
    name: Creative Commons Attribution-NoDerivs 3.0 Unported
    url: https://creativecommons.org/licenses/by-nd/3.0/
  description: |
    ## Description

    ### Purpose

    This specification describes service endpoints, resources and operations as well as details of requests and responses that interact with the openEHR EHR API in a RESTful manner.

    ### Related Documents

    Prerequisite documents for reading this document include:

    - The [EHR Information Model](https://specifications.openehr.org/releases/RM/latest/ehr.html#_the_ehr_information_model)

    Related documents include:

    - The [openEHR Architecture Overview](https://specifications.openehr.org/releases/BASE/latest/architecture_overview.html)
    - The [openEHR Global Class Index](https://specifications.openehr.org/classes)
    - The [XML-Schemas (XSD)](https://specifications.openehr.org/releases/ITS-XML/latest)
    - The [JSON-Schemas](https://specifications.openehr.org/releases/ITS-JSON/latest) and [Simplified Formats](simplified_formats.html)

    ### Status

    This specification is in the `STABLE` state, and can be downloaded as [OpenAPI specification](https://spec.openapis.org/oas/v3.0.3) file (in YAML format) [for validation](computable/OAS/ehr-validation.openapi.yaml), or [for code generators](computable/OAS/ehr-codegen.openapi.yaml).
    Users are encouraged to comment on and/or advise on these paragraphs as well as the main content.

    The development version of this document can be found at <https://specifications.openehr.org/releases/ITS-REST/development/ehr.html>.
servers:
  - url: https://{baseUrl}/v1
    description: An example openEHR server URL.
    variables:
      baseUrl:
        default: openEHRSys.example.com
        description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
security: []
tags:
  - name: EHR
    description: |
      Management of [EHRs](https://specifications.openehr.org/releases/RM/latest/ehr.html#_ehr_class).

      Operations in this group cover creation of new EHRs, retrieval by identifier or subject, and access to associated versioned resources.

      The `EHR` resource is the top-level resource in the EHR REST API; it contains all other resources in this group. 
      Identification of the `EHR` resource is usually by the `ehr_id`, and is present in the path segment.
  - name: EHR_STATUS
    description: |
      Management of [EHR_STATUS](https://specifications.openehr.org/releases/RM/latest/ehr.html#_ehr_status_class) and [VERSIONED_EHR_STATUS](https://specifications.openehr.org/releases/RM/latest/ehr.html#_versioned_ehr_status_class) resources.

      Operations include retrieval by time or version, update, and inspection of revision history for the versioned status of an EHR.
  - name: COMPOSITION
    description: |
      Management of [COMPOSITION](https://specifications.openehr.org/releases/RM/latest/ehr.html#_composition_class) and [VERSIONED_COMPOSITION](https://specifications.openehr.org/releases/RM/latest/ehr.html#_versioned_composition_class) resources.

      Operations include create, retrieve, update, delete of compositions, and access to their version containers, specific versions and revision history.
  - name: DIRECTORY
    description: |
      Management of the [directory](https://specifications.openehr.org/releases/RM/latest/ehr.html#_directory) [FOLDER](https://specifications.openehr.org/releases/RM/latest/common.html#_folder_class) resource.

      Operations include create, update, delete and time/version-based retrieval of the EHR’s directory structure.
  - name: CONTRIBUTION
    description: |
      Management of [CONTRIBUTION](https://specifications.openehr.org/releases/RM/latest/common.html#_contribution_class) resource.

      Operations cover creation of contributions and retrieval by identifier, enabling audit of grouped version commits within an EHR.
  - name: ITEM_TAG
    description: |
      Management of [ITEM_TAG](https://specifications.openehr.org/releases/RM/development/common.html#_item_tag_class) resources.
  - name: CONTENT_ITEM_schema
    x-displayName: CONTENT_ITEM
    description: |
      The abstract `CONTENT_ITEM` class:
      <SchemaDefinition schemaRef="#/components/schemas/UContentItem" />
  - name: ITEM_schema
    x-displayName: ITEM
    description: |
      The abstract `ITEM` class:
      <SchemaDefinition schemaRef="#/components/schemas/UItem" />
  - name: ITEM_STRUCTURE_schema
    x-displayName: ITEM_STRUCTURE
    description: |
      The abstract `ITEM_STRUCTURE` class:
      <SchemaDefinition schemaRef="#/components/schemas/UItemStructure" />
paths:
  /ehr:
    post:
      operationId: ehr_create
      summary: Create EHR
      description: |
        Create a new `EHR` with an auto-generated identifier.

        An EHR_STATUS resource needs to be always created and committed in the new EHR.
        This resource MAY be also supplied by the client as the request body. 
        If not supplied, a default EHR_STATUS will be used by the service with following attributes:
          - `is_queryable`: true
          - `is_modifiable`: true
          - `subject`: a PARTY_SELF object

        All other required EHR attributes and resources will be automatically created as needed by the [EHR creation semantics](https://specifications.openehr.org/releases/RM/latest/ehr.html#_ehr_creation_semantics).
      tags:
        - EHR
      parameters:
        - $ref: '#/components/parameters/Prefer'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_LOCATABLE'
      requestBody:
        description: |
          An EHR_STATUS resource MAY be also supplied by the client as the request body.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EhrStatus'
        required: false
      responses:
        '201':
          $ref: '#/components/responses/201_EHR'
        '400':
          $ref: '#/components/responses/400'
        '409':
          $ref: '#/components/responses/409_EHR'
    get:
      operationId: ehr_get_by_subject
      summary: Get EHR by subject id
      description: |
        Retrieve the EHR with the specified `subject_id` and `subject_namespace`.

        These subject parameters will be matched against EHR's EHR_STATUS.subject.external_ref.id.value and 
        EHR_STATUS.subject.external_ref.namespace values.
      tags:
        - EHR
      parameters:
        - $ref: '#/components/parameters/subject_id'
        - $ref: '#/components/parameters/subject_namespace'
        - $ref: '#/components/parameters/Accept_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_EHR'
        '404':
          $ref: '#/components/responses/404_EHR_subject'
  /ehr/{ehr_id}:
    put:
      operationId: ehr_create_with_id
      summary: Create EHR with id
      description: |
        Create a new EHR with the specified `ehr_id` identifier.

        The value of the `ehr_id` unique identifier MUST be valid [HIER_OBJECT_ID](https://specifications.openehr.org/releases/BASE/latest/base_types.html#_hier_object_id_class) value. 
        It is strongly RECOMMENDED that an UUID always be used for this.

        An EHR_STATUS resource needs to be always created and committed in the new EHR.
        This resource MAY be also supplied by the client as the request body. 
        If not supplied, a default EHR_STATUS will be used by the service with following attributes:
          - `is_queryable`: true
          - `is_modifiable`: true
          - `subject`: a PARTY_SELF object

        All other required EHR attributes and resources will be automatically created as needed by the [EHR creation semantics](https://specifications.openehr.org/releases/RM/latest/ehr.html#_ehr_creation_semantics).
      tags:
        - EHR
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/Prefer'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_LOCATABLE'
      requestBody:
        description: |
          An EHR_STATUS resource MAY be also supplied by the client as the request body.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EhrStatus'
        required: false
      responses:
        '201':
          $ref: '#/components/responses/201_EHR'
        '400':
          $ref: '#/components/responses/400'
        '409':
          $ref: '#/components/responses/409_EHR_with_id'
    get:
      operationId: ehr_get_by_id
      summary: Get EHR by id
      description: |
        Retrieve the EHR with the specified `ehr_id`.
      tags:
        - EHR
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/Accept_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_EHR'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id'
  /ehr/{ehr_id}/ehr_status/{version_uid}:
    get:
      operationId: ehr_status_get_by_version_id
      summary: Get EHR_STATUS by version id
      description: |
        Retrieves a particular version of the EHR_STATUS identified by `version_uid` and associated with the EHR identified by `ehr_id`.

        When there are ITEM_TAGs associated with the retrieved EHR_STATUS, they will be returned as `openehr-item-tag` and `openehr-version-item-tag` response headers, respectively - see [item tags headers](overview.html#tag/Requests_and_responses/HTTP-headers/openehr-item-tag-and-openehr-version-item-tag) for more details.
      tags:
        - EHR_STATUS
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/version_uid'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
      responses:
        '200':
          $ref: '#/components/responses/200_EHR_STATUS_retrieved'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_version_uid'
  /ehr/{ehr_id}/ehr_status:
    get:
      operationId: ehr_status_get_at_time
      summary: Get EHR_STATUS at time
      description: |
        Retrieves a version of the EHR_STATUS associated with the EHR identified by `ehr_id`.

        If `version_at_time` is supplied, retrieves the version extant _at specified time_, otherwise retrieves the _latest_ EHR_STATUS version.

        When there are ITEM_TAGs associated with the retrieved EHR_STATUS, they will be returned as `openehr-item-tag` and `openehr-version-item-tag` response headers, respectively - see [item tags headers](overview.html#tag/Requests_and_responses/HTTP-headers/openehr-item-tag-and-openehr-version-item-tag) for more details.
      tags:
        - EHR_STATUS
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/version_at_time'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
      responses:
        '200':
          $ref: '#/components/responses/200_EHR_STATUS_retrieved'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_no_version_at_time'
    put:
      operationId: ehr_status_update
      summary: Update EHR_STATUS
      description: |
        Updates EHR_STATUS associated with the EHR identified by `ehr_id`.

        The existing latest `version_uid` of EHR_STATUS resource (i.e. the `preceding_version_uid`) must be specified in the `If-Match` header.

        A list of ITEM_TAGs can be associated with the updated EHR_STATUS, in which case a `openehr-item-tag` or `openehr-version-item-tag` request header can be set as well. 
        The corresponding response header(s) will return ITEM_TAGs as they were set by the server - see [item tags headers](overview.html#tag/Requests_and_responses/HTTP-headers/openehr-item-tag-and-openehr-version-item-tag) for more details.

        The response will contain the updated EHR_STATUS resource when the `Prefer` header has a value of `return=representation`.
      tags:
        - EHR_STATUS
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/If-Match'
        - $ref: '#/components/parameters/Prefer'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
        - $ref: '#/components/parameters/ContentType_LOCATABLE'
        - $ref: '#/components/parameters/openehr-item-tag'
        - $ref: '#/components/parameters/openehr-version-item-tag'
      requestBody:
        description: |
          The new EHR_STATUS.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EhrStatus'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200_EHR_STATUS_updated'
        '204':
          $ref: '#/components/responses/204_version_updated'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id'
        '412':
          $ref: '#/components/responses/412_EHR_STATUS'
  /ehr/{ehr_id}/versioned_ehr_status:
    get:
      operationId: versioned_ehr_status_get
      summary: Get versioned EHR_STATUS
      description: |
        Retrieves a VERSIONED_EHR_STATUS associated with an EHR identified by `ehr_id`.
      tags:
        - EHR_STATUS
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_VERSIONED_EHR_STATUS'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id'
  /ehr/{ehr_id}/versioned_ehr_status/revision_history:
    get:
      operationId: versioned_ehr_status_revision_history
      summary: Get versioned EHR_STATUS revision history
      description: |
        Retrieves revision history of the VERSIONED_EHR_STATUS associated with the EHR identified by `ehr_id`.
      tags:
        - EHR_STATUS
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_REVISION_HISTORY'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id'
  /ehr/{ehr_id}/versioned_ehr_status/version:
    get:
      operationId: versioned_ehr_status_version_get_at_time
      summary: Get versioned EHR_STATUS version at time
      description: |
        Retrieves a VERSION from the VERSIONED_EHR_STATUS associated with the EHR identified by `ehr_id`.

        If `version_at_time` is supplied, retrieves the VERSION extant _at specified time_, otherwise retrieves the _latest_ VERSION.
      tags:
        - EHR_STATUS
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/version_at_time'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_VERSION_of_EHR_STATUS_at_time'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_no_version_at_time'
  /ehr/{ehr_id}/versioned_ehr_status/version/{version_uid}:
    get:
      operationId: versioned_ehr_status_version_get_by_id
      summary: Get versioned EHR_STATUS version by id
      description: |
        Retrieves a VERSION identified by `version_uid` of an EHR_STATUS associated with the EHR identified by `ehr_id`.
      tags:
        - EHR_STATUS
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/version_uid'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_VERSION_of_EHR_STATUS_by_id'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_version_uid'
  /ehr/{ehr_id}/composition:
    post:
      operationId: composition_create
      summary: Create COMPOSITION
      description: |
        Creates the first version of a new COMPOSITION in the EHR identified by `ehr_id`.

        A list of ITEM_TAGs can be associated with the COMPOSITION, in which case a `openehr-item-tag` or `openehr-version-item-tag` request header can be set as well. 
        The corresponding response header(s) will return ITEM_TAGs as they were set by the server - see [item tags headers](overview.html#tag/Requests_and_responses/HTTP-headers/openehr-item-tag-and-openehr-version-item-tag) for more details.
      tags:
        - COMPOSITION
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/Prefer'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
        - $ref: '#/components/parameters/ContentType_LOCATABLE'
        - $ref: '#/components/parameters/openehr-item-tag'
        - $ref: '#/components/parameters/openehr-version-item-tag'
      requestBody:
        description: |
          The COMPOSITION.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Composition'
        required: true
      responses:
        '201':
          $ref: '#/components/responses/201_COMPOSITION'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id'
        '422':
          $ref: '#/components/responses/422'
  /ehr/{ehr_id}/composition/{uid_based_id}:
    get:
      operationId: composition_get
      summary: Get COMPOSITION
      description: |
        Retrieves a version of the COMPOSITION identified by `uid_based_id` and associated with the EHR identified by `ehr_id`.

        The `uid_based_id` can take a form of an OBJECT_VERSION_ID identifier taken from VERSION.uid.value (i.e. a `version_uid`), or a form of a HIER_OBJECT_ID identifier taken from VERSIONED_OBJECT.uid.value (i.e. a `versioned_object_uid`).
        The former is used to retrieve a specific known version of the COMPOSITION (e.g. one identified by `8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1`), whereas the latter (e.g. an identifier like `8849182c-82ad-4088-a07f-48ead4180515`) is be used to retrieve a version from the version container whenever the _version_tree_id_ is unknown or irrelevant (such as when most recent version is requested).

        When the `uid_based_id` has the form of a HIER_OBJECT_ID, if the `version_at_time` is supplied, retrieves the version extant _at specified time_, otherwise retrieves the _latest_ COMPOSITION version.

        See [Resource identification](overview.html#tag/Resources/Resource-identification) for more details about the identifiers usage and meaning.

        When there are ITEM_TAGs associated with the retrieved COMPOSITION, they will be returned as `openehr-item-tag` and `openehr-version-item-tag` response headers, respectively - see [item tags headers](overview.html#tag/Requests_and_responses/HTTP-headers/openehr-item-tag-and-openehr-version-item-tag) for more details.
      tags:
        - COMPOSITION
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/uid_based_id'
        - $ref: '#/components/parameters/version_at_time'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
      responses:
        '200':
          $ref: '#/components/responses/200_COMPOSITION_retrieved'
        '204':
          $ref: '#/components/responses/204_deleted_at_time'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_no_version_at_time'
    put:
      operationId: composition_update
      summary: Update COMPOSITION
      description: |
        Updates COMPOSITION identified by `uid_based_id` and associated with the EHR identified by `ehr_id`.

        The `uid_based_id` can take only a form of an HIER_OBJECT_ID identifier taken from VERSIONED_OBJECT.uid.value (i.e. a `versioned_object_uid`).

        If the request body already contains a COMPOSITION.uid.value, it must match the `uid_based_id` in the URL. 

        The existing latest `version_uid` of COMPOSITION resource (i.e. the `preceding_version_uid`) must be specified in the `If-Match` header.

        A list of ITEM_TAGs can be associated with the updated COMPOSITION, in which case a `openehr-item-tag` or `openehr-version-item-tag` request header can be set as well. 
        The corresponding response header(s) will return ITEM_TAGs as they were set by the server - see [item tags headers](overview.html#tag/Requests_and_responses/HTTP-headers/openehr-item-tag-and-openehr-version-item-tag) for more details.
      tags:
        - COMPOSITION
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/uid_based_id_as_versioned_object_uid'
        - $ref: '#/components/parameters/If-Match'
        - $ref: '#/components/parameters/Prefer'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
        - $ref: '#/components/parameters/ContentType_LOCATABLE'
        - $ref: '#/components/parameters/openehr-item-tag'
        - $ref: '#/components/parameters/openehr-version-item-tag'
      requestBody:
        description: |
          The new COMPOSITION.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Composition'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200_COMPOSITION_updated'
        '204':
          $ref: '#/components/responses/204_version_updated'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_uid_based_id'
        '412':
          $ref: '#/components/responses/412_COMPOSITION'
        '422':
          $ref: '#/components/responses/422'
    delete:
      operationId: composition_delete
      summary: Delete COMPOSITION
      description: |
        Deletes the COMPOSITION identified by `uid_based_id` and associated with the EHR identified by `ehr_id`.

        The `uid_based_id` MUST be in a form of an OBJECT_VERSION_ID identifier taken from the last (most recent) VERSION.uid.value, representing the `preceding_version_uid` to be deleted.
      tags:
        - COMPOSITION
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/uid_based_id_as_version_uid'
      responses:
        '204':
          $ref: '#/components/responses/204_version_deleted'
        '400':
          $ref: '#/components/responses/400_already_deleted'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_uid_based_id'
        '409':
          $ref: '#/components/responses/409_COMPOSITION_with_uid_based_id'
  /ehr/{ehr_id}/versioned_composition/{versioned_object_uid}:
    get:
      operationId: versioned_composition_get
      summary: Get versioned COMPOSITION
      description: |
        Retrieves a VERSIONED_COMPOSITION identified by `versioned_object_uid` and associated with the EHR identified by `ehr_id`.
      tags:
        - COMPOSITION
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/versioned_object_uid_COMPOSITION'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_VERSIONED_COMPOSITION'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_versioned_object_uid'
  /ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/revision_history:
    get:
      operationId: versioned_composition_revision_history
      summary: Get versioned COMPOSITION revision history
      description: |
        Retrieves revision history of the VERSIONED_COMPOSITION identified by `versioned_object_uid` and associated with the EHR identified by `ehr_id`.
      tags:
        - COMPOSITION
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/versioned_object_uid_COMPOSITION'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_REVISION_HISTORY'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_versioned_object_uid'
  /ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/version:
    get:
      operationId: versioned_composition_version_get_at_time
      summary: Get versioned COMPOSITION version at time
      description: |
        Retrieves a VERSION from the VERSIONED_COMPOSITION identified by `versioned_object_uid` and associated with the EHR identified by `ehr_id`.

        If `version_at_time` is supplied, retrieves the VERSION extant _at specified time_, otherwise retrieves the _latest_ VERSION.
      tags:
        - COMPOSITION
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/versioned_object_uid_COMPOSITION'
        - $ref: '#/components/parameters/version_at_time'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_VERSION_of_COMPOSITION_at_time'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_versioned_object_uid_or_no_version_at_time'
  /ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/version/{version_uid}:
    get:
      operationId: versioned_composition_version_get_by_id
      summary: Get versioned COMPOSITION version by id
      description: |
        Retrieves a VERSION identified by `version_uid` of a VERSIONED_COMPOSITION identified by `versioned_object_uid` and associated with the EHR identified by `ehr_id`.
      tags:
        - COMPOSITION
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/versioned_object_uid_COMPOSITION'
        - $ref: '#/components/parameters/version_uid_COMPOSITION'
        - $ref: '#/components/parameters/Accept_canonical'
        - $ref: '#/components/parameters/ContentType_canonical'
      responses:
        '200':
          $ref: '#/components/responses/200_VERSION_of_COMPOSITION_by_id'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_versioned_object_uid_or_version_uid'
  /ehr/{ehr_id}/directory:
    post:
      operationId: directory_create
      summary: Create directory
      description: |
        Creates a new directory FOLDER associated with the EHR identified by `ehr_id`.
      tags:
        - DIRECTORY
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/Prefer'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
        - $ref: '#/components/parameters/ContentType_LOCATABLE'
      requestBody:
        description: |
          The directory.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Folder'
        required: true
      responses:
        '201':
          $ref: '#/components/responses/201_directory'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id'
    put:
      operationId: directory_update
      summary: Update directory
      description: |
        Updates directory FOLDER associated with the EHR identified by `ehr_id`.

        The existing latest `version_uid` of directory FOLDER resource (i.e. the `preceding_version_uid`) must be specified in the `If-Match` header.
      tags:
        - DIRECTORY
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/If-Match'
        - $ref: '#/components/parameters/Prefer'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
        - $ref: '#/components/parameters/ContentType_LOCATABLE'
      requestBody:
        description: |
          The new directory.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Folder'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200_directory_updated'
        '204':
          $ref: '#/components/responses/204_version_updated'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id'
        '412':
          $ref: '#/components/responses/412_directory'
    delete:
      operationId: directory_delete
      summary: Delete directory
      description: |
        Deletes directory FOLDER associated with the EHR identified by `ehr_id`.

        The existing latest `version_uid` of directory FOLDER resource (i.e. the `preceding_version_uid`) must be specified in the `If-Match` header.
      tags:
        - DIRECTORY
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/If-Match'
      responses:
        '204':
          $ref: '#/components/responses/204_deleted'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id'
        '412':
          $ref: '#/components/responses/412_directory'
    get:
      operationId: directory_get_at_time
      summary: Get folder in directory version at time
      description: |
        Retrieves the version of the directory FOLDER associated with the EHR identified by `ehr_id`. 
        If `version_at_time` is supplied, retrieves the version extant _at specified time_, otherwise retrieves the _latest_ directory FOLDER version. 

        If `path` is supplied, retrieves from the directory only the sub-FOLDER that is associated with that path.
      tags:
        - DIRECTORY
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/version_at_time'
        - $ref: '#/components/parameters/path'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
      responses:
        '200':
          $ref: '#/components/responses/200_FOLDER_retrieved'
        '204':
          $ref: '#/components/responses/204_deleted_at_time'
        '404':
          $ref: '#/components/responses/404_directory_unknown_ehr_id_or_no_version_at_time_or_no_path'
  /ehr/{ehr_id}/directory/{version_uid}:
    get:
      operationId: directory_get_by_version_id
      summary: Get folder in directory version
      description: |
        Retrieves a particular version of the directory FOLDER identified by `version_uid` and associated with the EHR identified by `ehr_id`.

        If `path` is supplied, retrieves from the directory only the sub-FOLDER that is associated with that path.
      tags:
        - DIRECTORY
      parameters:
        - $ref: '#/components/parameters/ehr_id'
        - $ref: '#/components/parameters/version_uid'
        - $ref: '#/components/parameters/path'
        - $ref: '#/components/parameters/Accept_LOCATABLE'
      responses:
        '200':
          $ref: '#/components/responses/200_FOLDER_retrieved'
        '404':
          $ref: '#/components/responses/404_directory_unknown_ehr_id_or_no_version_uid_or_no_path'
  /ehr/{ehr_id}/contribution:
    post:
      operationId: contribution_create
      summary: Create CONTRIBUTION
      description: |
        We will use the relaxed CONTRIBUTION with the following optional attributes:
          - `uid`: when provided, it will be accepted in case is not in-use, otherwise error will be returned
          - `audit.time_committed`: server will always set it
          - `audit.system_id`: when provided, it will be validated

        The `audit` and each `versions[i].commit_audit` are `UPDATE_AUDIT` objects: structurally an
        `AUDIT_DETAILS` minus the server-assigned attributes (`time_committed`, and the optional `system_id`).
        Clients SHOULD send `_type: "UPDA

# --- truncated at 32 KB (161 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openehr/refs/heads/main/openapi/openehr-ehr-openapi.yml