--- title: 'Composition (FHIR R4)' description: 'FHIR R4 Composition resource.' nav: 'API / R4 / Composition' order: 100 version: v1 fhir: r4 source: generated updated: '2026-09-23' --- # Composition (FHIR R4) FHIR R4 Composition resource. > This reference is generated from the canonical Huli Public API OpenAPI specification and the server's FHIR R4 CapabilityStatement — do not edit it directly. ## FHIR R4 Specification Official spec: [Composition — HL7 FHIR R4](https://hl7.org/fhir/R4/composition.html) ## Supported Interactions - **read** — Read a single resource by ID (`GET /fhir/R4/{Resource}/{id}`) - **search-type** — Search resources with query parameters (`GET /fhir/R4/{Resource}?...`) - **create** — Create a new resource (`POST /fhir/R4/{Resource}`) - **update** — Update an existing resource (`PUT /fhir/R4/{Resource}/{id}`) ## Scopes Scopes are shared across FHIR releases — the same `system/Composition.*` scope grants Composition access on both `/fhir/R4` and `/fhir/R5`. - — see [scope reference](/v1/scopes#system-composition-rs) - — see [scope reference](/v1/scopes#system-composition-cru) ## Search Parameters | Parameter | Type | Notes | |-----------|------|-------| | `_id` | token | Exact match. For identifiers use `system|value` format. | | `patient` | reference | Resource reference — supply the UUID of the referenced resource. | | `type` | token | Exact match. For identifiers use `system|value` format. | | `date` | date | Supports FHIR date prefixes: `eq`, `ne`, `gt`, `ge`, `lt`, `le`. Format: `[prefix]YYYY-MM-DD`. | | `_count` | number | Integer. For `_count`: default 20, max 100. | | `_cursor` | string | Case-insensitive partial match. | ## Endpoints ### Read Composition Retrieve a single Composition (the clinical-note projection of an encounter) by its ID. The response carries a weak ETag derived from the encounter's last-modified time. **Required scope:** #### Code Samples :::CodeGroup ```bash {label="cURL"} TOKEN=$(curl -s -X POST https://api.huli.ai/auth/token \ -d "grant_type=client_credentials" \ -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \ -d "client_assertion=${CLIENT_ASSERTION}" \ -d "scope=system/Composition.rs" \ | jq -r .access_token) curl -X GET https://api.huli.ai/fhir/R4/Composition/${RESOURCE_ID} \ -H "Authorization: Bearer ${TOKEN}" ``` ```typescript {label="TypeScript"} const token = process.env.HULI_ACCESS_TOKEN ?? ""; const response = await fetch( `https://api.huli.ai/fhir/R4/Composition/${id}`, { method: "GET", headers: { "Authorization": `Bearer ${token}`, }, } ); if (!response.ok) throw new Error(`HTTP ${String(response.status)}`); const data: unknown = await response.json(); ``` ```python {label="Python"} import os import requests token = os.environ["HULI_ACCESS_TOKEN"] headers = {"Authorization": f"Bearer {token}"} resp = requests.get( f"https://api.huli.ai/fhir/R4/Composition/{resource_id}", headers=headers, ) resp.raise_for_status() print(resp.json()) ``` ```java {label="Java"} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class getCompositionExample { public static void main(String[] args) throws Exception { String token = System.getenv("HULI_ACCESS_TOKEN"); String resourceId = "RESOURCE_ID"; HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api.huli.ai/fhir/R4/Composition/" + resourceId)) .header("Authorization", "Bearer " + token) .header("Accept", "application/fhir+json") .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println("status: " + response.statusCode()); System.out.println(response.body()); } } ``` ```go {label="Go"} import ( "fmt" "net/http" "os" ) func getCompositionExample() { token := os.Getenv("HULI_ACCESS_TOKEN") req, _ := http.NewRequest("GET", "https://api.huli.ai/fhir/R4/Composition/"+resourceID+"", nil) req.Header.Set("Authorization", "Bearer "+token) resp, err := http.DefaultClient.Do(req) if err != nil { fmt.Println("error:", err) return } defer resp.Body.Close() fmt.Println("status:", resp.Status) } ``` ::: #### Errors | Code | Status | Description | |------|--------|-------------| | [HPB-00106](/v1/errors#hpb-00106) | 401 | Authentication failed | | [HPB-00104](/v1/errors#hpb-00104) | 403 | Insufficient scope | | [HPB-00102](/v1/errors#hpb-00102) | 404 | Resource not found | | [HPB-00105](/v1/errors#hpb-00105) | 429 | Rate limit exceeded | --- ### Update Composition Update a Composition's clinical narrative and document status. Supports optimistic concurrency via `If-Match` against the weak ETag returned on read (a stale ETag yields 409 HPB-00103). Set `status: entered-in-error` to void the note. The underlying visit envelope (class, period) is preserved. **Required scope:** #### Code Samples :::CodeGroup ```bash {label="cURL"} TOKEN=$(curl -s -X POST https://api.huli.ai/auth/token \ -d "grant_type=client_credentials" \ -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \ -d "client_assertion=${CLIENT_ASSERTION}" \ -d "scope=system/Composition.u" \ | jq -r .access_token) curl -X PUT https://api.huli.ai/fhir/R4/Composition/${RESOURCE_ID} \ -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/fhir+json" \ -d @resource.json ``` ```typescript {label="TypeScript"} const token = process.env.HULI_ACCESS_TOKEN ?? ""; const response = await fetch( `https://api.huli.ai/fhir/R4/Composition/${id}`, { method: "PUT", headers: { "Authorization": `Bearer ${token}`, "Content-Type": "application/fhir+json", }, body: JSON.stringify(payload), } ); if (!response.ok) throw new Error(`HTTP ${String(response.status)}`); const data: unknown = await response.json(); ``` ```python {label="Python"} import os import requests token = os.environ["HULI_ACCESS_TOKEN"] headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/fhir+json"} resp = requests.put( f"https://api.huli.ai/fhir/R4/Composition/{resource_id}", headers=headers, json=payload, ) resp.raise_for_status() print(resp.json()) ``` ```java {label="Java"} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class updateCompositionExample { public static void main(String[] args) throws Exception { String token = System.getenv("HULI_ACCESS_TOKEN"); String resourceId = "RESOURCE_ID"; String payload = "{}"; // your serialized FHIR resource HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api.huli.ai/fhir/R4/Composition/" + resourceId)) .header("Authorization", "Bearer " + token) .header("Accept", "application/fhir+json") .header("Content-Type", "application/fhir+json") .method("PUT", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println("status: " + response.statusCode()); System.out.println(response.body()); } } ``` ```go {label="Go"} import ( "fmt" "net/http" "os" ) func updateCompositionExample() { token := os.Getenv("HULI_ACCESS_TOKEN") req, _ := http.NewRequest("PUT", "https://api.huli.ai/fhir/R4/Composition/"+resourceID+"", body) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("Content-Type", "application/fhir+json") // set req.Body to your serialized resource resp, err := http.DefaultClient.Do(req) if err != nil { fmt.Println("error:", err) return } defer resp.Body.Close() fmt.Println("status:", resp.Status) } ``` ::: #### Errors | Code | Status | Description | |------|--------|-------------| | [HPB-00101](/v1/errors#hpb-00101) | 400 | Validation error | | [HPB-00106](/v1/errors#hpb-00106) | 401 | Authentication failed | | [HPB-00104](/v1/errors#hpb-00104) | 403 | Insufficient scope | | [HPB-00102](/v1/errors#hpb-00102) | 404 | Resource not found | | [HPB-00103](/v1/errors#hpb-00103) | 409 | Version conflict | | [HPB-00101](/v1/errors#hpb-00101) | 422 | Unprocessable entity | | [HPB-00105](/v1/errors#hpb-00105) | 429 | Rate limit exceeded | --- ### Search Compositions Search Compositions by `patient`, `date`, and `type`. Paginated with `_count` and `_cursor`. **Required scope:** #### Query Parameters #### Code Samples :::CodeGroup ```bash {label="cURL"} TOKEN=$(curl -s -X POST https://api.huli.ai/auth/token \ -d "grant_type=client_credentials" \ -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \ -d "client_assertion=${CLIENT_ASSERTION}" \ -d "scope=system/Composition.rs" \ | jq -r .access_token) curl -X GET https://api.huli.ai/fhir/R4/Composition \ -H "Authorization: Bearer ${TOKEN}" ``` ```typescript {label="TypeScript"} const token = process.env.HULI_ACCESS_TOKEN ?? ""; const response = await fetch( `https://api.huli.ai/fhir/R4/Composition`, { method: "GET", headers: { "Authorization": `Bearer ${token}`, }, } ); if (!response.ok) throw new Error(`HTTP ${String(response.status)}`); const data: unknown = await response.json(); ``` ```python {label="Python"} import os import requests token = os.environ["HULI_ACCESS_TOKEN"] headers = {"Authorization": f"Bearer {token}"} resp = requests.get( f"https://api.huli.ai/fhir/R4/Composition", headers=headers, ) resp.raise_for_status() print(resp.json()) ``` ```java {label="Java"} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class searchCompositionsExample { public static void main(String[] args) throws Exception { String token = System.getenv("HULI_ACCESS_TOKEN"); HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api.huli.ai/fhir/R4/Composition")) .header("Authorization", "Bearer " + token) .header("Accept", "application/fhir+json") .method("GET", HttpRequest.BodyPublishers.noBody()) .build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println("status: " + response.statusCode()); System.out.println(response.body()); } } ``` ```go {label="Go"} import ( "fmt" "net/http" "os" ) func searchCompositionsExample() { token := os.Getenv("HULI_ACCESS_TOKEN") req, _ := http.NewRequest("GET", "https://api.huli.ai/fhir/R4/Composition", nil) req.Header.Set("Authorization", "Bearer "+token) resp, err := http.DefaultClient.Do(req) if err != nil { fmt.Println("error:", err) return } defer resp.Body.Close() fmt.Println("status:", resp.Status) } ``` ::: #### Errors | Code | Status | Description | |------|--------|-------------| | [HPB-00101](/v1/errors#hpb-00101) | 400 | Validation error | | [HPB-00106](/v1/errors#hpb-00106) | 401 | Authentication failed | | [HPB-00104](/v1/errors#hpb-00104) | 403 | Insufficient scope | | [HPB-00105](/v1/errors#hpb-00105) | 429 | Rate limit exceeded | --- ### Create Composition Create a Composition. Because a Composition is a projection of an encounter, this creates a new encounter carrying the clinical narrative (subject + author are required). The server assigns the resource ID. **Required scope:** #### Code Samples :::CodeGroup ```bash {label="cURL"} TOKEN=$(curl -s -X POST https://api.huli.ai/auth/token \ -d "grant_type=client_credentials" \ -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \ -d "client_assertion=${CLIENT_ASSERTION}" \ -d "scope=system/Composition.c" \ | jq -r .access_token) curl -X POST https://api.huli.ai/fhir/R4/Composition \ -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/fhir+json" \ -d @composition.json ``` ```typescript {label="TypeScript"} const token = process.env.HULI_ACCESS_TOKEN ?? ""; const response = await fetch( `https://api.huli.ai/fhir/R4/Composition`, { method: "POST", headers: { "Authorization": `Bearer ${token}`, "Content-Type": "application/fhir+json", }, body: JSON.stringify(payload), } ); if (!response.ok) throw new Error(`HTTP ${String(response.status)}`); const data: unknown = await response.json(); ``` ```python {label="Python"} import os import requests token = os.environ["HULI_ACCESS_TOKEN"] headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/fhir+json"} resp = requests.post( f"https://api.huli.ai/fhir/R4/Composition", headers=headers, json=payload, ) resp.raise_for_status() print(resp.json()) ``` ```java {label="Java"} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class createCompositionExample { public static void main(String[] args) throws Exception { String token = System.getenv("HULI_ACCESS_TOKEN"); String payload = "{}"; // your serialized FHIR resource HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api.huli.ai/fhir/R4/Composition")) .header("Authorization", "Bearer " + token) .header("Accept", "application/fhir+json") .header("Content-Type", "application/fhir+json") .method("POST", HttpRequest.BodyPublishers.ofString(payload)) .build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println("status: " + response.statusCode()); System.out.println(response.body()); } } ``` ```go {label="Go"} import ( "fmt" "net/http" "os" ) func createCompositionExample() { token := os.Getenv("HULI_ACCESS_TOKEN") req, _ := http.NewRequest("POST", "https://api.huli.ai/fhir/R4/Composition", body) req.Header.Set("Authorization", "Bearer "+token) req.Header.Set("Content-Type", "application/fhir+json") // set req.Body to your serialized resource resp, err := http.DefaultClient.Do(req) if err != nil { fmt.Println("error:", err) return } defer resp.Body.Close() fmt.Println("status:", resp.Status) } ``` ::: #### Errors | Code | Status | Description | |------|--------|-------------| | [HPB-00101](/v1/errors#hpb-00101) | 400 | Validation error | | [HPB-00106](/v1/errors#hpb-00106) | 401 | Authentication failed | | [HPB-00104](/v1/errors#hpb-00104) | 403 | Insufficient scope | | [HPB-00101](/v1/errors#hpb-00101) | 422 | Unprocessable entity | | [HPB-00105](/v1/errors#hpb-00105) | 429 | Rate limit exceeded | ---