> ## 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 Patient Summary For Specific Encounter
> Trigger asynchronous generation of summaries for a specific encounter and practitioner from CKG data
Use this endpoint to **generate** summaries by providing the `fhir_encounter_id` and `fhir_practitioner_id`. The endpoint retruns `patient_summary_id`.
Use `patient_summary_id` to **retrieve** the generated summaries via the [Get full Patient Summary using Patient Summary ID](/patient-summary-api-reference/summaries/patient-summary) endpoint.
Patient summaries are generated from data previously **ingested** into the Clinical Knowledge Graph (CKG).
Before calling this endpoint, ensure the required Patient, Encounter, and Practitioner resources have been ingested using the [CKG Data Ingestion APIs](/patient-summary-api-reference/ckg-data-ingestion).
* It is recommended that partners send Suki this data every morning (at midnight) for all appointments scheduled that day in order to avoid waiting for the API to complete the generation process.
* **Processing speed:** Each individual appointment takes roughly **20 seconds** to generate a Patient Summary once the API is triggered.
**Prerequisites:**
* Ingest the required Patient, Encounter, and Practitioner resources using the CKG Data Ingestion APIs.
* Include consistent patient, encounter, and practitioner identifiers in the FHIR resources.
* Ensure these identifiers match the `fhir_encounter_id` and `fhir_practitioner_id` values you use for generation and retrieval.
Generation typically completes within a **few seconds** to **a few minutes**, depending on the amount of patient data available in the CKG.
## Request body
| Field | Type | Required | Description |
| ---------------------- | ------ | -------- | ----------------------------------------------------------------------------- |
| `fhir_encounter_id` | string | Yes | Encounter identifier. Must match the identifier in the ingested FHIR data. |
| `fhir_practitioner_id` | string | Yes | Practitioner identifier. Must match the identifier in the ingested FHIR data. |
After the request returns 201, call the Patient Summary retrieval endpoint with `patient_summary_id` (or use the encounter/practitioner retrieval path) to fetch the generated summary by using the following endpoints:
## OpenAPI
````yaml POST /api/v1/patient-summary/generate/encounter
openapi: 3.0.1
info:
title: Suki Developer Platform
description: >-
REST and WebSocket APIs for the Suki Developer Platform. Authenticate with
Login or Register to obtain a Suki access token, then integrate ambient
clinical documentation, form filling, transcription, and reference metadata
endpoints.
contact: {}
version: '1.0'
servers:
- url: https://sdp.suki.ai
description: >-
Production base URL for Suki Developer Platform REST APIs. WebSocket
endpoints use the same host with `wss://`.
security:
- SukiTokenAuth: []
paths:
/api/v1/patient-summary/generate/encounter:
post:
tags:
- /api/v1/patient-summary
summary: Generate patient summary for an encounter
description: >-
Trigger asynchronous generation of a patient summary for a specific
encounter and practitioner. The API returns 202 Accepted immediately
when the job is scheduled. Generation typically completes within seconds
to minutes depending on the volume of CKG data available. Poll GET
/api/v1/patient-summary/encounter/{fhir_encounter_id}/practitioner/{fhir_practitioner_id}/status
to check when generation completes, then retrieve the summary via the
GET endpoint. Ensure FHIR data for the patient, encounter, and
practitioner has been ingested via the CKG Data Ingestion API before
triggering generation.
parameters:
- $ref: '#/components/parameters/ProviderIdHeader'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
fhir_encounter_id:
type: string
description: FHIR encounter identifier (required).
fhir_practitioner_id:
type: string
description: FHIR practitioner identifier (required).
required:
- fhir_encounter_id
- fhir_practitioner_id
example:
fhir_encounter_id: enc-123
fhir_practitioner_id: pract-456
responses:
'201':
description: >-
Created. Summary generation request accepted and a patient summary
resource was created.
content:
application/json:
schema:
type: object
properties:
patient_summary_id:
type: string
description: Patient summary job ID returned from generate APIs.
required:
- patient_summary_id
examples:
created:
value:
patient_summary_id: ee90d46e-1085-4a05-aa6a-1049113e857a
'400':
description: Bad request. The request body or parameters failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/controllers.BadRequestError'
examples:
bad_request:
value:
code: 400
message: invalid request
'401':
description: Unauthorized. The Suki access token is missing, expired, or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/controllers.AuthenticationError'
examples:
unauthorized:
value:
code: 401
message: invalid token
'403':
description: >-
Forbidden. Token lacks required scopes or access to the
organization.
content:
application/json:
schema:
$ref: '#/components/schemas/controllers.ForbiddenError'
examples:
forbidden:
value:
code: 403
message: forbidden
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/controllers.InternalServerError'
examples:
internal_error:
value:
code: 500
message: internal server error
security:
- SukiTokenAuth: []
x-codeSamples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url https://sdp.suki.ai/api/v1/patient-summary/generate/encounter \
--header 'Content-Type: application/json' \
--header 'sdp_suki_token: ' \
--header 'sdp_provider_id: ' \
--data '{"fhir_encounter_id":"enc-123","fhir_practitioner_id":"pract-456"}'
- lang: python
label: Python
source: >-
import requests
import time
BASE_URL = "https://sdp.suki.ai"
sdp_token = ""
encounter_id = "enc-123"
practitioner_id = "pract-456"
# Step 1: Trigger generation
response = requests.post(
f"{BASE_URL}/api/v1/patient-summary/generate/encounter",
headers={"sdp_suki_token": sdp_token, "Content-Type": "application/json"},
json={"fhir_encounter_id": encounter_id, "fhir_practitioner_id": practitioner_id},
timeout=30
)
response.raise_for_status()
print(f"Generation triggered (Status: {response.status_code})")
# Step 2: Poll status until complete
status_url =
f"{BASE_URL}/api/v1/patient-summary/encounter/{encounter_id}/practitioner/{practitioner_id}/status"
while True:
status_resp = requests.get(status_url, headers={"sdp_suki_token": sdp_token}, timeout=30)
status_data = status_resp.json()
print(f"Status: {status_data['status']}")
if status_data["status"] == "COMPLETED":
break
elif status_data["status"] == "FAILED":
raise Exception(f"Failed: {status_data.get('error')}")
time.sleep(5)
print("Generation completed successfully")
- lang: javascript
label: TypeScript
source: >-
const BASE_URL = "https://sdp.suki.ai";
const sdpToken = "";
const encounterId = "enc-123";
const practitionerId = "pract-456";
// Step 1: Trigger generation
const generateResponse = await fetch(
`${BASE_URL}/api/v1/patient-summary/generate/encounter`,
{
method: "POST",
headers: {
sdp_suki_token: sdpToken,
"Content-Type": "application/json",
},
body: JSON.stringify({
fhir_encounter_id: encounterId,
fhir_practitioner_id: practitionerId,
}),
}
);
if (!generateResponse.ok) {
throw new Error(`Generation failed: ${generateResponse.status}`);
}
console.log("Generation triggered");
// Step 2: Poll status until complete
const statusUrl =
`${BASE_URL}/api/v1/patient-summary/encounter/${encounterId}/practitioner/${practitionerId}/status`;
while (true) {
const statusResponse = await fetch(statusUrl, {
headers: { sdp_suki_token: sdpToken },
});
const statusData = await statusResponse.json();
console.log(`Status: ${statusData.status}`);
if (statusData.status === "COMPLETED") {
break;
} else if (statusData.status === "FAILED") {
throw new Error(`Failed: ${statusData.error}`);
}
await new Promise((resolve) => setTimeout(resolve, 5000));
}
console.log("Generation completed successfully");
components:
parameters:
ProviderIdHeader:
name: sdp_provider_id
in: header
description: >-
**Optional** for standard partners.
**Required** for:
- **Bearer authentication.** Use the same `provider_id` returned by the
Login or Register API.
- **Single Auth Token authentication.** Include the same `provider_id`
on every request as `sdp_provider_id`.
required: false
schema:
type: string
example: provider-123
schemas:
controllers.BadRequestError:
description: Bad Request Response
type: object
properties:
code:
type: integer
example: 400
message:
type: string
example: invalid request
controllers.AuthenticationError:
description: Authentication Failure Response
type: object
properties:
code:
type: integer
example: 401
message:
type: string
example: invalid token
controllers.ForbiddenError:
type: object
properties:
code:
type: integer
example: 403
description: HTTP status code for the error.
message:
type: string
example: forbidden
description: Human-readable description of the authorization failure.
description: Error response when the caller lacks permission.
controllers.InternalServerError:
description: Internal Server Error Response
type: object
properties:
code:
type: integer
example: 500
message:
type: string
example: internal server error
securitySchemes:
SukiTokenAuth:
type: apiKey
in: header
name: sdp_suki_token
description: >-
Suki access token (`suki_token`) from Login or Register. Expires after
one hour.
````