---
title: "Update ambient session context"
method: PATCH
path: "/api/v1/ambient/session/{ambient_session_id}/context"
tags: ["/api/v1/ambient/session"]
---

# Update ambient session context

`PATCH /api/v1/ambient/session/{ambient_session_id}/context`

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.

## Path parameters

- `ambient_session_id` string, required

## Headers

- `sdp_provider_id` string

## Request body

- ControllersUpdateContextRequest — Partial ambient session context update. Include only the fields you want to add or change.
  - `diagnoses` ControllersDiagnosesContext
    - `values` ControllersDiagnosisRequest[] — **Optional** - Array of diagnosis requests
      - `codes` ControllersCode[] — **Optional** - Codes associated with the diagnosis. When sending context, use ICD10 or IMO. HCC codes are returned in structured data output only.
        - `code` string — Code value
        - `description` string — Description of the code
        - `type` 'UNSPECIFIED' | 'IMO' | 'ICD10' | 'SNOMED'
      - `diagnosis_note` string — **Optional** - Diagnosis note
  - `emr` ControllersEmrContext — Target EMR for context-aware processing.
    - `target_emr` 'ATHENA' | 'EPIC' | 'CERNER' — **Optional** - Target EMR for context-aware processing, such as order submission and validation rules. Supported values include ATHENA, EPIC, and CERNER.
  - `orders` ControllersOrdersContext
    - `medication_orders` ControllersMedicationOrdersContext
      - `values` ControllersMedicationOrderRequest[] — **Optional** - Medication order requests
        - `dosage` ControllersDosage
          - `quantity` number — (Optional) Dosage quantity
          - `raw_value` string — (Optional) Raw dosage text
          - `unit` string — (Optional) Dosage unit
        - `drug_name` string, required — **Required** - Full medication name
        - `duration_in_days` integer — **Optional** - Duration in days
        - `end_date` string — **Optional** - End date-time (RFC3339)
        - `format` ControllersFormat
          - `raw_value` string — (Optional) Raw medication form
        - `frequency` ControllersFrequency
          - `raw_value` string — (Optional) Raw frequency text
          - `structured_value` string — (Optional) Frequency enum
        - `instructions` string — **Optional** - Free-form instructions
        - `linked_diagnosis_codes` ControllersLinkedDiagnosisCode[] — **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.
          - `code` string — (*Required) Diagnosis code value
          - `type` string — (*Required) Diagnosis coding system
        - `medication_code` ControllersMedicationCode, required
          - `code` string — (*Required) Medication code value
          - `type` 'RXCUI' | 'NDC' — (*Required) Medication coding system
        - `medication_timing` ControllersMedicationTiming
          - `raw_value` string — (Optional) Raw timing text
          - `structured_value` string — (Optional) Medication timing enum
        - `metadata` ControllersOrderMetadata, required
          - `encounter_relation` 'CURRENT_ENCOUNTER' | 'PRIOR_ENCOUNTER' — **Required when `origin` is `EMR`** - How this order relates to the encounter. Set to **`CURRENT_ENCOUNTER`** or **`PRIOR_ENCOUNTER`**.
          - `origin` 'EMR' | 'SUKI_AMBIENT', required — **Required** - Source of the order
        - `number_of_refills` integer — **Optional** - Number of refills
        - `quantity_dispensed` string — **Optional** - Quantity dispensed
        - `route` ControllersRoute
          - `raw_value` string — (Optional) Raw administration route
        - `start_date` string — **Optional** - Start date-time (RFC3339)
        - `status` 'ACTIVE' | 'DISCONTINUED' | 'REFILLED', required — **Required** - Order status
        - `strength` ControllersStrength
          - `raw_value` string — (Optional) Raw strength value
  - `patient` ControllersPatientContext — Patient demographics used to guide note generation.
    - `dob` string — **Optional** - Patient date of birth in `YYYY-MM-DD` format.
    - `sex` 'male' | 'female' | 'other' | 'unknown' — **Optional** - Patient sex. Accepted values: `male`, `female`, `other`.
  - `provider` ControllersProviderContext
    - `provider_role` 'ATTENDING' | 'CONSULTING' — Provider role for the session. Call `GET /api/v1/info/provider-roles` for supported values.
    - `specialty` string — **Optional** - Provider medical specialty. Call `GET /api/v1/info/specialties` for supported values.
  - `sections` ControllersSectionContext[] — **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.
    - `loinc` string, required — LOINC code for the section. Supported Loinc codes are available at: [note-sections](/documentation/concepts/ambient-clinical-notes/note-sections)
  - `visit` ControllersVisitContext — Visit details such as chief complaint, encounter type, and visit type.
    - `chief_complaint` string — Captures the initial problem the patient presents with
    - `encounter_type` 'AMBULATORY' | 'INPATIENT' | 'EMERGENCY' — Encounter setting, such as AMBULATORY or INPATIENT. Call `GET /api/v1/info/encounter-types` for supported values.
    - `reason_for_visit` string — Specific symptom / condition, or request (e.g., chest pain, wellness exam)
    - `visit_type` 'NEW_PATIENT' | 'ESTABLISHED_PATIENT' | 'WELLNESS' | 'ED' — Visit category, such as NEW_PATIENT or ESTABLISHED_PATIENT. Call `GET /api/v1/info/visit-types` for supported values.

## Response `200`

Request succeeded.

- ControllersUpdateContextResponse — Updated ambient session context after a successful PATCH.
  - `context` ControllersContext — Clinical context for the ambient session, including provider, patient, visit, sections, diagnoses, EMR, and medication orders.
    - `diagnoses` ControllersDiagnosesContext
      - `values` ControllersDiagnosisRequest[] — **Optional** - Array of diagnosis requests
        - `codes` ControllersCode[] — **Optional** - Codes associated with the diagnosis. When sending context, use ICD10 or IMO. HCC codes are returned in structured data output only.
          - `code` string — Code value
          - `description` string — Description of the code
          - `type` 'UNSPECIFIED' | 'IMO' | 'ICD10' | 'SNOMED'
        - `diagnosis_note` string — **Optional** - Diagnosis note
    - `emr` ControllersEmrContext — Target EMR for context-aware processing.
      - `target_emr` 'ATHENA' | 'EPIC' | 'CERNER' — **Optional** - Target EMR for context-aware processing, such as order submission and validation rules. Supported values include ATHENA, EPIC, and CERNER.
    - `orders` ControllersOrdersContext
      - `medication_orders` ControllersMedicationOrdersContext
        - `values` ControllersMedicationOrderRequest[] — **Optional** - Medication order requests
          - `dosage` ControllersDosage
            - `quantity` number — (Optional) Dosage quantity
            - `raw_value` string — (Optional) Raw dosage text
            - `unit` string — (Optional) Dosage unit
          - `drug_name` string, required — **Required** - Full medication name
          - `duration_in_days` integer — **Optional** - Duration in days
          - `end_date` string — **Optional** - End date-time (RFC3339)
          - `format` ControllersFormat
            - `raw_value` string — (Optional) Raw medication form
          - `frequency` ControllersFrequency
            - `raw_value` string — (Optional) Raw frequency text
            - `structured_value` string — (Optional) Frequency enum
          - `instructions` string — **Optional** - Free-form instructions
          - `linked_diagnosis_codes` ControllersLinkedDiagnosisCode[] — **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.
            - `code` string — (*Required) Diagnosis code value
            - `type` string — (*Required) Diagnosis coding system
          - `medication_code` ControllersMedicationCode, required
            - `code` string — (*Required) Medication code value
            - `type` 'RXCUI' | 'NDC' — (*Required) Medication coding system
          - `medication_timing` ControllersMedicationTiming
            - `raw_value` string — (Optional) Raw timing text
            - `structured_value` string — (Optional) Medication timing enum
          - `metadata` ControllersOrderMetadata, required
            - `encounter_relation` 'CURRENT_ENCOUNTER' | 'PRIOR_ENCOUNTER' — **Required when `origin` is `EMR`** - How this order relates to the encounter. Set to **`CURRENT_ENCOUNTER`** or **`PRIOR_ENCOUNTER`**.
            - `origin` 'EMR' | 'SUKI_AMBIENT', required — **Required** - Source of the order
          - `number_of_refills` integer — **Optional** - Number of refills
          - `quantity_dispensed` string — **Optional** - Quantity dispensed
          - `route` ControllersRoute
            - `raw_value` string — (Optional) Raw administration route
          - `start_date` string — **Optional** - Start date-time (RFC3339)
          - `status` 'ACTIVE' | 'DISCONTINUED' | 'REFILLED', required — **Required** - Order status
          - `strength` ControllersStrength
            - `raw_value` string — (Optional) Raw strength value
    - `patient` ControllersPatientContext — Patient demographics used to guide note generation.
      - `dob` string — **Optional** - Patient date of birth in `YYYY-MM-DD` format.
      - `sex` 'male' | 'female' | 'other' | 'unknown' — **Optional** - Patient sex. Accepted values: `male`, `female`, `other`.
    - `provider` ControllersProviderContext
      - `provider_role` 'ATTENDING' | 'CONSULTING' — Provider role for the session. Call `GET /api/v1/info/provider-roles` for supported values.
      - `specialty` string — **Optional** - Provider medical specialty. Call `GET /api/v1/info/specialties` for supported values.
    - `sections` ControllersSectionContext[] — **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.
      - `loinc` string, required — LOINC code for the section. Supported Loinc codes are available at: [note-sections](/documentation/concepts/ambient-clinical-notes/note-sections)
    - `visit` ControllersVisitContext — Visit details such as chief complaint, encounter type, and visit type.
      - `chief_complaint` string — Captures the initial problem the patient presents with
      - `encounter_type` 'AMBULATORY' | 'INPATIENT' | 'EMERGENCY' — Encounter setting, such as AMBULATORY or INPATIENT. Call `GET /api/v1/info/encounter-types` for supported values.
      - `reason_for_visit` string — Specific symptom / condition, or request (e.g., chest pain, wellness exam)
      - `visit_type` 'NEW_PATIENT' | 'ESTABLISHED_PATIENT' | 'WELLNESS' | 'ED' — Visit category, such as NEW_PATIENT or ESTABLISHED_PATIENT. Call `GET /api/v1/info/visit-types` for supported values.

## Other responses

- `400` — Bad request. The request body or parameters failed validation.
- `401` — Unauthorized. The Suki access token is missing, expired, or invalid.
- `403` — Forbidden. The authenticated user cannot access this resource.
- `404` — Not found. The session, encounter, or resource ID does not exist.
- `500` — Internal server error.

---

[API](https://skmtc.dev/suki/apis/suki-developer-platform.md) · [All operations](https://skmtc.dev/suki/apis/suki-developer-platform/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/suki/suki-developer-platform/revisions/5f420a18fb68/schema)