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

# Seed ambient session context

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

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.

## Path parameters

- `ambient_session_id` string, required

## Headers

- `sdp_provider_id` string

## Request body

- 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.

## Response `200`

Request succeeded.

## 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)