Skip to main content
POST
/
api
/
v1
/
ambient
/
session
/
{ambient_session_id}
/
context
cURL
curl --request POST \
  --url https://sdp.suki.ai/api/v1/ambient/session/<ambient_session_id>/context \
  --header 'Content-Type: application/json' \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>' \
  --data '{
  "diagnoses": {
    "values": [
      {
        "codes": [
          {
            "code": "30422",
            "description": "Essential hypertension",
            "type": "IMO"
          }
        ],
        "diagnosis_note": "Hypertension"
      }
    ]
  },
  "emr": {
    "target_emr": "ATHENA"
  },
  "form_filling": {
    "values": [
      {
        "form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0"
      }
    ]
  },
  "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"
  }
}'
This response has no body data.
Updated:You can now provide EMR context and medication orders in the ambient session context.
Use this endpoint to provide or update the for an . Providing detailed context helps Suki generate a more accurate and relevant . For example, you can provide:
  • details (e.g., specialty and role).
  • Patient and visit information.
  • A list of codes for the clinical sections you want to generate.
  • Existing 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 and Specialty section. For more information about medication orders, refer to the Medication orders guide.
You can 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

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_suki_token>",
    "sdp_provider_id": "<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())

Headers

​
sdp_suki_token
string
required

sdp_suki_token

​
sdp_provider_id
string

Unique identifier for the provider. Optional for standard partners. Required for Single Auth Token authentication, where multiple providers share the same partner_token.

Example:

"provider-123"

Path Parameters

​
ambient_session_id
string
required

ambient_session_id

Body

application/json

Context

​
diagnoses
object

Optional - Information about the diagnoses

​
emr
object

Optional - Information about EMR context

​
form_filling
object

Optional - Information about form-filling context

​
orders
object

Optional - Information about orders context

​
patient
object

Optional - Information about the patient

​
provider
object

Optional - Information about the provider

​
sections
object[]

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

​
visit
object

Optional - Information about the visit

Response

Last modified on June 12, 2026