Create Ambient Session

Initialize a new Ambient session for patient encounter documentation

POST /api/v1/ambient/session/create

cURL

cURL

curl --request POST \
  --url https://sdp.suki.ai/api/v1/ambient/session/create \
  --header 'Content-Type: application/json' \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>' \
  --data '{
  "ambient_session_id": "123dfg-456dfg-789dfg-012dfg",
  "encounter_id": "123dfg-456dfg-789dfg-012dfg"
}'

201

{
  "ambient_session_id": "123dfg-456dfg-789dfg-012dfg",
  "composition_id": "123dfg-456dfg-789dfg-012dfg"
}

Updated

• Pass emr_encounter_id to enable cross-modality ambient interoperability.
• The response now includes composition_id. Use it as note_id with the note-level Ambient APIs.
• The multilingual parameter is deprecated. Multilingual support is enabled by default for all ambient sessions.

Use this endpoint to create an ambient session. An ambient session is one recording for a patient encounter (visit). One encounter can include one or more ambient sessions.

Suki returns an ambient_session_id and a composition_id. Use ambient_session_id for session-scoped operations such as context, streaming, status, and session content.

Store the composition_id from the response. You will pass this value as the note_id when you call the following note-level Ambient APIs:

Get Note Content

Get Note Context

Get Note Structured Data

To learn how to use ambient across modalities, refer to the Ambient interoperability guide.

For Start Ambient UI guidance, ID handling, and fields required for interoperability, refer to Create an ambient session guide.

Request body fields

You can create an ambient session with an empty request body. Suki generates ambient_session_id and returns composition_id.

Add a field when you need to control how the session is identified or grouped:

• ambient_session_id: Supply your own session UUID.
• emr_encounter_id: Tie the note to a patient visit for cross-modality interoperability.
• encounter_id: Group re-ambient sessions on one note. Pass it on the first session, reuse the same value on later sessions, and store it locally. Create does not return this field.

All fields are optional when creating a standalone ambient session.

Field	Type	Details
ambient_session_id	string (UUID)	Session ID (Ambient APIs). If omitted, Suki generates the ID and returns it in the response.
emr_encounter_id	string (UUID)	EMR Encounter ID. Links the ambient session to the patient visit. Must be a UUID.
encounter_id	string	Encounter ID. Groups sessions for the same clinical note. Pass on the first session and reuse on re-ambient sessions. Maximum 255 characters. The create response does not return this field.

Important:

• We recommend that recordings are at least 1 minute long. Short recordings may not contain enough information for note generation.
• If the recording is too short, note generation may be skipped.
• For interoperable workflows, pass a valid UUID for emr_encounter_id.
• To continue a note on another modality, pass the existing emr_encounter_id.
• Do not create sessions for the same emr_encounter_id at the same time. Wait at least 1 second between create requests for that encounter. Faster back-to-back creates can return a conflict.

Code examples

Python

import json
import requests

BASE_URL = "https://sdp.suki.ai"
CREATE_SESSION_URL = f"{BASE_URL}/api/v1/ambient/session/create"

# Get sdp_suki_token from Login: POST /api/v1/auth/login
sdp_suki_token = "<sdp_suki_token>"

# Required for single_auth partners
sdp_provider_id = "<sdp_provider_id>"

# Set these from your system. Omit a field by leaving the value as None.
# All request body fields are optional. Suki generates values you omit.
# Pass emr_encounter_id for cross-modality Ambient interoperability.
ambient_session_id = None  # Optional UUID for this Ambient session
emr_encounter_id = None  # UUID for your EMR encounter
encounter_id = None  # Required for re-ambient workflows

headers = {
    "sdp_suki_token": sdp_suki_token,
    "sdp_provider_id": sdp_provider_id,
    "Content-Type": "application/json",
}

payload = {}
if ambient_session_id:
    payload["ambient_session_id"] = ambient_session_id
if emr_encounter_id:
    payload["emr_encounter_id"] = emr_encounter_id
if encounter_id:
    payload["encounter_id"] = encounter_id

response = requests.post(
    CREATE_SESSION_URL,
    headers=headers,
    json=payload,
    timeout=60,
)

print("HTTP status:", response.status_code)

try:
    response_body = response.json()
except ValueError:
    print("Response was not JSON:")
    print(response.text)
    raise SystemExit(1)

print("Response body:")
print(json.dumps(response_body, indent=2))

if response.status_code == 201:
    created_ambient_session_id = response_body["ambient_session_id"]
    composition_id = response_body["composition_id"]

    print("ambient_session_id:", created_ambient_session_id)
    print("composition_id:", composition_id)
    print(
        "Use ambient_session_id for session APIs "
        "(context, stream, status, session content)."
    )
    print(
        "Use composition_id as note_id for note-level Ambient APIs "
        "(note content, note context, note structured data)."
    )
else:
    print("Create Ambient session failed.")
    if isinstance(response_body, dict):
        print("code:", response_body.get("code"))
        print("message:", response_body.get("message"))

TypeScript

const BASE_URL = "https://sdp.suki.ai";
const CREATE_SESSION_URL = `${BASE_URL}/api/v1/ambient/session/create`;

// Get sdp_suki_token from Login: POST /api/v1/auth/login
const sdpSukiToken = "<sdp_suki_token>";

// Required for single_auth partners
const sdpProviderId = "<sdp_provider_id>";

// Set these from your system. Omit a field by leaving the value undefined.
// All request body fields are optional. Suki generates values you omit.
// Pass emr_encounter_id for cross-modality Ambient interoperability.
const ambientSessionId: string | undefined = undefined; // Optional UUID for this Ambient session
const emrEncounterId: string | undefined = undefined; // UUID for your EMR encounter
const encounterId: string | undefined = undefined; // Required for re-ambient workflows

type CreateAmbientSessionRequest = {
  ambient_session_id?: string;
  emr_encounter_id?: string;
  encounter_id?: string;
};

type CreateAmbientSessionResponse = {
  ambient_session_id: string;
  composition_id: string;
};

type ApiErrorResponse = {
  code?: number;
  message?: string;
};

const payload: CreateAmbientSessionRequest = {};
if (ambientSessionId) {
  payload.ambient_session_id = ambientSessionId;
}
if (emrEncounterId) {
  payload.emr_encounter_id = emrEncounterId;
}
if (encounterId) {
  payload.encounter_id = encounterId;
}

const response = await fetch(CREATE_SESSION_URL, {
  method: "POST",
  headers: {
    sdp_suki_token: sdpSukiToken,
    sdp_provider_id: sdpProviderId,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

const responseText = await response.text();
let responseBody: CreateAmbientSessionResponse | ApiErrorResponse | unknown;

try {
  responseBody = responseText ? JSON.parse(responseText) : {};
} catch {
  console.error("Response was not JSON:");
  console.error(responseText);
  throw new Error("Create Ambient session returned non-JSON response");
}

console.log("HTTP status:", response.status);
console.log("Response body:", JSON.stringify(responseBody, null, 2));

if (response.status === 201) {
  const session = responseBody as CreateAmbientSessionResponse;
  console.log("ambient_session_id:", session.ambient_session_id);
  console.log("composition_id:", session.composition_id);
  console.log(
    "Use ambient_session_id for session APIs (context, stream, status, session content)."
  );
  console.log(
    "Use composition_id as note_id for note-level Ambient APIs (note content, note context, note structured data)."
  );
} else {
  const error = responseBody as ApiErrorResponse;
  console.error("Create Ambient session failed.");
  console.error("code:", error.code);
  console.error("message:", error.message);
}

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"

Body

application/json

Session identifiers for Ambient session create. Pass emr_encounter_id to enable cross-modality interoperability and encounter_id for re-ambient workflows.

ambient_session_id · string

Optional - UUID for this Ambient session. Suki generates one when omitted and returns it in the response.

Example:

"123dfg-456dfg-789dfg-012dfg"

emr_encounter_id · string

Optional for standalone sessions - UUID for your EMR or EHR visit. One EMR encounter can contain multiple notes. Required for cross-modality Ambient workflows.

Example:

"123dfg-456dfg-789dfg-012dfg"

encounter_id · string

Required for re-ambient workflows - Groups re-ambient sessions for one note. Reuse the same value for every re-ambient session on that note. Up to 255 characters. If omitted on the first session, Suki generates one.

Example:

"123dfg-456dfg-789dfg-012dfg"

multilingual · boolean · deprecated

Deprecated. Multilingual support is enabled by default for all Ambient sessions.

Example:

false

Response

201

application/json

Resource created successfully.

Identifiers returned after Ambient session create.

ambient_session_id · string

UUID for the created Ambient session. Store this for later session API calls.

Example:

"123dfg-456dfg-789dfg-012dfg"

composition_id · string

ID of the note for this session. Pass this value as note_id when you call the note-level Ambient APIs.

Example:

"123dfg-456dfg-789dfg-012dfg"