Ambient API Quickstart

This quickstart walks you through one successful Ambient workflow on staging environment. You will authenticate, create a session, stream visit audio, end the session, and retrieve the clinical note. Rely on a webhook when processing finishes to handle notifications instead of polling. Your application owns session controls, audio streaming, status handling, note review, and EHR handoff. For product context and when to choose Ambient APIs versus Ambient SDKs, refer to Ambient clinical documentation. What you will do

Authenticate to get an sdp_suki_token (and register the user if needed).
Create an ambient session and optionally seed context for better notes. An ambient session is one recording for a patient visit (encounter). One encounter can include more than one session.
Stream audio over the WebSocket, send control events, and end the ambient session when that recording is finished.
Retrieve the clinical note and transcript, or rely on a webhook when processing finishes.

Prefer one paste-ready file? Use the Complete staging script in the preferred language below, then follow the numbered steps for the same flow with full explanations.

Using an AI coding tool?Copy the prompt below to point your agent at the Ambient skill and Documentation MCP. For every task skill, refer to AI coding tools.

Fetch the Ambient skill and connect the documentation MCP.

Open in Cursor

Access and credentials

You need partner credentials to use the Suki Ambient APIs. Contact our Partnership team to get your credentials. They will guide you through the Onboarding process and provide what you need to get started.

Prerequisites

To use the Suki Ambient APIs, you must have the following:

An OAuth-compliant authentication system.
JWT tokens with consistent user identifiers.
A publicly accessible endpoint (or Okta authorization server) for token validation.

Environments to use for development and testing

This guide uses https://sdp.suki-stage.com and wss://sdp.suki-stage.com for API and WebSocket examples (staging).

Important:

The production environment is https://sdp.suki.ai and wss://sdp.suki.ai.
The staging environment is https://sdp.suki-stage.com and wss://sdp.suki-stage.com.
Your partnership team will confirm which environment, base URL, and credentials apply for your integration.

Complete staging script

Replace the credential placeholders, put a 16 kHz mono LINEAR16 WAV (or raw PCM) at audio.wav, then run. For detailed explanations of each step, refer to the numbered steps below.

Python: pip install requests websocket-client then python ambient_staging.py.
TypeScript (Node): npm install ws then npx tsx ambient_staging.ts (Node 18+).

Ambient sessions must be at least 1 minute of audio for note generation. Shorter sessions can return status skipped with no note. Use a WAV or raw LINEAR16 PCM file that is long enough when you test.

# ambient_staging.py
# Flow: login (register once if needed) → create → context → stream → end → poll content
# pip install requests websocket-client

import base64
import json
import time
from datetime import datetime, timezone
from typing import Any, Optional

import requests
import websocket

BASE_URL = "https://sdp.suki-stage.com"
WS_URL = "wss://sdp.suki-stage.com/ws/stream"
CHUNK_BYTES = 3200  # ~100 ms of 16 kHz mono 16-bit PCM
WAV_HEADER_BYTES = 44

# Replace these with your partner credentials
PARTNER_ID = "your-partner-id"
PARTNER_TOKEN = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."  # Keep on your backend only
PROVIDER_ID = "provider-123"  # Optional; required for Bearer / Single Auth Token partners
SDP_PROVIDER_ID = ""  # Leave empty unless your partnership requires sdp_provider_id
AUDIO_PATH = "audio.wav"  # 16 kHz mono LINEAR16 WAV or raw PCM


def b64(data: bytes) -> str:
    return base64.b64encode(data).decode("ascii")


def rest_headers(suki_token: str) -> dict[str, str]:
    headers = {
        "sdp_suki_token": suki_token,
        "Content-Type": "application/json",
    }
    if SDP_PROVIDER_ID:
        headers["sdp_provider_id"] = SDP_PROVIDER_ID
    return headers


def expect_status(response: requests.Response, url: str, want: int) -> None:
    if response.status_code == want:
        return
    detail = (response.text or "")[:500]
    try:
        body = response.json()
        if isinstance(body, dict) and body.get("message"):
            detail = str(body["message"])
    except ValueError:
        pass
    raise RuntimeError(f"HTTP {response.status_code} {url}: {detail}")


def login(partner_id: str, partner_token: str, provider_id: Optional[str] = None) -> str:
    url = f"{BASE_URL}/api/v1/auth/login"
    payload: dict[str, Any] = {"partner_id": partner_id, "partner_token": partner_token}
    if provider_id:
        payload["provider_id"] = provider_id
    r = requests.post(url, json=payload, timeout=60)
    expect_status(r, url, 200)
    token = r.json().get("suki_token")
    if not token:
        raise RuntimeError("login response missing suki_token")
    return token


def register_provider(
    partner_id: str,
    partner_token: str,
    provider_name: str,
    provider_org_id: str,
    provider_id: Optional[str] = None,
) -> None:
    url = f"{BASE_URL}/api/v1/auth/register"
    payload: dict[str, Any] = {
        "partner_id": partner_id,
        "partner_token": partner_token,
        "provider_name": provider_name,
        "provider_org_id": provider_org_id,
    }
    if provider_id:
        payload["provider_id"] = provider_id
    r = requests.post(url, json=payload, timeout=60)
    # New link: 201. Already linked: 409. Both are success for this flow.
    if r.status_code not in (201, 409):
        expect_status(r, url, 201)


def login_with_register_fallback(
    partner_id: str,
    partner_token: str,
    provider_id: Optional[str],
    provider_name: str,
    provider_org_id: str,
) -> str:
    try:
        return login(partner_id, partner_token, provider_id)
    except RuntimeError as err:
        if "provider_not_registered" not in str(err):
            raise
        register_provider(
            partner_id, partner_token, provider_name, provider_org_id, provider_id
        )
        return login(partner_id, partner_token, provider_id)


def create_ambient_session(suki_token: str, body: Optional[dict[str, str]] = None) -> dict[str, str]:
    url = f"{BASE_URL}/api/v1/ambient/session/create"
    r = requests.post(url, headers=rest_headers(suki_token), json=body or {}, timeout=60)
    expect_status(r, url, 201)
    data = r.json()
    sid = data.get("ambient_session_id")
    composition_id = data.get("composition_id")
    if not sid:
        raise RuntimeError("create response missing ambient_session_id")
    return {
        "ambient_session_id": sid,
        "composition_id": composition_id or "",
    }


def seed_context(suki_token: str, ambient_session_id: str) -> None:
    url = f"{BASE_URL}/api/v1/ambient/session/{ambient_session_id}/context"
    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"},
    }
    r = requests.post(url, headers=rest_headers(suki_token), json=payload, timeout=60)
    expect_status(r, url, 200)


def strip_wav_header(raw: bytes) -> bytes:
    if len(raw) >= 12 and raw[:4] == b"RIFF" and raw[8:12] == b"WAVE":
        return raw[WAV_HEADER_BYTES:]
    return raw


def stream_pcm_file(suki_token: str, ambient_session_id: str, path: str) -> None:
    header = [
        f"sdp_suki_token: {suki_token}",
        f"ambient_session_id: {ambient_session_id}",
    ]
    if SDP_PROVIDER_ID:
        header.append(f"sdp_provider_id: {SDP_PROVIDER_ID}")

    ws = websocket.create_connection(WS_URL, header=header, timeout=60)
    try:
        rfc3339 = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
        ws.send(json.dumps({"type": "START_TIME", "data": b64(rfc3339.encode("utf-8"))}))

        with open(path, "rb") as f:
            pcm = strip_wav_header(f.read())

        for i in range(0, len(pcm), CHUNK_BYTES):
            ws.send(json.dumps({"type": "AUDIO", "data": b64(pcm[i : i + CHUNK_BYTES])}))

        # End marker: Base64 of ASCII bytes EOF (literal RU9G)
        ws.send(json.dumps({"type": "AUDIO", "data": "RU9G"}))
    finally:
        ws.close()


def end_ambient_session(suki_token: str, ambient_session_id: str) -> None:
    url = f"{BASE_URL}/api/v1/ambient/session/{ambient_session_id}/end"
    r = requests.post(url, headers=rest_headers(suki_token), timeout=60)
    expect_status(r, url, 200)


def get_status(suki_token: str, ambient_session_id: str) -> str:
    url = f"{BASE_URL}/api/v1/ambient/session/{ambient_session_id}/status"
    r = requests.get(url, headers=rest_headers(suki_token), timeout=60)
    expect_status(r, url, 200)
    return r.json()["status"]


def get_content(suki_token: str, ambient_session_id: str) -> Any:
    url = f"{BASE_URL}/api/v1/ambient/session/{ambient_session_id}/content"
    r = requests.get(
        url,
        headers=rest_headers(suki_token),
        params={"cumulative": "false"},
        timeout=60,
    )
    expect_status(r, url, 200)
    return r.json()


def wait_for_content(suki_token: str, ambient_session_id: str, poll_sec: float = 2.0) -> dict[str, Any]:
    while True:
        status = get_status(suki_token, ambient_session_id)
        print("status:", status)
        if status == "completed":
            return {"status": status, "content": get_content(suki_token, ambient_session_id)}
        if status in ("failed", "skipped", "aborted"):
            return {"status": status, "content": None}
        time.sleep(poll_sec)


if __name__ == "__main__":
    suki_token = login_with_register_fallback(
        PARTNER_ID,
        PARTNER_TOKEN,
        PROVIDER_ID,
        provider_name="Dr. John Smith",
        provider_org_id="org-123",
    )
    print("Authenticated")

    created = create_ambient_session(suki_token, {})
    ambient_session_id = created["ambient_session_id"]
    print("ambient_session_id:", ambient_session_id)
    print("composition_id:", created["composition_id"])

    seed_context(suki_token, ambient_session_id)
    print("Context seeded")

    stream_pcm_file(suki_token, ambient_session_id, AUDIO_PATH)
    print("Stream finished")

    end_ambient_session(suki_token, ambient_session_id)
    print("Session ended")

    result = wait_for_content(suki_token, ambient_session_id)
    print(json.dumps(result, indent=2))

// ambient_staging.ts
// Flow: login (register once if needed) → create → context → stream → end → poll content
// Node 18+: npm install ws && npx tsx ambient_staging.ts

import fs from "node:fs";
import WebSocket from "ws";

const BASE_URL = "https://sdp.suki-stage.com";
const WS_URL = "wss://sdp.suki-stage.com/ws/stream";
const CHUNK_BYTES = 3200; // ~100 ms of 16 kHz mono 16-bit PCM
const WAV_HEADER_BYTES = 44;

// Replace these with your partner credentials
const PARTNER_ID = "your-partner-id";
const PARTNER_TOKEN = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."; // Keep on your backend only
const PROVIDER_ID = "provider-123"; // Optional; required for Bearer / Single Auth Token partners
const SDP_PROVIDER_ID = ""; // Leave empty unless your partnership requires sdp_provider_id
const AUDIO_PATH = "audio.wav"; // 16 kHz mono LINEAR16 WAV or raw PCM

function restHeaders(sukiToken: string): Record<string, string> {
  const headers: Record<string, string> = {
    sdp_suki_token: sukiToken,
    "Content-Type": "application/json",
  };
  if (SDP_PROVIDER_ID) headers.sdp_provider_id = SDP_PROVIDER_ID;
  return headers;
}

async function expectStatus(response: Response, url: string, want: number): Promise<void> {
  if (response.status === want) return;
  const raw = await response.text();
  let detail = raw.slice(0, 500);
  try {
    const body = JSON.parse(raw);
    if (body?.message) detail = String(body.message);
  } catch {
    // keep raw text
  }
  throw new Error(`HTTP ${response.status} ${url}: ${detail}`);
}

async function login(
  partnerId: string,
  partnerToken: string,
  providerId?: string,
): Promise<string> {
  const url = `${BASE_URL}/api/v1/auth/login`;
  const body: Record<string, string> = {
    partner_id: partnerId,
    partner_token: partnerToken,
  };
  if (providerId) body.provider_id = providerId;

  const response = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  await expectStatus(response, url, 200);
  const data = (await response.json()) as { suki_token?: string };
  if (!data.suki_token) throw new Error("login response missing suki_token");
  return data.suki_token;
}

async function registerProvider(input: {
  partnerId: string;
  partnerToken: string;
  providerName: string;
  providerOrgId: string;
  providerId?: string;
}): Promise<void> {
  const url = `${BASE_URL}/api/v1/auth/register`;
  const body: Record<string, string> = {
    partner_id: input.partnerId,
    partner_token: input.partnerToken,
    provider_name: input.providerName,
    provider_org_id: input.providerOrgId,
  };
  if (input.providerId) body.provider_id = input.providerId;

  const response = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  // New link: 201. Already linked: 409. Both are success for this flow.
  if (response.status !== 201 && response.status !== 409) {
    await expectStatus(response, url, 201);
  }
}

async function loginWithRegisterFallback(
  partnerId: string,
  partnerToken: string,
  providerId: string | undefined,
  providerName: string,
  providerOrgId: string,
): Promise<string> {
  try {
    return await login(partnerId, partnerToken, providerId);
  } catch (err) {
    if (!String(err).includes("provider_not_registered")) throw err;
    await registerProvider({
      partnerId,
      partnerToken,
      providerName,
      providerOrgId,
      providerId,
    });
    return login(partnerId, partnerToken, providerId);
  }
}

async function createAmbientSession(
  sukiToken: string,
): Promise<{ ambientSessionId: string; compositionId: string }> {
  const url = `${BASE_URL}/api/v1/ambient/session/create`;
  const response = await fetch(url, {
    method: "POST",
    headers: restHeaders(sukiToken),
    body: JSON.stringify({}),
  });
  await expectStatus(response, url, 201);
  const data = (await response.json()) as {
    ambient_session_id?: string;
    composition_id?: string;
  };
  if (!data.ambient_session_id) {
    throw new Error("create response missing ambient_session_id");
  }
  return {
    ambientSessionId: data.ambient_session_id,
    compositionId: data.composition_id ?? "",
  };
}

async function seedContext(sukiToken: string, ambientSessionId: string): Promise<void> {
  const url = `${BASE_URL}/api/v1/ambient/session/${ambientSessionId}/context`;
  const response = await fetch(url, {
    method: "POST",
    headers: restHeaders(sukiToken),
    body: JSON.stringify({
      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" },
    }),
  });
  await expectStatus(response, url, 200);
}

function stripWavHeader(buf: Buffer): Buffer {
  if (
    buf.length >= 12 &&
    buf.subarray(0, 4).toString("ascii") === "RIFF" &&
    buf.subarray(8, 12).toString("ascii") === "WAVE"
  ) {
    return buf.subarray(WAV_HEADER_BYTES);
  }
  return buf;
}

function streamPcmFile(
  sukiToken: string,
  ambientSessionId: string,
  path: string,
): Promise<void> {
  return new Promise((resolve, reject) => {
    const headers: Record<string, string> = {
      sdp_suki_token: sukiToken,
      ambient_session_id: ambientSessionId,
    };
    if (SDP_PROVIDER_ID) headers.sdp_provider_id = SDP_PROVIDER_ID;

    const ws = new WebSocket(WS_URL, { headers });

    ws.on("open", () => {
      try {
        const rfc3339 = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
        ws.send(
          JSON.stringify({
            type: "START_TIME",
            data: Buffer.from(rfc3339, "utf8").toString("base64"),
          }),
        );

        const pcm = stripWavHeader(fs.readFileSync(path));
        for (let i = 0; i < pcm.length; i += CHUNK_BYTES) {
          ws.send(
            JSON.stringify({
              type: "AUDIO",
              data: pcm.subarray(i, i + CHUNK_BYTES).toString("base64"),
            }),
          );
        }
        // End marker: Base64 of ASCII bytes EOF
        ws.send(JSON.stringify({ type: "AUDIO", data: "RU9G" }));
        ws.close();
      } catch (err) {
        reject(err);
      }
    });

    ws.on("message", (data) => console.log("ws message:", data.toString()));
    ws.on("error", reject);
    ws.on("close", () => resolve());
  });
}

async function endAmbientSession(sukiToken: string, ambientSessionId: string): Promise<void> {
  const url = `${BASE_URL}/api/v1/ambient/session/${ambientSessionId}/end`;
  const response = await fetch(url, {
    method: "POST",
    headers: restHeaders(sukiToken),
  });
  await expectStatus(response, url, 200);
}

async function getStatus(sukiToken: string, ambientSessionId: string): Promise<string> {
  const url = `${BASE_URL}/api/v1/ambient/session/${ambientSessionId}/status`;
  const response = await fetch(url, { headers: restHeaders(sukiToken) });
  await expectStatus(response, url, 200);
  const data = (await response.json()) as { status: string };
  return data.status;
}

async function getContent(sukiToken: string, ambientSessionId: string): Promise<unknown> {
  const url = `${BASE_URL}/api/v1/ambient/session/${ambientSessionId}/content?cumulative=false`;
  const response = await fetch(url, { headers: restHeaders(sukiToken) });
  await expectStatus(response, url, 200);
  return response.json();
}

async function waitForContent(
  sukiToken: string,
  ambientSessionId: string,
  pollMs = 2000,
): Promise<{ status: string; content: unknown }> {
  for (;;) {
    const status = await getStatus(sukiToken, ambientSessionId);
    console.log("status:", status);
    if (status === "completed") {
      return { status, content: await getContent(sukiToken, ambientSessionId) };
    }
    if (status === "failed" || status === "skipped" || status === "aborted") {
      return { status, content: null };
    }
    await new Promise((r) => setTimeout(r, pollMs));
  }
}

async function main() {
  const sukiToken = await loginWithRegisterFallback(
    PARTNER_ID,
    PARTNER_TOKEN,
    PROVIDER_ID,
    "Dr. John Smith",
    "org-123",
  );
  console.log("Authenticated");

  const created = await createAmbientSession(sukiToken);
  console.log("ambient_session_id:", created.ambientSessionId);
  console.log("composition_id:", created.compositionId);

  await seedContext(sukiToken, created.ambientSessionId);
  console.log("Context seeded");

  await streamPcmFile(sukiToken, created.ambientSessionId, AUDIO_PATH);
  console.log("Stream finished");

  await endAmbientSession(sukiToken, created.ambientSessionId);
  console.log("Session ended");

  const result = await waitForContent(sukiToken, created.ambientSessionId);
  console.log(JSON.stringify(result, null, 2));
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

Create your first Ambient session

Authenticate to get a Suki token

Send a POST request to the Login API endpoint with the following parameters in the request body:

partner_id: Your unique , which we provide to you securely offline.
partner_token: The user’s OAuth 2.0 ID token () from your identity provider.
provider_id (Optional for standard partners; required for some auth flows): Unique identifier for the .

On success the API returns a (suki_token). Include it as the sdp_suki_token header for subsequent API calls.

If the user is not registered, call the Register API first, then retry /login. You only need to register a user once.

Each sample below is self-contained (TypeScript, Python, and cURL). Expect HTTP 200.

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

const response = await fetch(`${BASE_URL}/api/v1/auth/login`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    partner_id: "your-partner-id",
    partner_token: "your-jwt-token",
    provider_id: "provider-123", // Required for Bearer / Single Auth; omit for Standard
  }),
});

const data = await response.json();
if (response.status !== 200) {
  throw new Error(`Login failed: ${response.status} ${JSON.stringify(data)}`);
}
if (!data.suki_token) throw new Error("login response missing suki_token");

const sukiToken = data.suki_token as string;
console.log("suki_token:", sukiToken);

import requests

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

response = requests.post(
    f"{BASE_URL}/api/v1/auth/login",
    headers={"Content-Type": "application/json"},
    json={
        "partner_id": "your-partner-id",
        "partner_token": "your-jwt-token",
        "provider_id": "provider-123",  # Required for Bearer / Single Auth; omit for Standard
    },
    timeout=60,
)
if response.status_code != 200:
    raise RuntimeError(f"Login failed: {response.status_code} {response.text}")

data = response.json()
suki_token = data.get("suki_token")
if not suki_token:
    raise RuntimeError("login response missing suki_token")
print("suki_token:", suki_token)

curl --request POST \
  --url https://sdp.suki-stage.com/api/v1/auth/login \
  --header 'Content-Type: application/json' \
  --data '{
    "partner_id": "your-partner-id",
    "partner_token": "your-jwt-token",
    "provider_id": "provider-123"
  }'

Save the suki_token as it is valid for 1 hour. Request a new token before it expires.

Create an Ambient Session

Send a POST request to Create Ambient Session API. The body can be empty for a first staging session.Optional body fields:

emr_encounter_id (UUID): EMR or EHR visit ID for cross-modality Ambient interoperability.
encounter_id: Required for re-ambient workflows. Alphanumeric string up to 255 characters to group sessions for the same note.
ambient_session_id: Optional UUID v4 to identify the session; Suki generates one if omitted.

Expect HTTP 201 and a response with ambient_session_id and composition_id.

const BASE_URL = "https://sdp.suki-stage.com";
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 from login>";

// 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;
};

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

const headers: Record<string, string> = {
  "Content-Type": "application/json",
  sdp_suki_token: sdpSukiToken,
  sdp_provider_id: sdpProviderId,
};

const createResponse = await fetch(CREATE_SESSION_URL, {
  method: "POST",
  headers,
  body: JSON.stringify(payload),
});

const created = (await createResponse.json()) as CreateAmbientSessionResponse;
if (createResponse.status !== 201) {
  throw new Error(
    `Create failed: ${createResponse.status} ${JSON.stringify(created)}`,
  );
}

console.log("ambient_session_id:", created.ambient_session_id);
console.log("composition_id:", created.composition_id);

import json
import requests

BASE_URL = "https://sdp.suki-stage.com"
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 from login>"

# 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,
)

if response.status_code != 201:
    raise RuntimeError(
        f"Create failed: {response.status_code} {response.text}"
    )

created = response.json()
print(json.dumps(created, indent=2))
print("ambient_session_id:", created["ambient_session_id"])
print("composition_id:", created["composition_id"])

curl --request POST \
  --url https://sdp.suki-stage.com/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": "<ambient_session_id>",
    "emr_encounter_id": "<emr_encounter_id>",
    "encounter_id": "<encounter_id>"
  }'

Save ambient_session_id and composition_id. Use the session ID for streaming and content calls; use composition_id as note_id for note-level APIs.

Seed Context (Optional)

POST to Seed Context API after session creation to provide metadata that improves note quality. Skip this step for the minimum path and add it after your first end-to-end run works.Include fields such as provider, patient, visit, sections, diagnoses, and emr.

const BASE_URL = "https://sdp.suki-stage.com";
const sdpSukiToken = "<sdp_suki_token from login>";
const ambientSessionId = "<ambient_session_id from create>";
const sdpProviderId = "<sdp_provider_id>"; // Required for single_auth partners

const headers: Record<string, string> = {
  "Content-Type": "application/json",
  sdp_suki_token: sdpSukiToken,
  sdp_provider_id: sdpProviderId,
};

const contextResponse = await fetch(
  `${BASE_URL}/api/v1/ambient/session/${ambientSessionId}/context`,
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      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" },
    }),
  },
);

if (contextResponse.status !== 200) {
  const err = await contextResponse.text();
  throw new Error(`Context failed: ${contextResponse.status} ${err}`);
}
console.log("Context seeded");

import requests

BASE_URL = "https://sdp.suki-stage.com"
sdp_suki_token = "<sdp_suki_token from login>"
ambient_session_id = "<ambient_session_id from create>"
sdp_provider_id = "<sdp_provider_id>"  # Required for single_auth partners

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

response = requests.post(
    f"{BASE_URL}/api/v1/ambient/session/{ambient_session_id}/context",
    headers=headers,
    json=payload,
    timeout=60,
)
if response.status_code != 200:
    raise RuntimeError(f"Context failed: {response.status_code} {response.text}")
print("Context seeded")

curl --request POST \
  --url https://sdp.suki-stage.com/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 '{
    "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"
    }
  }'

Stream Audio via WebSocket (WS)

Open a WebSocket to wss://sdp.suki-stage.com/ws/stream after session creation and context. Authenticate using Sec-WebSocket-Protocol (SukiAmbientAuth,<sdp_suki_token>,<ambient_session_id>) for browsers or headers for non-browser clients.Audio requirements:

encoding: LINEAR16.
sample_rate: 16KHz.
channel: Mono.

Strip WAV headers (44 bytes) before chunking. Send 100ms PCM chunks Base64-encoded in AUDIO messages. Required send order: START_TIME, one or more AUDIO messages, then an AUDIO end marker with Base64 of ASCII EOF (RU9G).Supported EVENT values: PAUSE, RESUME, CANCEL, ABORT (deprecated), KEEP_ALIVE. Close the socket when finished, then call the end session endpoint and poll status/content.

Use the Complete staging script for a full streaming client. When capture finishes, close the WebSocket, then call end session.

End session

POST to End Session API to end the session.

const BASE_URL = "https://sdp.suki-stage.com";
const sdpSukiToken = "<sdp_suki_token from login>";
const ambientSessionId = "<ambient_session_id from create>";
const sdpProviderId = "<sdp_provider_id>"; // Required for single_auth partners

const headers: Record<string, string> = {
  sdp_suki_token: sdpSukiToken,
  sdp_provider_id: sdpProviderId,
};

const endResponse = await fetch(
  `${BASE_URL}/api/v1/ambient/session/${ambientSessionId}/end`,
  { method: "POST", headers },
);

if (endResponse.status !== 200) {
  const err = await endResponse.text();
  throw new Error(`End failed: ${endResponse.status} ${err}`);
}
console.log("Session ended");

import requests

BASE_URL = "https://sdp.suki-stage.com"
sdp_suki_token = "<sdp_suki_token from login>"
ambient_session_id = "<ambient_session_id from create>"
sdp_provider_id = "<sdp_provider_id>"  # Required for single_auth partners

headers = {
    "sdp_suki_token": sdp_suki_token,
    "sdp_provider_id": sdp_provider_id,
}

response = requests.post(
    f"{BASE_URL}/api/v1/ambient/session/{ambient_session_id}/end",
    headers=headers,
    timeout=60,
)
if response.status_code != 200:
    raise RuntimeError(f"End failed: {response.status_code} {response.text}")
print("Session ended")

curl --request POST \
  --url https://sdp.suki-stage.com/api/v1/ambient/session/<ambient_session_id>/end \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>'

Retrieve Generated Content

For the minimum path, poll Get Status API until a terminal state such as completed, then retrieve the note with Get Content API.After that works, you can also use a webhook (session_summary_generated) or Get Transcript API.

const BASE_URL = "https://sdp.suki-stage.com";
const sdpSukiToken = "<sdp_suki_token from login>";
const ambientSessionId = "<ambient_session_id from create>";
const sdpProviderId = "<sdp_provider_id>"; // Required for single_auth partners

const headers: Record<string, string> = {
  sdp_suki_token: sdpSukiToken,
  sdp_provider_id: sdpProviderId,
};

const statusResponse = await fetch(
  `${BASE_URL}/api/v1/ambient/session/${ambientSessionId}/status`,
  { headers },
);
const statusBody = await statusResponse.json();
if (statusResponse.status !== 200) {
  throw new Error(
    `Status failed: ${statusResponse.status} ${JSON.stringify(statusBody)}`,
  );
}
console.log("status:", statusBody.status);

const contentResponse = await fetch(
  `${BASE_URL}/api/v1/ambient/session/${ambientSessionId}/content?cumulative=false`,
  { headers },
);
const content = await contentResponse.json();
if (contentResponse.status !== 200) {
  throw new Error(
    `Content failed: ${contentResponse.status} ${JSON.stringify(content)}`,
  );
}
console.log(JSON.stringify(content, null, 2));

import json
import requests

BASE_URL = "https://sdp.suki-stage.com"
sdp_suki_token = "<sdp_suki_token from login>"
ambient_session_id = "<ambient_session_id from create>"
sdp_provider_id = "<sdp_provider_id>"  # Required for single_auth partners

headers = {
    "sdp_suki_token": sdp_suki_token,
    "sdp_provider_id": sdp_provider_id,
}

status_response = requests.get(
    f"{BASE_URL}/api/v1/ambient/session/{ambient_session_id}/status",
    headers=headers,
    timeout=60,
)
if status_response.status_code != 200:
    raise RuntimeError(
        f"Status failed: {status_response.status_code} {status_response.text}"
    )
print("status:", status_response.json()["status"])

content_response = requests.get(
    f"{BASE_URL}/api/v1/ambient/session/{ambient_session_id}/content",
    headers=headers,
    params={"cumulative": "false"},
    timeout=60,
)
if content_response.status_code != 200:
    raise RuntimeError(
        f"Content failed: {content_response.status_code} {content_response.text}"
    )
print(json.dumps(content_response.json(), indent=2))

curl --request GET \
  --url https://sdp.suki-stage.com/api/v1/ambient/session/<ambient_session_id>/status \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>'

curl --request GET \
  --url 'https://sdp.suki-stage.com/api/v1/ambient/session/<ambient_session_id>/content?cumulative=false' \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>'

Verify your integration

Before you design the full production workflow, confirm that your staging integration can complete this minimum path:

Authenticate successfully and use the returned sdp_suki_token in follow-up requests.
Create an ambient session and store the returned ambient_session_id (and composition_id when you need note-level APIs).
Stream visit audio on /ws/stream with the required PCM format and message order.
End the session and confirm that Suki starts processing.
Poll session status until a terminal state, then retrieve note content.

After this path works end to end on staging, add patient context, interoperability fields (emr_encounter_id and encounter_id), webhooks, transcripts, and production rollout.

Available cookbooks

AmbientAPI

End Ambient After Streaming

Send RU9G, then end session.

5 min

AmbientAPI

Authenticate Browser WebSocket Handshake

Auth browser WebSocket with protocols.

5 min

AmbientAPI

Poll Session Status Before Fetching Content

Poll until status is completed.

5 min

Available tutorials

Ambient

Build an Ambient Streaming Client

Authenticate, create a session, stream PCM audio over WebSocket, and retrieve clinical note results.

20 minIntermediate

Webhooks

Build a Webhook Notification Receiver

Verify HMAC signatures, parse partner notifications, and handle success and failure events.

10 minBeginner

Next steps

After you complete your first Ambient API session:

Provide Visit Context

Seed patient and visit context when you need better notes or Web SDK review.

Get the Generated Clinical Note

Choose session content, note content, or transcript after status is completed.

Ambient Interoperability

Pass emr_encounter_id and reuse encounter_id when notes span modalities.

Configure Webhooks

API Error Messages

Map Ambient API error codes and messages for Login, session, and content calls.

Get Started

API References

Ambient API Quickstart

Access and credentials

Prerequisites

Environments to use for development and testing

Complete staging script

Create your first Ambient session

Verify your integration

Available cookbooks

End Ambient After Streaming

Authenticate Browser WebSocket Handshake

Poll Session Status Before Fetching Content

Available tutorials

Build an Ambient Streaming Client

Build a Webhook Notification Receiver

Next steps

Provide Visit Context

Get the Generated Clinical Note

Ambient Interoperability

Configure Webhooks

API Error Messages

​Access and credentials

​Prerequisites

​Environments to use for development and testing

​Complete staging script

​Create your first Ambient session

​Verify your integration

​Available cookbooks

​End Ambient After Streaming

​Authenticate Browser WebSocket Handshake

​Poll Session Status Before Fetching Content

​Available tutorials

​Build an Ambient Streaming Client

​Build a Webhook Notification Receiver

​Next steps

Provide Visit Context

Get the Generated Clinical Note

Ambient Interoperability

Configure Webhooks

API Error Messages

Access and credentials

Prerequisites

Environments to use for development and testing

Complete staging script

Create your first Ambient session

Verify your integration

Available cookbooks

End Ambient After Streaming

Authenticate Browser WebSocket Handshake

Poll Session Status Before Fetching Content

Available tutorials

Build an Ambient Streaming Client

Build a Webhook Notification Receiver

Next steps