Create Ambient Session

POST

api

ambient

session

create

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

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

UpdatedThe multilingual parameter is deprecated.Multilingual support is now enabled by default for all ambient sessions. You no longer need to pass this parameter. The API automatically supports conversations in multiple languages and generates the in English.

Use this endpoint to create an . Suki will generate an ambient_session_id and return it in the response. Use the ambient_session_id to identify the in future API calls. Many Suki APIs use this ID to perform operations such as checking session status, generating notes, retrieving transcripts, and other operations. Store the ambient_session_id after you create a session, as it is required for most session-related operations.

Request body fields

Both fields in the request body are optional. Suki generates any values you omit.

Field	Type	Description
`ambient_session_id`	string (UUID)	Unique identifier for this ambient session. Must be a string in UUID format. If omitted, Suki generates one and returns it in the response.
`encounter_id`	string (UUID)	Unique identifier for the patient encounter (visit). Must be a string in UUID format. Use the same `encounter_id` across multiple `session/create` calls to group several ambient sessions under the same visit. If omitted, Suki generates one.

encounter_id must be a string in UUID format. Numeric IDs from your system must be converted to a string (for example, String(id)) before you send them.

We recommend that recordings are at least 1 minute long. Short recordings may not contain enough information for note generation.

Important:If the recording is too short, note generation may be skipped.

Code examples

Python
TypeScript

from typing import Any, Optional, TypedDict, cast

import requests

BASE_URL = "https://sdp.suki-stage.com"


class CreateAmbientSessionRequest(TypedDict, total=False):
    ambient_session_id: str
    encounter_id: str


class CreateAmbientSessionResponse(TypedDict):
    ambient_session_id: str


class ApiHttpError(RuntimeError):
    """Wrong HTTP status; OpenAPI errors usually include JSON with message + code."""

    def __init__(self, status: int, url: str, detail: str) -> None:
        super().__init__(f"HTTP {status} {url}: {detail}")
        self.status = status
        self.url = url


def _post_json_expect(url: str, headers: dict[str, str], payload: dict[str, Any], expect_status: int) -> dict[str, Any]:
    r = requests.post(url, json=payload, headers=headers, timeout=60)
    if r.status_code == expect_status:
        data = r.json()
        if isinstance(data, dict):
            return data
        raise ApiHttpError(expect_status, url, "response JSON was not an object")

    detail = ""
    try:
        err = r.json()
        if isinstance(err, dict) and isinstance(err.get("message"), str):
            detail = err["message"]
    except ValueError:
        detail = (r.text or "")[:500]
    raise ApiHttpError(r.status_code, url, detail or "(no body)")


def create_ambient_session(
    suki_token: str,
    body: Optional[CreateAmbientSessionRequest] = None,
) -> CreateAmbientSessionResponse:
    """POST /api/v1/ambient/session/create (sdp_suki_token header required). HTTP 201."""
    url = f"{BASE_URL}/api/v1/ambient/session/create"
    headers = {"sdp_suki_token": suki_token, "sdp_provider_id": "<sdp_provider_id>", "Content-Type": "application/json"}
    data = _post_json_expect(url, headers, dict(body or {}), 201)
    sid = data.get("ambient_session_id")
    if not isinstance(sid, str) or not sid:
        raise ValueError(f"{url}: 201 response missing ambient_session_id")
    return cast(CreateAmbientSessionResponse, {"ambient_session_id": sid})


if __name__ == "__main__":
    try:
        session = create_ambient_session(
            "<sdp_suki_token>",
            {
                # Optional UUIDs; omit to let Suki generate.
                "ambient_session_id": "123dfg-456dfg-789dfg-012dfg",
                "encounter_id": "123dfg-456dfg-789dfg-012dfg",
            },
        )
        print(session["ambient_session_id"])
    except (ApiHttpError, ValueError) as e:
        print(e)

const BASE_URL = "https://sdp.suki-stage.com";

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

type CreateAmbientSessionResponse = { ambient_session_id: string };

class ApiHttpError extends Error {
  status: number;
  url: string;
  constructor(status: number, url: string, detail: string) {
    super(`HTTP ${status} ${url}: ${detail}`);
    this.status = status;
    this.url = url;
  }
}

async function postJsonExpectObject(
  url: string,
  headers: Record<string, string>,
  body: Record<string, unknown>,
  expectStatus: number
): Promise<Record<string, unknown>> {
  const res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
  const text = await res.text();
  const json = text ? JSON.parse(text) : {};

  if (res.status !== expectStatus) {
    const msg = typeof (json as any)?.message === "string" ? (json as any).message : text?.slice(0, 500) || "(no body)";
    throw new ApiHttpError(res.status, url, msg);
  }
  if (json && typeof json === "object" && !Array.isArray(json)) return json as Record<string, unknown>;
  throw new ApiHttpError(res.status, url, "response JSON was not an object");
}

export async function createAmbientSession(
  sdpSukiToken: string,
  body: CreateAmbientSessionRequest = {}
): Promise<CreateAmbientSessionResponse> {
  const url = `${BASE_URL}/api/v1/ambient/session/create`;
  const data = await postJsonExpectObject(
    url,
    { sdp_suki_token: sdpSukiToken, sdp_provider_id: "<sdp_provider_id>", "Content-Type": "application/json" },
    body as Record<string, unknown>,
    201
  );
  const ambientSessionId = data.ambient_session_id;
  if (typeof ambientSessionId !== "string" || !ambientSessionId) {
    throw new Error(`${url}: 201 response missing ambient_session_id`);
  }
  return { ambient_session_id: ambientSessionId };
}

// Example usage
const session = await createAmbientSession("<sdp_suki_token>", {
  // Optional UUIDs; omit to let Suki generate.
  ambient_session_id: "123dfg-456dfg-789dfg-012dfg",
  encounter_id: "123dfg-456dfg-789dfg-012dfg",
});
console.log(session.ambient_session_id);

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"

Body

application/json

CreateSessionRequest

Request body for the /session/create endpoint

ambient_session_id

string

Optional - UUID format

Example:

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

encounter_id

string

Optional - UUID format

Example:

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

multilingual

boolean

deprecated

Deprecated. Multilingual support is now true by default. To disable it, contact the Suki support team.

Example:

true

Response

Success Response

Response body for the /session/create endpoint

ambient_session_id

string

Example:

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

Last modified on June 12, 2026

Ambient Session Management API

Seed Ambient Session Context

⌘I

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

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

​Request body fields

​Code examples

Headers

Body

Response

Request body fields

Code examples