--- name: suki-ambient description: >- Use when building ambient clinical documentation with Suki Ambient APIs or Ambient SDKs, including Web SDK, Headless Web SDK, and Mobile SDK: create an Ambient session, provide session context, stream visit audio, end the session, and retrieve generated clinical note content. license: SUKI_Proprietary metadata: author: suki version: "2.4" --- ## Ambient clinical notes Use **Ambient** to turn a clinical conversation into a structured clinical note. Ambient is different from: - **Form filling**, which populates structured medical form templates. - **Dictation**, which provides real-time speech-to-text. - **Audio streaming**, which documents the shared WebSocket wire format used by Ambient and Form filling on `/ws/stream` (and contrasts Dictation `/ws/transcribe`). The Streaming Wire Format hub is an overview only; exact Ambient JSON shapes are on the Ambient wire format page. ## Accuracy rules - Do not invent endpoints, request fields, response fields, SDK methods, status values, or WebSocket message types. - Use the Ambient API documentation for direct API integrations and the relevant SDK documentation for SDK integrations. - Do not use Dictation `/ws/transcribe`, `audioData`, or `AUDIO_END` for Ambient. - Do not use Form filling session IDs or structured-data endpoints for Ambient. - Form filling also returns an `ambient_session_id`, but that ID belongs to the Form filling session. It is not an Ambient session ID. - Do not assume that the Web SDK, Headless Web SDK, Mobile SDK, and Ambient API expose the same authentication or session lifecycle. - Do not assume that the WebSocket contains the generated clinical note. Retrieve the final content through the documented REST or SDK APIs. - Do not treat `encounter_id` and `emr_encounter_id` as the same identifier. - If an exact field, enum, SDK method, or workflow is unclear, read the linked Suki documentation or use the documentation MCP before generating code. ## Choose an integration path Once the path is known, **fetch that dedicated skill** and implement from it. Do not implement a full Web SDK, Headless, Mobile, or raw API integration from this workflow skill alone. | Path | Choose when | Dedicated skill | | --- | --- | --- | | **Ambient API** | Your application owns the UI, audio capture, session lifecycle, and note retrieval | `suki-ambient-api` | | **Web SDK** | You want Suki's hosted ambient UI in a web application | `suki-web-sdk` | | **Headless Web SDK** | You want to build your own React UI while using Suki's ambient session hooks | `suki-headless-web-sdk` | | **Mobile SDK** | You are integrating Ambient into a native iOS application | `suki-mobile-sdk` | Skill URLs: - Ambient API: https://developer.suki.ai/.well-known/agent-skills/suki-ambient-api/SKILL.md - Web SDK: https://developer.suki.ai/.well-known/agent-skills/suki-web-sdk/SKILL.md - Headless Web SDK: https://developer.suki.ai/.well-known/agent-skills/suki-headless-web-sdk/SKILL.md - Mobile SDK: https://developer.suki.ai/.well-known/agent-skills/suki-mobile-sdk/SKILL.md For direct API integrations, use staging unless the user explicitly requests production. | Environment | REST | WebSocket | | --- | --- | --- | | Staging | `https://sdp.suki-stage.com` | `wss://sdp.suki-stage.com` | | Production | `https://sdp.suki.ai` | `wss://sdp.suki.ai` | ## Ambient API workflow (summary) The following is a **summary** of the Ambient API path. For the full implementation rules, fetch **`suki-ambient-api`**. Do not apply the raw API authentication or WebSocket steps to an SDK unless the SDK documentation explicitly requires them. ```text authenticate → create Ambient session → provide session context → open /ws/stream → START_TIME → AUDIO chunks → AUDIO + EOF → close WebSocket → end session → poll session status → retrieve clinical note and/or transcript ```` | Step | Method | Path | Success | | --- | --- | --- | --- | | Login | `POST` | `/api/v1/auth/login` | `200` | | Register | `POST` | `/api/v1/auth/register` | `201` or documented conflict response | | Create session | `POST` | `/api/v1/ambient/session/create` | `201` | | Session context | `POST` | `/api/v1/ambient/session/{ambient_session_id}/context` | `200` | | Stream audio | `WebSocket` | `/ws/stream` | `101` | | End session | `POST` | `/api/v1/ambient/session/{ambient_session_id}/end` | `200` | | Session status | `GET` | `/api/v1/ambient/session/{ambient_session_id}/status` | `200` | | Content | `GET` | `/api/v1/ambient/session/{ambient_session_id}/content` | `200` | | Transcript | `GET` | `/api/v1/ambient/session/{ambient_session_id}/transcript` | `200` | ## 1. Authenticate Ambient API authentication uses the Suki Token returned by the authentication flow. * Follow the [Partner authentication](https://developer.suki.ai/documentation/how-to/partner-authentication) documentation for your partner configuration. * Use Login or Register as required by your partner setup. * The authentication response provides a `suki_token`. * Send that token as the `sdp_suki_token` header on subsequent Ambient REST requests. * Ambient WebSocket requests also use the Suki Token. * Send `sdp_provider_id` when required by your partner configuration. * The Suki Token is valid for about one hour. Refresh it before it expires. Do not replace `sdp_suki_token` with `Authorization: Bearer` for Ambient API requests unless a specific Suki endpoint explicitly documents that behavior. ## 2. Create an Ambient session Create a session with: ```http POST /api/v1/ambient/session/create ``` A successful request returns an `ambient_session_id`. Use that returned Ambient session ID for: * Session context * WebSocket streaming * Session end * Session status * Content retrieval * Transcript retrieval Do not substitute a Form filling `ambient_session_id`. The create request can also support session configuration such as: * `encounter_id` * `emr_encounter_id` * `multilingual` Use the create API documentation to confirm the fields and constraints required for the integration. ### Ambient session ID `ambient_session_id` identifies one Ambient recording session. It is different from: * `encounter_id`, which is the Ambient session group ID. * `emr_encounter_id`, which identifies the partner's EMR or EHR encounter. * `composition_id`, which identifies the generated note artifact. Do not use these identifiers interchangeably. ### `encounter_id` Ambient `encounter_id` is a session group identifier. Use it when the workflow needs to group Ambient sessions or re-ambient the same clinical note. It is not the same as the partner's EMR encounter ID. ### `emr_encounter_id` `emr_encounter_id` is the partner EMR or EHR visit identifier. For interoperability workflows, it anchors the Ambient note to the partner's encounter across supported Suki modalities. When using `emr_encounter_id`, follow the current create API requirements. The identifier must be a UUID for the current interoperability workflow. Do not use `encounter_id` when the integration specifically requires `emr_encounter_id`. ### `composition_id` Ambient session creation returns `composition_id` for the note artifact. For note-level Ambient APIs, use `composition_id` as the `note_id` where the API requires a note identifier. Do not assume `composition_id` is the same as `ambient_session_id`. ## 3. Provide session context After creating the Ambient session and before opening `/ws/stream`, provide session context: ```http POST /api/v1/ambient/session/{ambient_session_id}/context ``` Session context gives Suki information that can help guide note generation. Depending on the workflow, context can include information such as: * Patient information * Provider information * Visit information * Encounter information * Diagnoses * Note sections * EMR configuration Use the Context API schema for the exact request structure. Do not invent field names, enum values, or nested structures. ### Context timing The recommended order is: ```text create session → set session context → open WebSocket → stream audio ``` Opening the WebSocket before the session and required context are ready can cause the connection to fail. ### Note sections Ambient can generate note sections using LOINC codes. For example: ```json { "sections": [ { "loinc": "10164-2", "title": "History of Present Illness" }, { "loinc": "51847-2", "title": "Assessment and Plan" } ] } ``` Use only LOINC codes and section configuration supported by the current Ambient documentation. ## 4. Stream audio on `/ws/stream` Ambient audio is streamed over: ```text wss://sdp.suki-stage.com/ws/stream ``` for staging, or the corresponding production host. The `/ws/stream` endpoint is shared by Ambient and Form filling. Use the Ambient session ID when streaming an Ambient session. ### WebSocket prerequisites Before opening the socket: 1. Authenticate and obtain a Suki Token. 2. Create the Ambient session. 3. Provide required session context. 4. Confirm the session is ready for streaming. 5. Open `/ws/stream`. The Ambient WebSocket handshake requires the session to be in the appropriate state for streaming. The documented API workflow opens the socket while the session is `created`. Do not open `/ws/stream` after the session has already reached a terminal state. ### Non-browser clients Send these headers during the WebSocket upgrade: ```http sdp_suki_token: ambient_session_id: ``` ### Browser clients Browser clients send the authentication information through `Sec-WebSocket-Protocol`. Use the following comma-separated order: ```text SukiAmbientAuth,, ``` The order matters. Do not reverse the session ID and token. ### Text frames only Each outbound message is a UTF-8 JSON text frame. Do not send raw PCM bytes as WebSocket binary frames. The stream uses Base64-encoded audio inside JSON. ## 5. Send the Ambient stream messages The Ambient stream uses the following message sequence: ```text START_TIME → AUDIO → AUDIO → ... → AUDIO containing EOF → close WebSocket → REST end ``` ### `START_TIME` The first message is `START_TIME`. ```json { "type": "START_TIME", "data": "" } ``` The `data` value is the Base64 encoding of the RFC3339 timestamp as UTF-8 bytes. Do not send an empty `START_TIME`. ### `AUDIO` Audio messages use: ```json { "type": "AUDIO", "data": "" } ``` The `data` field contains Base64-encoded raw PCM audio. Do not use Dictation's `audioData` field. ### Streaming events Ambient supports documented `EVENT` messages such as: ```text PAUSE RESUME KEEP_ALIVE CANCEL ``` `ABORT` is deprecated. Use the current wire-format documentation for the exact event behavior and message structure. Do not invent additional event types. ### End of audio End the audio stream by sending an `AUDIO` message whose `data` is Base64 for the ASCII bytes: ```text EOF ``` The Base64 representation is: ```text RU9G ``` For example: ```json { "type": "AUDIO", "data": "RU9G" } ``` Do not use Dictation's: ```json { "type": "EVENT", "event": "AUDIO_END" } ``` That message belongs to `/ws/transcribe`, not `/ws/stream`. ### Close before REST end After sending the final EOF audio message: 1. Close the WebSocket. 2. Call the Ambient REST end endpoint. ```http POST /api/v1/ambient/session/{ambient_session_id}/end ``` Do not assume that sending EOF alone completes the Ambient session. ## 6. End the session Call: ```http POST /api/v1/ambient/session/{ambient_session_id}/end ``` after closing the WebSocket. Ending the session signals that the visit is complete and allows Suki to process the captured conversation and generate the final clinical note. ## 7. Poll session status Check: ```http GET /api/v1/ambient/session/{ambient_session_id}/status ``` The documented Ambient session statuses are: | Status | Meaning | | ----------- | ---------------------------------------------------------------------------------- | | `created` | Session has been created but has not started | | `ready` | Session has started and is ready for audio | | `running` | Session is processing audio and generating content | | `completed` | Session completed successfully and final content is available | | `failed` | Session failed during processing | | `skipped` | Session was skipped because there was not enough audio or the transcript was empty | | `aborted` | Session was cancelled by the user or client | `paused` is no longer supported as a current Ambient REST status. Use the status endpoint as the source of truth for the REST Ambient session lifecycle. ### Terminal statuses Stop polling when the session reaches: ```text completed failed skipped aborted ``` Only retrieve the final clinical note after the session reaches `completed`. For `failed`, `skipped`, or `aborted`, stop processing according to your application's error or cancellation flow. Do not invent additional terminal values. ## 8. Retrieve the clinical note After the session reaches `completed`, retrieve content with: ```http GET /api/v1/ambient/session/{ambient_session_id}/content ``` The content endpoint returns the generated clinical note content. The response includes structured note sections such as the `summary` array. For cumulative behavior, use the documented `cumulative` query parameter. For example: ```http GET /api/v1/ambient/session/{ambient_session_id}/content?cumulative=false ``` Do not assume that content is delivered as the final result of the WebSocket. ### Transcript Retrieve the transcript separately: ```http GET /api/v1/ambient/session/{ambient_session_id}/transcript ``` The response contains the final transcript data. Use the transcript endpoint when your application needs the conversation text separately from the generated clinical note. ## Session duration Ambient sessions should contain at least one minute of audio for note generation. Sessions shorter than one minute can receive: ```text skipped ``` and no clinical note is generated. A skipped session is not necessarily a system failure. Check whether the session had enough audio and whether the transcript contained usable speech. ## Audio requirements Use these requirements when implementing direct Ambient audio streaming. * 16 kHz sample rate * Mono audio * Signed 16-bit little-endian PCM * `LINEAR16` * Raw PCM data inside Base64-encoded JSON messages * Approximately 3200 bytes per 100 ms chunk * Stream audio at approximately real time * Strip a standard 44-byte WAV/RIFF header before sending PCM data when the source is a WAV file For connection timing, keep-alive behavior, pause behavior, and exact wire format, use the `suki-audio-streaming` skill. ### Active streams While actively streaming, send audio frequently enough to keep the connection active. The current streaming documentation specifies that active streams should receive audio at least every 25 seconds. ### Paused streams When the stream is paused, use the documented `KEEP_ALIVE` event to keep the connection alive. The streaming documentation specifies: * Send `KEEP_ALIVE` every 5 seconds while paused. * Maximum pause duration is 30 minutes. Do not use undocumented keep-alive messages. ## Web SDK path Choose the Web SDK when you want Suki's hosted Ambient UI in a JavaScript or React application. Use SDK authentication and initialization rather than copying the Ambient API login and `sdp_suki_token` workflow into the SDK integration. ### JavaScript and React The current Web SDK uses packages such as: ```text @ suki-sdk/js @ suki-sdk/react @ suki-sdk/core ``` Use the exact package and initialization flow documented for your Web SDK version. A typical initialization uses `SukiAuthManager` with partner and provider information, followed by SDK initialization. Do not invent SDK methods or configuration properties. ### Encounter identifiers For Web SDK interoperability, the encounter identifier represents the partner's EMR/EHR encounter. The current documentation requires the Web SDK encounter identifier to follow the UUID requirement for interoperability. Do not confuse: * Web SDK ambient session ID * Web SDK note ID * Web SDK encounter ID * Ambient API `ambient_session_id` * Ambient API `encounter_id` * `emr_encounter_id` These identifiers serve different purposes. ### Hosted UI The Web SDK provides the hosted Ambient experience. Your application is responsible for: * Initializing the SDK. * Providing the required authentication and provider information. * Providing the encounter context required by your integration. * Mounting the SDK into the appropriate UI element. * Handling note submission and EHR handoff according to the SDK documentation. Read the current Web SDK documentation for the exact version-specific API. ## Headless Web SDK path Use the Headless Web SDK when your React application owns the UI but uses Suki's session and recording hooks. The Headless Web SDK uses: ```text @ s uki-sdk/platform-react ``` Use the SDK's authentication and session hooks instead of copying the raw Ambient API authentication flow. ### Authentication The Headless Web SDK uses `useAuth`. The authentication flow can include: * `partnerId` * `partnerToken` * `autoRegister` * `loginOnMount` * `providerName` * `providerOrgId` * `providerSpecialty` Use only the properties supported by the installed SDK version. ### Create a session Use `useAmbient()` to create the Ambient session. Wait until session creation succeeds before passing the `ambientSessionId` to session controls. Do not pass an undefined or incomplete session ID to `useAmbientSession`. ### Manage the session Use `useAmbientSession()` to control the recording. The documented workflow includes methods such as: ```text start pause resume submit setSessionContext ``` Set session context after starting the session when following the current Headless Web SDK workflow. The Headless Web SDK also exposes session state such as the current session status. Use the SDK documentation for the exact status values and method behavior. ### Offline sessions The Headless Web SDK can expose whether a session is offline. If the SDK reports an offline session, follow the documented offline behavior rather than treating it as an API failure. ## Mobile SDK path Use the Mobile SDK for native iOS Ambient integrations. The Mobile SDK has its own initialization, authentication, session creation, recording, and content retrieval APIs. Do not copy the Ambient REST WebSocket workflow into Mobile SDK code. The documented Mobile SDK workflow is: ```text initialize SDK → create session → start recording → record conversation → end session → retrieve content and/or transcript ``` Follow the current Mobile SDK documentation for: * SDK initialization * Partner configuration * Provider information * Token provider * Session creation * Recording controls * Session delegate callbacks * Content retrieval * Transcript retrieval ## Ambient vs Form filling vs Dictation Do not mix these workflows. | Capability | Ambient | Form filling | Dictation | | --------------- | -------------------- | ---------------------------- | ------------------------------------ | | Primary output | Clinical note | Structured medical form data | Transcript text | | REST session ID | `ambient_session_id` | `ambient_session_id` | `transcription_session_id` | | WebSocket | `/ws/stream` | `/ws/stream` | `/ws/transcribe` | | Audio field | `data` | `data` | `audioData` | | Start message | `START_TIME` | `START_TIME` | No `START_TIME` | | End message | `AUDIO` with `RU9G` | `AUDIO` with `RU9G` | `EVENT` with `AUDIO_END` | | Main retrieval | `/content` | `/structured-data` | Transcript frames / final transcript | The fact that Ambient and Form filling share `/ws/stream` does not make their REST sessions interchangeable. ## Non-negotiable rules Before generating or reviewing Ambient API integration code, verify: * The session is created before the WebSocket is opened. * The correct Ambient `ambient_session_id` is used. * Required session context is provided before streaming. * `/ws/stream` is used, not `/ws/transcribe`. * Browser WebSocket protocol order is `SukiAmbientAuth,,`. * Non-browser clients send `sdp_suki_token` and `ambient_session_id` as WebSocket upgrade headers. * WebSocket messages are UTF-8 JSON text frames. * `START_TIME` is the first Ambient stream message. * `START_TIME.data` contains the Base64-encoded RFC3339 timestamp. * Audio is Base64-encoded PCM in the `data` field. * The stream ends with an `AUDIO` message containing Base64 `EOF` (`RU9G`). * Dictation `AUDIO_END` is not used. * The WebSocket is closed before the REST `/end` request. * The session status is checked before retrieving final content. * `completed` is treated as successful completion. * `failed`, `skipped`, and `aborted` are treated as terminal states. * Final note content is retrieved through the documented REST or SDK API. * `encounter_id` is not confused with `emr_encounter_id`. * A Form filling `ambient_session_id` is never used for an Ambient session. * Partner secrets and Suki access tokens are not committed to source control or exposed unnecessarily to clients. ## Production considerations Before moving an Ambient integration to production: * Confirm your partner authentication configuration. * Confirm your JWKS or other supported authentication setup. * Allowlist required Suki domains where your network requires it. * Use the production host only after the integration has been tested in staging. * Handle WebSocket connection failures and REST errors. * Handle `failed`, `skipped`, and `aborted` sessions. * Make session and note identifiers traceable in your application. * Avoid logging clinical audio, transcripts, notes, or access tokens unless required and appropriately protected. * Do not expose partner secrets in browser code. * Consider partner webhooks instead of tight polling for asynchronous completion notifications. ## Troubleshooting ### WebSocket connection fails Check: 1. The Ambient session was created successfully. 2. Session context was provided before opening the socket. 3. The WebSocket URL uses `wss://`. 4. The correct staging or production host is used. 5. Browser protocol order is exactly: ```text SukiAmbientAuth,, ``` 6. Non-browser clients use the required WebSocket headers. 7. The Suki Token is valid. 8. The session is in the correct state for streaming. 9. The client sends JSON text frames rather than binary PCM frames. ### Session is `skipped` A `skipped` session means Suki did not generate a clinical note because there was not enough usable audio or the transcript was empty. Check: * Session duration. * Audio format. * Audio chunking. * Whether actual speech was captured. * Whether the WebSocket stayed connected. * Whether the final EOF message was sent. * Whether the REST `/end` endpoint was called. ### Content is empty or incomplete Check: 1. The session has reached `completed`. 2. The correct `ambient_session_id` is used. 3. The WebSocket was closed before `/end`. 4. The `/end` endpoint was called successfully. 5. The application waits for processing before retrieving content. 6. The `sdp_suki_token` is still valid. Do not treat a WebSocket connection closing as proof that the clinical note is ready. ## When to read more - [Ambient API Quickstart](https://developer.suki.ai/api-reference/quickstart): Authenticate, create an Ambient session, stream audio, end the session, and retrieve the clinical note on staging - [Ambient Clinical Documentation](https://developer.suki.ai/documentation/concepts/ambient-clinical-notes/ambient-documentation): Learn how Suki generates structured clinical notes from patient-provider conversations. Align on workflow decisions, choose capture and note strategy, pick an Ambient product, then design review and EHR handoff - [Partner Authentication Mechanisms](https://developer.suki.ai/documentation/how-to/partner-authentication): Compare and choose the right authentication mechanism for your APIs and SDKs, including Partner Token exchange, JWKS, and provider registration - [Streaming Architecture](https://developer.suki.ai/documentation/how-to/audio-streaming/streaming-architecture): Learn how Ambient /ws/stream, Form filling /ws/stream, and Dictation /ws/transcribe fit together: REST sessions, WebSocket JSON frames, connection rules, and where results come from - [Streaming Wire Format Overview](https://developer.suki.ai/documentation/how-to/audio-streaming/websocket-streaming-wire-format): Choose the correct WebSocket wire format for Ambient, Form filling (`GET /ws/stream`), or Dictation (`GET /ws/transcribe`) JSON text frames - [Ambient Streaming Wire Format](https://developer.suki.ai/documentation/how-to/audio-streaming/websocket-streaming-wire-format-ambient): Format and send Base64 audio chunks as JSON text frames on GET /ws/stream for Ambient and Form filling sessions, including message types, order, and PCM chunking - [Web SDK Quickstart](https://developer.suki.ai/web-sdk/quickstart): Install the Web SDK, create SukiAuthManager, and mount SukiAssistant with encounter data in JavaScript or React - [Headless Web SDK Quickstart](https://developer.suki.ai/headless-web-sdk/quickstart): Install `@suki-sdk/platform-react`, authenticate with `useAuth`, and run your first ambient recording in a React app - [llms-full.txt](https://developer.suki.ai/llms-full.txt): Full-site dump for broad cross-product questions ## Sister skills * Ambient API: [https://developer.suki.ai/.well-known/agent-skills/suki-ambient-api/SKILL.md](https://developer.suki.ai/.well-known/agent-skills/suki-ambient-api/SKILL.md) * Web SDK: [https://developer.suki.ai/.well-known/agent-skills/suki-web-sdk/SKILL.md](https://developer.suki.ai/.well-known/agent-skills/suki-web-sdk/SKILL.md) * Headless Web SDK: [https://developer.suki.ai/.well-known/agent-skills/suki-headless-web-sdk/SKILL.md](https://developer.suki.ai/.well-known/agent-skills/suki-headless-web-sdk/SKILL.md) * Mobile SDK: [https://developer.suki.ai/.well-known/agent-skills/suki-mobile-sdk/SKILL.md](https://developer.suki.ai/.well-known/agent-skills/suki-mobile-sdk/SKILL.md) * Form filling: [https://developer.suki.ai/.well-known/agent-skills/suki-form-filling/SKILL.md](https://developer.suki.ai/.well-known/agent-skills/suki-form-filling/SKILL.md) * Dictation: [https://developer.suki.ai/.well-known/agent-skills/suki-dictation/SKILL.md](https://developer.suki.ai/.well-known/agent-skills/suki-dictation/SKILL.md) * Audio streaming: [https://developer.suki.ai/.well-known/agent-skills/suki-audio-streaming/SKILL.md](https://developer.suki.ai/.well-known/agent-skills/suki-audio-streaming/SKILL.md) * Webhooks: [https://developer.suki.ai/.well-known/agent-skills/suki-webhooks/SKILL.md](https://developer.suki.ai/.well-known/agent-skills/suki-webhooks/SKILL.md)