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",
  "note_id": "123dfg-456dfg-789dfg-012dfg"
}

Updated

• The create response now returns note_id. Use it with note-level Ambient APIs and store it for later re-ambient workflows. composition_id is deprecated and supports backward compatibility.

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.

This endpoint returns an ambient_session_id and a note_id.

Use ambient_session_id for session-scoped operations such as context, streaming, status, and session content.

Store note_id from the response. Pass it as the path parameter when you call the note-level Ambient APIs:

Get Note Content

Get Note Context

Get Note Structured Data

composition_id is deprecated. If you still use it, it will return the same value as note_id.

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

For guidance on how to design your ambient workflow, ID handling, and fields required for interoperability, refer to Create an ambient session guide.

Request body fields

All request body fields are optional. You can create with an empty body; Suki generates ambient_session_id and returns note_id.

Use the fields below only when you need to set the session ID yourself, link the visit for interoperability, or group re-ambient sessions on one note.

Field	Type	Details
ambient_session_id	string (UUID or non-UUID, at most 36 characters)	Session ID (Ambient APIs). Optional. If omitted, Suki generates it and returns it in the response.
emr_encounter_id	string (UUID or non-UUID, at most 36 characters)	EMR Encounter ID. Links the session to a patient visit for cross-modality ambient workflows.
encounter_id	string (at most 255 characters)	Encounter ID. Groups sessions on the same clinical note for re-ambient. Pass on the first create and reuse later, or pass the returned note_id as this value if the first create omitted it. Not returned in the create response. There is no separate note_id request field. See How re-ambient works.

How re-ambient works

Re-ambient lets you create a new ambient session that continues an existing clinical note instead of creating a new note.

When you create an ambient session, Suki returns a note_id in the response. Save this note_id for note-level Ambient APIs and for re-ambient when the first create did not send encounter_id.

Choose the identifier for re-ambient

Create ambient session does not have a separate note_id request field for re-ambient. Instead, pass the re-ambient identifier in the encounter_id field.

Use the identifier based on how you created the original ambient session:

Create ambient session request	Value to pass in encounter_id
Included encounter_id	Use the same encounter_id value.
Did not include encounter_id	Use the note_id returned when the session was created.

• When you create the re-ambient request, use encounter_id, but the value depends on whether the original create ambient session request included an encounter_id.
• Also save the returned note_id: it identifies the clinical note and is the path parameter for note-level Ambient APIs.

• Record for at least 1 minute. Shorter recordings may not contain enough information, and Suki may skip note generation.
• To continue the same note across modalities, reuse the existing emr_encounter_id on create (UUID or non-UUID, at most 36 characters).
• Wait at least 1 second between create requests that share the same emr_encounter_id. Concurrent or back-to-back creates may 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.
# Create body fields on this endpoint: ambient_session_id, emr_encounter_id, encounter_id only.
# Pass emr_encounter_id for cross-modality Ambient interoperability.
ambient_session_id = None  # Optional UUID for this Ambient session
emr_encounter_id = None  # EMR encounter id (UUID or non-UUID, at most 36 characters)
encounter_id = None  # Optional; reuse later for re-ambient

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"]
    note_id = response_body["note_id"]

    print("ambient_session_id:", created_ambient_session_id)
    print("note_id:", note_id)
    print(
        "Use ambient_session_id for session APIs "
        "(context, stream, status, session content)."
    )
    print(
        "Use 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.
// Create body fields on this endpoint: ambient_session_id, emr_encounter_id, encounter_id only.
// 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; // EMR encounter id (UUID or non-UUID, at most 36 characters)
const encounterId: string | undefined = undefined; // Optional; reuse later for re-ambient

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

type CreateAmbientSessionResponse = {
  ambient_session_id: string;
  note_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("note_id:", session.note_id);
  console.log(
    "Use ambient_session_id for session APIs (context, stream, status, session content)."
  );
  console.log(
    "Use 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 for cross-modality interoperability and encounter_id to group re-ambient sessions for one note. If the first create omitted encounter_id, pass the returned note_id as the encounter_id value on later creates.

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 - Visit interop key for interoperability. Accepts a UUID or non-UUID value, at most 36 characters. One EMR encounter can contain multiple notes. Required for cross-modality Ambient workflows.

Maximum string length: 36

Example:

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

encounter_id · string

Optional - Groups re-ambient sessions for one note. Pass it on the first session and reuse the same value on later creates. If the first create omitted it, pass the returned note_id as this field's value for re-ambient. There is no separate note_id request field. Up to 255 characters. Create does not return this field.

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"

note_id · string

ID of the clinical note for this session. Use it as the note_id path parameter on note-level Ambient APIs (note content, note context, note structured data). If the first create omitted encounter_id, pass this value as the encounter_id field on later creates to re-ambient the same note.

Example:

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

composition_id · string · deprecated

Deprecated. Same value as note_id. Kept for backward compatibility. Prefer note_id.