Skip to main content
The clinik.documents namespace manages FHIR Composition resources — structured clinical documents organized into titled sections. Use compositions for multi-section documents like discharge summaries, referral letters, care plans, and operative reports. For single-body narrative notes, use clinik.notes instead.

​
create

Create a new Composition. The status, type, patientId, practitionerId, title, and sections fields are required. 
const { data, meta } = await clinik.documents.create(request: DocumentCreateRequest): Promise<ApiResponse<Composition>>
​
status
string
required
Document status. Accepted values: preliminary, final, amended.
​
type
string
required
Document type identifier, for example discharge-summary, referral-letter, care-plan.
​
patientId
string
required
ID of the patient the document is about.
​
practitionerId
string
required
ID of the practitioner who authored the document.
​
title
string
required
Document title.
​
sections
Array
required
Ordered array of document sections. Each section requires a title and text, and optionally a code and an array of resourceIds that this section references.
​
encounterId
string
Encounter this document is associated with.
​
date
string
Document date in YYYY-MM-DD format.
​
confidentiality
'N' | 'R' | 'V'
Confidentiality level. N = Normal, R = Restricted, V = Very Restricted.

​
Section structure

Each section in the sections array accepts: 
{
  title: string;          // Section heading
  text: string;           // Section content (plain text or markdown)
  code?: string;          // Section code for machine processing
  resourceIds?: string[]; // IDs of referenced FHIR resources
}

​
Example

const { data: doc } = await clinik.documents.create({
  status: 'final',
  type: 'discharge-summary',
  patientId: 'pt_abc123',
  practitionerId: 'prac_def456',
  title: 'Discharge Summary - Jane Doe',
  date: '2025-01-20',
  confidentiality: 'N',
  sections: [
    {
      title: 'Chief Complaint',
      code: 'chief-complaint',
      text: 'Patient admitted for chest pain evaluation.',
    },
    {
      title: 'Hospital Course',
      code: 'hospital-course',
      text: 'Cardiac workup negative. Discharged in stable condition.',
    },
    {
      title: 'Discharge Medications',
      code: 'medications',
      text: 'Continue aspirin 81mg daily, atorvastatin 20mg daily.',
      resourceIds: ['rx_med1', 'rx_med2'],
    },
    {
      title: 'Follow-up',
      code: 'follow-up',
      text: 'Cardiology follow-up in 2 weeks.',
    },
  ],
});

console.log('Document ID:', doc.id);

​
read

Fetch a single composition by ID. 
const { data, meta } = await clinik.documents.read(id: string): Promise<ApiResponse<Composition>>

​
update

Partially update a document. Only the fields you include are changed. To amend a final document, update status to amended alongside your content changes. 
const { data, meta } = await clinik.documents.update(id: string, request: DocumentUpdateRequest): Promise<ApiResponse<Composition>>

​
Example: amend a final document

await clinik.documents.update('doc_abc123', {
  status: 'amended',
  sections: [
    {
      title: 'Follow-up',
      code: 'follow-up',
      text: 'Cardiology follow-up in 1 week (expedited due to new findings).',
    },
  ],
});

​
delete

Permanently delete a composition. 
const { data, meta } = await clinik.documents.delete(id: string): Promise<ApiResponse<void>>
Search compositions with filters on patient, author, type, status, and date. 
const { data, meta } = await clinik.documents.search(params?: ResourceSearchParams): Promise<ApiResponse<PaginatedResponse<Composition>>>
​
patientId
string
Filter by patient.
​
practitionerId
string
Filter by authoring practitioner.
​
type
string
Filter by document type.
​
status
string
Filter by document status.
​
date
string
Filter by document date.
​
count
number
Results per page.
​
cursor
string
Pagination cursor from a previous response.

​
Example

const { data } = await clinik.documents.search({
  patientId: 'pt_abc123',
  type: 'discharge-summary',
  status: 'final',
});

console.log('Discharge summaries:', data.data.length);