> ## 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.
# Seed Ambient Session Context
> Provide clinical context and patient information for ambient session
**Updated:**
You can now provide **EMR context** and **medication details** in the Ambient session context API.
Use this endpoint to provide or update the session context for an ambient session. Providing detailed context helps Suki generate a more accurate and relevant clinical note.
For example, you can provide:
* Provider details (e.g., specialty and role).
* Patient and visit information.
* A list of LOINC codes for the clinical sections you want to generate.
* Existing diagnoses with their associated medical codes.
* EMR context, including target EMR, when you need EMR-specific behavior (for example order submission rules).
* Orders context (medication orders), including structured medication orders for active medications and related metadata.
For more information about the context, refer to the [PBC](/api-reference/capabilities/problem-based-charting) and [Specialty](/documentation/specialties) section.
For more information about medication orders, refer to the [Medication orders](/documentation/medication-orders) guide.
Use the `Codes` section to provide additional context for a session, such as **medical codes** for a **diagnosis**.
To ensure your requests succeed, follow these validation rules when sending data to the API:
### Field validation and constraints
* **Character Limits**: Ensure the **`chief_complaint`** and **`reason_for_visit`** fields do not exceed **255 characters**.
* **Enumerated Values**: Use only the predefined string values for **`visit_type`**, **`encounter_type`**, and **`provider_role`**.
* **EMR Selection**: You must set **`emr.target_emr`** to one of the following: **`ATHENA`**, **`EPIC`**, or **`CERNER`**.
### Medication order requirements
When you send **`orders.medication_orders.values`**, include the following required properties for each object:
* **Drug Information**: Provide both the **`drug_name`** and a **`medication_code`**.
* **Coding Systems**: For **`medication_code`**, specify the **`code`** and set the **`type`** to **`RXCUI`** or **`NDC`**.
* **Order Status**: Set the **`status`** to **`ACTIVE`**, **`DISCONTINUED`**, or **`REFILLED`**.
* **Metadata**: Include the **`metadata`** object with a required **`origin`** of **`EMR`** or **`SUKI_AMBIENT`**.
If you set **`origin`** to **`EMR`**, you must also set **`metadata.encounter_relation`** to either **`CURRENT_ENCOUNTER`** or **`PRIOR_ENCOUNTER`**.
**Diagnosis links**:
To link a diagnosis to an order, ensure the codes in **`linked_diagnosis_codes`** match a diagnosis already provided in the **`diagnoses`** section.
Use the same coding system for both to allow the service to validate the link.
## Code examples
```python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
import requests
ambient_session_id = "123dfg-456dfg-789dfg-012dfg"
url = f"https://sdp.suki-stage.com/api/v1/ambient/session/{ambient_session_id}/context"
headers = {
"sdp_suki_token": "",
"sdp_provider_id": "",
"Content-Type": "application/json"
}
payload = {
"provider": {
"specialty": "CARDIOLOGY",
"provider_role": "ATTENDING"
},
"patient": {
"dob": "2000-01-01",
"sex": "male"
},
"visit": {
"chief_complaint": "Headache",
"encounter_type": "AMBULATORY",
"reason_for_visit": "Follow-up for migraines",
"visit_type": "ESTABLISHED_PATIENT"
},
"sections": [
{"loinc": "10164-2"},
{"loinc": "48765-2"}
],
"diagnoses": {
"values": [
{
"codes": [
{
"code": "I10",
"description": "Essential hypertension",
"type": "ICD10"
}
],
"diagnosis_note": "Hypertension"
}
]
},
"emr": {
"target_emr": "EPIC"
},
"orders": {
"medication_orders": {
"values": [
{
"drug_name": "Acetaminophen 500mg Tab",
"medication_code": {"code": "860975", "type": "RXCUI"},
"linked_diagnosis_codes": [
{"code": "I10", "type": "ICD10"}
],
"metadata": {"origin": "SUKI_AMBIENT"},
"status": "ACTIVE",
"instructions": "Take with food"
}
]
}
}
}
response = requests.post(url, json=payload, headers=headers)
if response.status_code == 200:
print("Context seeded successfully")
else:
print(f"Failed to seed context: {response.status_code}")
print(response.json())
```
```typescript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
const ambientSessionId = '123dfg-456dfg-789dfg-012dfg';
const response = await fetch(
`https://sdp.suki-stage.com/api/v1/ambient/session/${ambientSessionId}/context`,
{
method: 'POST',
headers: {
'sdp_suki_token': '',
'sdp_provider_id': '',
'Content-Type': 'application/json'
},
body: JSON.stringify({
provider: {
specialty: 'CARDIOLOGY',
provider_role: 'ATTENDING'
},
patient: {
dob: '2000-01-01',
sex: 'male'
},
visit: {
chief_complaint: 'Headache',
encounter_type: 'AMBULATORY',
reason_for_visit: 'Follow-up for migraines',
visit_type: 'ESTABLISHED_PATIENT'
},
sections: [
{ loinc: '10164-2' },
{ loinc: '48765-2' }
],
diagnoses: {
values: [
{
codes: [
{
code: 'I10',
description: 'Essential hypertension',
type: 'ICD10'
}
],
diagnosis_note: 'Hypertension'
}
]
},
emr: {
target_emr: 'EPIC'
},
orders: {
medication_orders: {
values: [
{
drug_name: 'Acetaminophen 500mg Tab',
medication_code: { code: '860975', type: 'RXCUI' },
linked_diagnosis_codes: [{ code: 'I10', type: 'ICD10' }],
metadata: { origin: 'SUKI_AMBIENT' },
status: 'ACTIVE',
instructions: 'Take with food'
}
]
}
}
})
}
);
if (response.ok) {
console.log('Context seeded successfully');
} else {
const error = await response.json();
console.error(`Failed to seed context: ${response.status}`, error);
}
```
## OpenAPI
````yaml POST /api/v1/ambient/session/{ambient_session_id}/context
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/ambient/session/{ambient_session_id}/context:
post:
tags:
- /api/v1/ambient/session
summary: Seed ambient session context
description: >-
Seeds clinical context for an ambient session before or during audio
capture. Send provider, patient, visit, section, diagnosis, EMR, and
medication order metadata to improve note quality. Replaces the entire
context when called.
parameters:
- name: ambient_session_id
in: path
description: >-
UUID for the ambient session. Use the `ambient_session_id` returned
from Create Ambient Session, or the UUID you supplied in that
request.
required: true
schema:
type: string
- $ref: '#/components/parameters/ProviderIdHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/controllers.Context'
example:
diagnoses:
values:
- codes:
- code: '30422'
description: Essential hypertension
type: IMO
diagnosis_note: Hypertension
emr:
target_emr: ATHENA
orders:
medication_orders:
values:
- dosage:
quantity: 1
raw_value: 1 tablet
unit: TAB
drug_name: Acetaminophen 500mg Tab
duration_in_days: 7
end_date: '2026-01-08T00:00:00Z'
format:
raw_value: Tablet
frequency:
raw_value: once daily
structured_value: ONE_A_DAY
instructions: Take with food
linked_diagnosis_codes:
- code: I10
type: ICD10
medication_code:
code: '860975'
type: RXCUI
medication_timing:
raw_value: morning
structured_value: IN_THE_MORNING
metadata:
encounter_relation: CURRENT_ENCOUNTER
origin: SUKI_AMBIENT
number_of_refills: 3
quantity_dispensed: 1 box
route:
raw_value: Oral
start_date: '2026-01-01T00:00:00Z'
status: ACTIVE
strength:
raw_value: 500mg
patient:
dob: '2000-01-01'
sex: male
provider:
role: ATTENDING
specialty: CARDIOLOGY
sections:
- loinc: 10164-2
visit:
chief_complaint: Headache
encounter_type: AMBULATORY
reason_for_visit: Follow-up for migraines
visit_type: ESTABLISHED_PATIENT
required: true
responses:
'200':
description: Request succeeded.
content: {}
'400':
description: Bad request. The request body or parameters failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/controllers.BadRequestError'
'401':
description: Unauthorized. The Suki access token is missing, expired, or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/controllers.AuthenticationError'
'403':
description: Forbidden. The authenticated user cannot access this resource.
content:
application/json:
schema:
$ref: '#/components/schemas/controllers.ForbiddenError'
'404':
description: Not found. The session, encounter, or resource ID does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/controllers.NotFoundError'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/controllers.InternalServerError'
security:
- SukiTokenAuth: []
x-codeSamples:
- lang: bash
label: cURL
source: |-
curl --request POST \
--url https://sdp.suki.ai/api/v1/ambient/session//context \
--header 'Content-Type: application/json' \
--header 'sdp_suki_token: ' \
--header 'sdp_provider_id: ' \
--data '{
"diagnoses": {
"values": [
{
"codes": [
{
"code": "30422",
"description": "Essential hypertension",
"type": "IMO"
}
],
"diagnosis_note": "Hypertension"
}
]
},
"emr": {
"target_emr": "ATHENA"
},
"orders": {
"medication_orders": {
"values": [
{
"dosage": {
"quantity": 1,
"raw_value": "1 tablet",
"unit": "TAB"
},
"drug_name": "Acetaminophen 500mg Tab",
"duration_in_days": 7,
"end_date": "2026-01-08T00:00:00Z",
"format": {
"raw_value": "Tablet"
},
"frequency": {
"raw_value": "once daily",
"structured_value": "ONE_A_DAY"
},
"instructions": "Take with food",
"linked_diagnosis_codes": [
{
"code": "I10",
"type": "ICD10"
}
],
"medication_code": {
"code": "860975",
"type": "RXCUI"
},
"medication_timing": {
"raw_value": "morning",
"structured_value": "IN_THE_MORNING"
},
"metadata": {
"encounter_relation": "CURRENT_ENCOUNTER",
"origin": "SUKI_AMBIENT"
},
"number_of_refills": 3,
"quantity_dispensed": "1 box",
"route": {
"raw_value": "Oral"
},
"start_date": "2026-01-01T00:00:00Z",
"status": "ACTIVE",
"strength": {
"raw_value": "500mg"
}
}
]
}
},
"patient": {
"dob": "2000-01-01",
"sex": "male"
},
"provider": {
"role": "ATTENDING",
"specialty": "CARDIOLOGY"
},
"sections": [
{
"loinc": "10164-2"
}
],
"visit": {
"chief_complaint": "Headache",
"encounter_type": "AMBULATORY",
"reason_for_visit": "Follow-up for migraines",
"visit_type": "ESTABLISHED_PATIENT"
}
}'
components:
parameters:
ProviderIdHeader:
name: sdp_provider_id
in: header
description: >-
**Optional** - Stable identifier for the active provider. Omit for
standard partners whose `partner_token` identifies the user.
**Required** for Bearer partners and Single Auth Token authentication
where multiple providers share one `partner_token`. Use the same
`provider_id` you sent on Login or Register.
required: false
schema:
type: string
example: provider-123
schemas:
controllers.Context:
type: object
properties:
diagnoses:
type: object
description: >-
**Optional** - Existing diagnoses and coded values to include in
note generation.
allOf:
- $ref: '#/components/schemas/controllers.DiagnosesContext'
emr:
type: object
description: '**Optional** - EMR context, including the target EMR system.'
allOf:
- $ref: '#/components/schemas/controllers.EmrContext'
orders:
type: object
description: '**Optional** - Medication orders and related order context.'
allOf:
- $ref: '#/components/schemas/controllers.OrdersContext'
patient:
type: object
description: '**Optional** - Patient demographics such as date of birth and sex.'
allOf:
- $ref: '#/components/schemas/controllers.PatientContext'
provider:
type: object
description: '**Optional** - Provider role and specialty for the session.'
allOf:
- $ref: '#/components/schemas/controllers.ProviderContext'
sections:
type: array
description: >-
**Optional** - Information about the sections to be generated.
If not provided, all supported
[note-sections](/documentation/note-sections) will be generated.
items:
$ref: '#/components/schemas/controllers.SectionContext'
visit:
type: object
description: >-
**Optional** - Visit details such as chief complaint and encounter
type.
allOf:
- $ref: '#/components/schemas/controllers.VisitContext'
description: >-
Clinical context for the ambient session, including provider, patient,
visit, sections, diagnoses, EMR, and medication orders.
controllers.BadRequestError:
type: object
properties:
code:
type: integer
example: 400
description: HTTP status code for the error.
message:
type: string
example: invalid request
description: Human-readable description of the validation or request error.
description: Error response when the request fails validation.
controllers.AuthenticationError:
type: object
properties:
code:
type: integer
example: 401
description: HTTP status code for the error.
message:
type: string
example: invalid token
description: Human-readable description of the authentication failure.
description: Error response when authentication fails.
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.NotFoundError:
type: object
properties:
code:
type: integer
example: 404
description: HTTP status code for the error.
message:
type: string
example: not found
description: Human-readable description of the missing resource.
description: Error response when the requested resource was not found.
controllers.InternalServerError:
type: object
properties:
code:
type: integer
example: 500
description: HTTP status code for the error.
message:
type: string
example: internal server error
description: Human-readable description of the server error.
description: Error response when the server encounters an unexpected error.
controllers.DiagnosesContext:
type: object
properties:
values:
type: array
description: '**Optional** - Array of diagnosis requests'
items:
$ref: '#/components/schemas/controllers.DiagnosisRequest'
controllers.EmrContext:
type: object
properties:
target_emr:
type: string
description: >-
**Optional** - Target EMR for context-aware processing, such as
order submission and validation rules. Supported values include
ATHENA, EPIC, and CERNER.
enum:
- ATHENA
- EPIC
- CERNER
example: ATHENA
description: Target EMR for context-aware processing.
controllers.OrdersContext:
type: object
properties:
medication_orders:
type: object
description: '**Optional** - Medication orders supplied in context'
allOf:
- $ref: '#/components/schemas/controllers.MedicationOrdersContext'
controllers.PatientContext:
type: object
properties:
dob:
type: string
description: '**Optional** - Patient date of birth in `YYYY-MM-DD` format.'
example: '2000-01-01'
sex:
type: string
description: >-
**Optional** - Patient sex. Accepted values: `male`, `female`,
`other`.
example: male
enum:
- male
- female
- other
- unknown
description: Patient demographics used to guide note generation.
controllers.ProviderContext:
type: object
properties:
provider_role:
type: string
description: >-
Provider role for the session. Call `GET
/api/v1/info/provider-roles` for supported values.
example: ATTENDING
enum:
- ATTENDING
- CONSULTING
specialty:
type: string
description: >-
**Optional** - Provider medical specialty. Call `GET
/api/v1/info/specialties` for supported values.
example: CARDIOLOGY
controllers.SectionContext:
type: object
required:
- loinc
properties:
loinc:
type: string
description: >-
LOINC code for the section. Supported Loinc codes are available at:
[note-sections](/documentation/note-sections)
example: 10164-2
controllers.VisitContext:
type: object
properties:
chief_complaint:
type: string
description: Captures the initial problem the patient presents with
example: >-
Headache (Patient's primary symptom or problem stated in their own
words)
encounter_type:
type: string
description: >-
Encounter setting, such as AMBULATORY or INPATIENT. Call `GET
/api/v1/info/encounter-types` for supported values.
example: AMBULATORY
enum:
- AMBULATORY
- INPATIENT
- EMERGENCY
reason_for_visit:
type: string
description: >-
Specific symptom / condition, or request (e.g., chest pain, wellness
exam)
example: Follow-up for migraines
visit_type:
type: string
description: >-
Visit category, such as NEW_PATIENT or ESTABLISHED_PATIENT. Call
`GET /api/v1/info/visit-types` for supported values.
example: ESTABLISHED_PATIENT
enum:
- NEW_PATIENT
- ESTABLISHED_PATIENT
- WELLNESS
- ED
description: Visit details such as chief complaint, encounter type, and visit type.
controllers.DiagnosisRequest:
type: object
properties:
codes:
type: array
description: >-
**Optional** - Codes associated with the diagnosis. When sending
context, use ICD10 or IMO. HCC codes are returned in structured data
output only.
items:
$ref: '#/components/schemas/controllers.Code'
diagnosis_note:
type: string
description: '**Optional** - Diagnosis note'
example: Hypertension
controllers.MedicationOrdersContext:
type: object
properties:
values:
type: array
description: '**Optional** - Medication order requests'
items:
$ref: '#/components/schemas/controllers.MedicationOrderRequest'
controllers.Code:
type: object
properties:
code:
type: string
description: Code value for the diagnosis or medication coding system.
example: '30422'
description:
type: string
description: >-
Description of the code. For HCC codes, the description uses the
format `CMS-HCC model category `.
example: Essential hypertension
type:
type: string
description: >-
Diagnosis coding system for this code value. HCC codes are returned
in ambient structured data output when the ICD-10-CM diagnosis maps
to a CMS-HCC model category (V28).
example: IMO
enum:
- UNSPECIFIED
- IMO
- ICD10
- SNOMED
- HCC
controllers.MedicationOrderRequest:
type: object
required:
- drug_name
- medication_code
- status
- metadata
properties:
dosage:
type: object
description: '**Optional** - Amount per administration'
allOf:
- $ref: '#/components/schemas/controllers.Dosage'
drug_name:
type: string
description: '**Required** - Full medication name'
example: Acetaminophen 500mg Tab
duration_in_days:
type: integer
description: '**Optional** - Duration in days'
example: 7
end_date:
type: string
description: '**Optional** - End date-time (RFC3339)'
example: '2026-01-08T00:00:00Z'
format:
type: object
description: '**Optional** - Physical dosage form'
allOf:
- $ref: '#/components/schemas/controllers.Format'
frequency:
type: object
description: '**Optional** - Administration frequency'
allOf:
- $ref: '#/components/schemas/controllers.Frequency'
instructions:
type: string
description: '**Optional** - Free-form instructions'
example: Take with food
linked_diagnosis_codes:
type: array
description: >-
**Optional** - Diagnosis codes linked to this order. When provided,
each entry should match a diagnosis already supplied under
`diagnoses` (same coding system) so the platform can validate the
link.
items:
$ref: '#/components/schemas/controllers.LinkedDiagnosisCode'
medication_code:
type: object
description: >-
**Required** - Standardized medication code (`code` and `type` are
both required; see `MedicationCode`)
allOf:
- $ref: '#/components/schemas/controllers.MedicationCode'
medication_timing:
type: object
description: '**Optional** - Timing modifiers'
allOf:
- $ref: '#/components/schemas/controllers.MedicationTiming'
metadata:
type: object
description: >-
**Required** - Order metadata. **`origin`** is required (`EMR` or
`SUKI_AMBIENT`). **`encounter_relation`** is **required** when
**`origin`** is **`EMR`** (see `OrderMetadata`).
allOf:
- $ref: '#/components/schemas/controllers.OrderMetadata'
number_of_refills:
type: integer
description: '**Optional** - Number of refills'
example: 3
quantity_dispensed:
type: string
description: '**Optional** - Quantity dispensed'
example: 1 box
route:
type: object
description: '**Optional** - Administration route'
allOf:
- $ref: '#/components/schemas/controllers.Route'
start_date:
type: string
description: '**Optional** - Start date-time (RFC3339)'
example: '2026-01-01T00:00:00Z'
status:
type: string
description: '**Required** - Order status'
enum:
- ACTIVE
- DISCONTINUED
- REFILLED
example: ACTIVE
strength:
type: object
description: >-
**Optional** - Medication strength or concentration (`raw_value`
until standardized values are finalized)
allOf:
- $ref: '#/components/schemas/controllers.Strength'
controllers.Dosage:
type: object
properties:
quantity:
type: number
description: (Optional) Dosage quantity
example: 1
raw_value:
type: string
description: (Optional) Raw dosage text
example: 1 tablet
unit:
type: string
description: (Optional) Dosage unit
example: TAB
controllers.Format:
type: object
properties:
raw_value:
type: string
description: (Optional) Raw medication form
example: Tablet
controllers.Frequency:
type: object
properties:
raw_value:
type: string
description: (Optional) Raw frequency text
example: once daily
structured_value:
type: string
description: (Optional) Frequency enum
example: ONE_A_DAY
controllers.LinkedDiagnosisCode:
type: object
properties:
code:
type: string
description: (*Required) Diagnosis code value
example: I10
type:
type: string
description: (*Required) Diagnosis coding system
example: ICD10
controllers.MedicationCode:
type: object
properties:
code:
type: string
description: (*Required) Medication code value
example: '860975'
type:
type: string
description: (*Required) Medication coding system
enum:
- RXCUI
- NDC
example: RXCUI
controllers.MedicationTiming:
type: object
properties:
raw_value:
type: string
description: (Optional) Raw timing text
example: morning
structured_value:
type: string
description: (Optional) Medication timing enum
example: IN_THE_MORNING
controllers.OrderMetadata:
type: object
required:
- origin
properties:
encounter_relation:
type: string
description: >-
**Required when `origin` is `EMR`** - How this order relates to the
encounter. Set to **`CURRENT_ENCOUNTER`** or **`PRIOR_ENCOUNTER`**.
enum:
- CURRENT_ENCOUNTER
- PRIOR_ENCOUNTER
example: CURRENT_ENCOUNTER
origin:
type: string
description: '**Required** - Source of the order'
enum:
- EMR
- SUKI_AMBIENT
example: SUKI_AMBIENT
controllers.Route:
type: object
properties:
raw_value:
type: string
description: (Optional) Raw administration route
example: Oral
controllers.Strength:
type: object
properties:
raw_value:
type: string
description: (Optional) Raw strength value
example: 500mg
securitySchemes:
SukiTokenAuth:
type: apiKey
in: header
name: sdp_suki_token
description: >-
Suki access token for the authenticated provider. Obtain this by calling
Login or Register with a valid `partner_token`. Pass the `suki_token`
value from the JSON response as the `sdp_suki_token` header on REST
requests and non-browser WebSocket upgrades. Browser WebSocket clients
pass the token in `Sec-WebSocket-Protocol` instead. Tokens expire after
one hour; call Login again to refresh.
````