Update Ambient Session Context

Update existing session context with new clinical information

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

cURL

cURL

curl --request PATCH \
  --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"
  },
  "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"
  }
}'

200

{
  "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"
    }
  }
}

Updated:

You can now update the ambient session context with new EMR context and Medication orders. Read more in 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.

• Use PATCH when updating context for an existing Ambient session and POST when adding session context through the seed flow. For guidance on choosing the right operation in your UI, see Update ambient session context.

For guidance on what to include and exclude when seeding session context, refer to Seed ambient session context guide.

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. Those fields replace previous values. They do not append

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

Partial ambient session context update. Include only the fields you want to add or change.

diagnoses · object

Optional - Diagnoses to add or update.

Show child attributes

emr · object

Optional - EMR context to add or update.

Show child attributes

orders · object

Optional - Medication orders to add or update.

Show child attributes

patient · object

Optional - Patient demographics to add or update.

Show child attributes

provider · object

Optional - Provider details to add or update.

Show child attributes

sections · object[]

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

Show child attributes

visit · object

Optional - Visit details to add or update.

Show child attributes

Response

200

application/json

Request succeeded.

Updated ambient session context after a successful PATCH.

context · object

Updated context for the session

Show child attributes