> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Generate a Patient Summary
> Trigger encounter Patient Summary generation and store the returned patient_summary_id
export const CbRecipeMeta = ({items = []}) =>
;
};
}
sidebar={{
apiHref: "/patient-summary-api-reference/summary-generation/encounter-summary",
authSections: [
{
title: "Partner API",
text: "Authenticate every REST call with Partner Token headers on each request. See",
href: "/documentation/get-started/partner-authentication",
linkLabel: "Partner authentication",
scopes: ["sdp_suki_token", "sdp_provider_id"],
},
],
glance: [
{ label: "Product", value: "Patient Summary" },
{ label: "Surface", value: "Partner API" },
{ label: "Time", value: "~5 min" },
{ label: "Level", value: "Beginner" },
],
}}
>
## Problem
You need a summary for one upcoming visit, but generation is asynchronous and the summary is not in the create response. Calling retrieve immediately after generate returns empty or missing content.
Patient Summary jobs run in the background. The generate endpoint returns a `patient_summary_id` you must store, then poll status until `COMPLETED` before retrieve APIs return the finished summary.
## Architecture
```mermaid actions={false} theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFFBDE','primaryTextColor':'#1C1C1C','primaryBorderColor':'#FFD147','lineColor':'#6F5410','secondaryColor':'#FFFDF5','tertiaryColor':'#FFEB94','fontSize':'13px'}}}%%
flowchart LR
A[CKG COMPLETED] --> B[POST generate]
B --> C[Store patient_summary_id]
C --> D[Poll status]
D --> E[Retrieve summary]
```
## Prerequisites
CKG ingestion for the patient, encounter, and practitioner is `COMPLETED`. See [Ingest FHIR into CKG](/documentation/cookbooks/upload-fhir-to-ckg-and-poll).Completed [Partner onboarding](/documentation/get-started/partner-onboarding) with `sdp_suki_token` and `sdp_provider_id` headers ready.`fhir_encounter_id` and `fhir_practitioner_id` values that match the ingested FHIR bundle.
## Solution
CKG ingestion for this encounter is `COMPLETED`.
POST generate, accept `201` or `202`, and store `patient_summary_id` when returned.
[Wait for Patient Summary before Fetch](/documentation/cookbooks/poll-patient-summary-status-before-retrieve)
Call [Generate Patient Summary for an encounter](/patient-summary-api-reference/summary-generation/encounter-summary) with `fhir_encounter_id` and `fhir_practitioner_id`. Store `patient_summary_id` when returned. Poll status next, then retrieve.
```bash theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
curl --request POST \
--url "${SUKI_BASE_URL:-https://sdp.suki.ai}/api/v1/patient-summary/generate/encounter" \
--header 'Content-Type: application/json' \
--header "sdp_suki_token: ${SDP_SUKI_TOKEN}" \
--header "sdp_provider_id: ${SDP_PROVIDER_ID}" \
--data '{
"fhir_encounter_id": "enc-123",
"fhir_practitioner_id": "pract-456"
}'
```
```typescript theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
// generate-patient-summary-for-encounter.ts
const BASE_URL = process.env.SUKI_BASE_URL ?? "https://sdp.suki.ai";
const SDP_SUKI_TOKEN = process.env.SDP_SUKI_TOKEN!;
const SDP_PROVIDER_ID = process.env.SDP_PROVIDER_ID ?? "";
const FHIR_ENCOUNTER_ID = process.env.FHIR_ENCOUNTER_ID ?? "enc-123";
const FHIR_PRACTITIONER_ID = process.env.FHIR_PRACTITIONER_ID ?? "pract-456";
function restHeaders(): Record {
const headers: Record = {
"Content-Type": "application/json",
sdp_suki_token: SDP_SUKI_TOKEN,
};
if (SDP_PROVIDER_ID) headers.sdp_provider_id = SDP_PROVIDER_ID;
return headers;
}
async function generatePatientSummaryForEncounter(
fhirEncounterId: string,
fhirPractitionerId: string
): Promise {
const res = await fetch(`${BASE_URL}/api/v1/patient-summary/generate/encounter`, {
method: "POST",
headers: restHeaders(),
body: JSON.stringify({
fhir_encounter_id: fhirEncounterId,
fhir_practitioner_id: fhirPractitionerId,
}),
});
// OpenAPI documents 201 with patient_summary_id; quickstart also accepts 202.
if (res.status !== 201 && res.status !== 202) {
throw new Error(`Generate for encounter failed: ${res.status}`);
}
const data = (await res.json().catch(() => ({}))) as {
patient_summary_id?: string;
};
// Store when present. You can also poll/retrieve by FHIR encounter + practitioner ids.
return data.patient_summary_id;
}
const patientSummaryId = await generatePatientSummaryForEncounter(
FHIR_ENCOUNTER_ID,
FHIR_PRACTITIONER_ID
);
console.log("patient_summary_id:", patientSummaryId ?? "(poll by FHIR ids)");
// Next: poll status before retrieve
```
```python theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
# generate_patient_summary_for_encounter.py
# pip install requests
import os
from typing import Optional
import requests
BASE_URL = os.environ.get("SUKI_BASE_URL", "https://sdp.suki.ai")
SDP_SUKI_TOKEN = os.environ["SDP_SUKI_TOKEN"]
SDP_PROVIDER_ID = os.environ.get("SDP_PROVIDER_ID", "")
FHIR_ENCOUNTER_ID = os.environ.get("FHIR_ENCOUNTER_ID", "enc-123")
FHIR_PRACTITIONER_ID = os.environ.get("FHIR_PRACTITIONER_ID", "pract-456")
def rest_headers() -> dict[str, str]:
headers = {
"Content-Type": "application/json",
"sdp_suki_token": SDP_SUKI_TOKEN,
}
if SDP_PROVIDER_ID:
headers["sdp_provider_id"] = SDP_PROVIDER_ID
return headers
def generate_patient_summary_for_encounter(
fhir_encounter_id: str,
fhir_practitioner_id: str,
) -> Optional[str]:
res = requests.post(
f"{BASE_URL}/api/v1/patient-summary/generate/encounter",
headers=rest_headers(),
json={
"fhir_encounter_id": fhir_encounter_id,
"fhir_practitioner_id": fhir_practitioner_id,
},
timeout=30,
)
# OpenAPI documents 201 with patient_summary_id; quickstart also accepts 202.
if res.status_code not in (201, 202):
res.raise_for_status()
data = res.json() if res.content else {}
return data.get("patient_summary_id")
patient_summary_id = generate_patient_summary_for_encounter(
FHIR_ENCOUNTER_ID,
FHIR_PRACTITIONER_ID,
)
print("patient_summary_id:", patient_summary_id or "(poll by FHIR ids)")
# Next: poll status before retrieve
```
Do not generate until [Ingest FHIR into CKG](/documentation/cookbooks/upload-fhir-to-ckg-and-poll) returns `COMPLETED` for the same patient and encounter.
POST to [Generate Patient Summary for an encounter](/patient-summary-api-reference/summary-generation/encounter-summary) with matching `fhir_encounter_id` and `fhir_practitioner_id`.
Persist the returned ID. The generate response does not contain the finished summary text.
Poll status until `COMPLETED`, then call retrieve APIs. Use [Wait for Patient Summary before fetch](/documentation/cookbooks/poll-patient-summary-status-before-retrieve) next.
## Try it
* **Generate returns patient\_summary\_id**
A successful POST returns a job ID, not the summary body. Store it for status polling and retrieve calls.
* **Retrieve waits for COMPLETED**
Calling retrieve while status is `READY` or `RUNNING` returns empty or partial data. Poll first.
* **Existing summaries avoid duplicate jobs**
Check whether a usable summary already exists for the appointment before re-generating.
## Common mistakes
* Generating before CKG ingestion is `COMPLETED`.
* Mismatched `fhir_encounter_id` or `fhir_practitioner_id` versus ingested FHIR data.
* Treating the generate response as the finished summary instead of saving `patient_summary_id` and polling.
* Re-generating when a usable summary for the appointment already exists.
## Related cookbooks
Upload FHIR, then wait for COMPLETED.
Poll until status is COMPLETED.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.