> ## 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.
# Update Ambient Session Context
> Update existing session context with new clinical information
**Updated:**
You can now update the ambient session context with new **EMR context** and **medication orders**.
Use this endpoint to update the session context for an ambient session. The API applies a field mask so you can send only the parts of the context you want to change.
This is a **PATCH** operation that allows partial updates to the session context.
## Comparison with POST Context
| Feature | POST (Seed) | PATCH (Update) |
| :---------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------- |
| **Purpose** | Set entire context all at once when available | Incrementally build context as information becomes available |
| **Data Approach** | Complete context payload | Partial context updates |
| **Timing** | Before EndSession. When you have all context information together. | Before EndSession. As information becomes available progressively |
| **Behavior** | Replaces entire context | Updates only specified fields |
## OpenAPI
````yaml PATCH /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:
patch:
tags:
- /api/v1/ambient/session
summary: Update ambient session context
description: >-
Partially updates ambient session context using a field mask. Send only
the context fields you want to add or change before you end the session.
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.UpdateContextRequest'
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:
application/json:
schema:
$ref: '#/components/schemas/controllers.UpdateContextResponse'
example:
context:
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
'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 PATCH \
--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** 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.UpdateContextRequest:
type: object
properties:
diagnoses:
type: object
description: '**Optional** - Diagnoses to add or update.'
allOf:
- $ref: '#/components/schemas/controllers.DiagnosesContext'
emr:
type: object
description: '**Optional** - EMR context to add or update.'
allOf:
- $ref: '#/components/schemas/controllers.EmrContext'
orders:
type: object
description: '**Optional** - Medication orders to add or update.'
allOf:
- $ref: '#/components/schemas/controllers.OrdersContext'
patient:
type: object
description: '**Optional** - Patient demographics to add or update.'
allOf:
- $ref: '#/components/schemas/controllers.PatientContext'
provider:
type: object
description: '**Optional** - Provider details to add or update.'
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/concepts/ambient-clinical-notes/note-sections)
will be generated.
items:
$ref: '#/components/schemas/controllers.SectionContext'
visit:
type: object
description: '**Optional** - Visit details to add or update.'
allOf:
- $ref: '#/components/schemas/controllers.VisitContext'
description: >-
Partial ambient session context update. Include only the fields you want
to add or change.
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
controllers.UpdateContextResponse:
type: object
properties:
context:
type: object
description: Updated context for the session
allOf:
- $ref: '#/components/schemas/controllers.Context'
description: Updated ambient session context after a successful PATCH.
example:
context:
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
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.NotFoundError:
description: Not Found Response
type: object
properties:
code:
type: integer
example: 404
message:
type: string
example: not found
controllers.InternalServerError:
description: Internal Server Error Response
type: object
properties:
code:
type: integer
example: 500
message:
type: string
example: internal server 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/concepts/ambient-clinical-notes/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.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/concepts/ambient-clinical-notes/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.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:
description: Code value
type: string
example: '30422'
description:
description: Description of the code
type: string
example: Essential hypertension
type:
type: string
enum:
- UNSPECIFIED
- IMO
- ICD10
- SNOMED
example: IMO
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:
description: (Optional) Dosage quantity
type: number
example: 1
raw_value:
description: (Optional) Raw dosage text
type: string
example: 1 tablet
unit:
description: (Optional) Dosage unit
type: string
example: TAB
controllers.Format:
type: object
properties:
raw_value:
description: (Optional) Raw medication form
type: string
example: Tablet
controllers.Frequency:
type: object
properties:
raw_value:
description: (Optional) Raw frequency text
type: string
example: once daily
structured_value:
description: (Optional) Frequency enum
type: string
example: ONE_A_DAY
controllers.LinkedDiagnosisCode:
type: object
properties:
code:
description: (*Required) Diagnosis code value
type: string
example: I10
type:
description: (*Required) Diagnosis coding system
type: string
example: ICD10
controllers.MedicationCode:
type: object
properties:
code:
description: (*Required) Medication code value
type: string
example: '860975'
type:
description: (*Required) Medication coding system
type: string
enum:
- RXCUI
- NDC
example: RXCUI
controllers.MedicationTiming:
type: object
properties:
raw_value:
description: (Optional) Raw timing text
type: string
example: morning
structured_value:
description: (Optional) Medication timing enum
type: string
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:
description: (Optional) Raw administration route
type: string
example: Oral
controllers.Strength:
type: object
properties:
raw_value:
description: (Optional) Raw strength value
type: string
example: 500mg
securitySchemes:
SukiTokenAuth:
type: apiKey
in: header
name: sdp_suki_token
description: >-
Suki access token (`suki_token`) from Login or Register. Expires after
one hour.
````