Skip to main content
Clinical summarization transforms raw EHR data into actionable discharge summaries, progress notes, and referral letters that highlight status changes, decision points, and follow-up needs. It is particularly useful for efficient handoffs, longitudinal care planning, and ensuring clear communication across multidisciplinary teams.

​
Prerequisites

  • A Clinia workspace
  • A Clinia API key ($CLINIA_TOKEN)
  • Your workspace URL ($CLINIA_WORKSPACE)

​
Overview

Generating a clinical summary with the AI Engine follows three steps:
  1. Ingest patient data (FHIR bundle or PDF document)
  2. Poll the ingestion workflow until it completes
  3. Summarize by selecting a summary template and streaming the result

​
Step 1 — Ingest patient data

Submit a FHIR bundle scoped to the patient you want to summarize. The patientId is a stable identifier you control — it links ingested data to future summary requests. 
curl -X POST "https://$CLINIA_WORKSPACE/ai/v1/ingest" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "patientId": "patient-bob-gratton",
    "bundle": {
      "resourceType": "Bundle",
      "entry": [
        {
          "resource": {
            "resourceType": "Patient",
            "id": "bob-gratton",
            "birthDate": "1945-03-15"
          }
        },
        {
          "resource": {
            "resourceType": "Observation",
            "id": "obs-bp",
            "status": "final",
            "code": { "text": "Blood Pressure" },
            "valueString": "142/88 mmHg"
          }
        }
      ]
    }
  }'
The response returns a runId you will use to track the workflow: 
{
  "runId": "run_01JABZX3V4Q2P2M41ME6E3FQ7R",
  "status": "started"
}
Ingesting a new FHIR bundle replaces any previously ingested bundle for that patient. Unstructured documents (PDFs) are additive and accumulate over time.

​
Step 2 — Poll ingestion status

Ingestion is asynchronous. Poll the status endpoint until status is success or failed. 
curl -X GET "https://$CLINIA_WORKSPACE/ai/v1/ingest/{runId}/status" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN"

{
  "runId": "run_01JABZX3V4Q2P2M41ME6E3FQ7R",
  "status": "success"
}
Typical ingestion times: seconds for FHIR bundles, several minutes for PDF documents.

​
Step 3 — Pick a summary template

Summary templates define the structure and content of the generated document. Retrieve the available templates from your workspace: 
curl -X GET "https://$CLINIA_WORKSPACE/ai/v1/summary-templates?page=0&perPage=20" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN"
Note the id of the template you want to use.

​
Step 4 — Create a summary

Submit a summary request with your patientId and summaryTemplateId. The response streams as Server-Sent Events (SSE). 
curl -X POST "https://$CLINIA_WORKSPACE/ai/v1/summaries" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "patientId": "patient-bob-gratton",
    "summaryTemplateId": "{summaryTemplateId}"
  }'

​
SSE event stream

Each SSE event carries a JSON payload in its data field. Events arrive in the following sequence:
Event typeDescription
text-startSignals the start of a new section. Includes sectionTitle and sectionIndex.
text-deltaA text chunk for the current section. Append to previous deltas for the same sectionIndex.
text-endSignals that all deltas for a section have been sent.
summary-endSignals end of generation. On success, includes a summaryId for later retrieval.
Example stream: 
id: 1
data: {"type":"text-start","payload":{"sectionTitle":"History of Present Illness","sectionIndex":0}}

id: 2
data: {"type":"text-delta","payload":{"text":"Patient reports worsening shortness of breath over 2 days.","sectionTitle":"History of Present Illness","sectionIndex":0}}

id: 3
data: {"type":"text-end","payload":{"sectionTitle":"History of Present Illness","sectionIndex":0}}

id: 4
data: {"type":"summary-end","payload":{"status":"success","summaryId":"sum_01JABZX3V4Q2P2M41ME6E3FQ7R"}}
Multiple sections can stream in parallel. Use sectionIndex to correctly order and render sections as they arrive.

​
Retrieving a saved summary

Once generation completes successfully, retrieve the persisted summary at any time using the summaryId from the summary-end event: 
curl -X GET "https://$CLINIA_WORKSPACE/ai/v1/summaries/{summaryId}" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN"
You can also list all summaries for a patient: 
curl -X GET "https://$CLINIA_WORKSPACE/ai/v1/summaries?patientId=patient-bob-gratton&page=0&perPage=20" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN"