---
title: "Create COMPOSITION"
method: POST
path: "/ehr/{ehr_id}/composition"
tags: ["COMPOSITION"]
---

# Create COMPOSITION

`POST /ehr/{ehr_id}/composition`

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.

## Path parameters

- `ehr_id` string, uuid, required

## Headers

- `Prefer` 'return=representation' | 'return=minimal' | 'return=identifier'
- `Accept` 'application/json' | 'application/xml' | 'application/openehr.wt.flat+json' | 'application/openehr.wt.structured+json'
- `Content-Type` 'application/json' | 'application/xml' | 'application/openehr.wt.flat+json' | 'application/openehr.wt.structured+json'
- `openehr-item-tag` UpdateItemTag[]
  - `key` string, required — Tag key (identifier)
  - `value` string — Tag value
  - `target_path` string — An AQL path withing the `target` used to tag a fine-grained element
- `openehr-version-item-tag` UpdateItemTag[]
  - `key` string, required — Tag key (identifier)
  - `value` string — Tag value
  - `target_path` string — An AQL path withing the `target` used to tag a fine-grained element

## Request body

- Composition
  - `_type` string

## Response `201`

`201 Created` is returned when the COMPOSITION is successfully created. 
If `Prefer` header is `return=representation`, the full resource is included in the response body; if is `return=identifier`, only its unique identifier is included. 
If the `Prefer` header is missing or set to `return=minimal`, the body is empty.

- union
  - Composition
    - `_type` string
  - Identifier
    - `uid` string, required — The (version) resource identifier.

## Other responses

- `400` — `400 Bad Request` is returned when the request could not be parsed or is invalid (e.g. malformed request URL syntax, missing required header or parameter, or syntactically invalid header, parameter or content). The response body MAY contain error details.
- `404` — `404 Not Found` is returned when an EHR with `ehr_id` does not exist.
- `422` — `422 Unprocessable Entity` is returned when the content type and syntax is correct, could be converted to a resource, but there are semantic validation errors, such as the underlying template is not known or is not validating the supplied resource.

---

[API](https://skmtc.net/openehr/apis/ehr-api.md) · [All operations](https://skmtc.net/openehr/apis/ehr-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openehr/ehr-api/versions/a0e37a217524/schema)