Skip to main content
POST
cURL
Updated:
  • You can now send Embedded Form templates and prior section text on each section with sections[].precharted_content. Read more in Embedded Forms.
  • You can now provide EMR context and Medication orders details in the Ambient Session Context API.
Use this endpoint to provide or update the for an . Context such as specialty, note sections, diagnoses, EMR details, and Medication orders helps Suki generate a more accurate and relevant .
Send the full visit context with this POST after you create the session, and finish before you end the session. POST replaces the entire context. To change only some fields later, use Update ambient session context API.
For what to send and when, refer to Provide visit context guide.

​
What you can send

  • details (e.g., specialty and role).
  • Patient and visit information.
  • A list of codes for the clinical sections you want to generate. If you omit sections, Suki uses the Default 13 LOINC sections.
  • Existing with their associated medical codes.
  • EMR context, including target EMR, when you need EMR-specific behavior (for example order submission rules).
  • Medication orders, including structured medication orders for active medications and related metadata.
  • Prior section text and Embedded Form templates on each section through sections[].precharted_content.
For more information about the context, refer to the PBC and Specialty section. For more information about Medication orders, refer to the Medication orders guide.
Use the Codes section to provide additional context for a session, such as medical codes for a diagnosis.
  • Do not include HCC codes or note personalization fields such as verbosity and section_format in session context.
  • HCC codes are output-only and are returned in structured note data. Configure note personalization through User preferences. Refer to Diagnosis codes for HCC code handling and Note Personalization guide for personalization best practices.
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.

​
Precharted content and Embedded Forms

Each item in sections can carry a precharted_content list. Send type: "string" with text for prior section text, or type: "structured" with template_id and fields for an Embedded Form template.
Send Embedded Form templates after you create the session and finish seed or update context before you end the session. You can seed or update after streaming has started, including just before you end. For field rules and a full example, refer to Seed and read Embedded Forms.

​
Code examples

Authorizations

​
sdp_suki_token
string
header
required

Suki access token (suki_token) from Login or Register. Expires after one hour.

Headers

​
sdp_provider_id
string

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

"provider-123"

Path Parameters

​
ambient_session_id
string
required

UUID for the ambient session. Use the ambient_session_id returned from Create Ambient Session, or the UUID you supplied in that request.

Body

application/json

Clinical context for the ambient session, including provider, patient, visit, sections, diagnoses, EMR, and medication orders.

​
diagnoses
object

Optional - Existing diagnoses and coded values to include in note generation.

​
emr
object

Optional - EMR context, including the target EMR system.

​
orders
object

Optional - Medication orders and related order context.

​
patient
object

Optional - Patient demographics such as date of birth and sex.

​
provider
object

Optional - Provider role and specialty for the session.

​
sections
object[]

Optional - Information about the sections to be generated. If not provided, all supported note-sections will be generated.

​
visit
object

Optional - Visit details such as chief complaint and encounter type.

Response

Request succeeded.

Last modified on October 26, 2026