Skip to main content
This guide walks you through the steps to use the Suki Ambient APIs to create an ambient session, stream audio, and retrieve the clinical note. What you will do
  1. Authenticate to get a Suki token (and register the user if needed).
  2. Create an ambient session and optionally seed context for better notes.
  3. Stream audio over the WebSocket, send control events, and end the session when the visit is done.
  4. Retrieve the clinical note and transcript, or rely on a webhook when processing finishes.
Using an AI coding tool?Copy the following prompt to add the Suki developer documentation as a skill and MCP server to your tool for better AI-assisted coding during the integration process. For all AI options (contextual menu, llms.txt, and skill.md), refer to AI-optimized documentation.

Install the Suki developer docs as a skill to get context on Suki's developer tools, APIs, and SDKs. Add the MCP server for documentation search.

Open in Cursor

​
Access and credentials

You need partner credentials to use the Suki Ambient API. 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
Refer to the Partner onboarding and Partner authentication guides for more details.

​
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.

​
Step 1: Authenticate and get token

To begin, you must authenticate to get your access token. Send a POST request to the /api/v1/auth/login endpoint with the following parameters in the request body:
  1. partner_id: Your unique , which we provide to you securely offline.
  2. partner_token: The user’s OAuth 2.0 ID token () from your identity provider.
  3. provider_id (Optional): Unique identifier for the . Required for Bearer type partners only.
Suki verifies the partner_token using your publicly exposed JWKS endpoint (or your Okta authorization server URL if you use Okta). On a successful request, the API returns a (suki_token) that you must include as the sdp_suki_token header for all subsequent API calls.
Handling an unregistered user:
  • If the user is not yet registered in our system, the /login request will fail.
  • In this case, you must first call the /api/v1/auth/register endpoint to create the user, then call /login again.
  • You only need to call the register endpoint once for each new user.
  • Refer to the Register API reference for the full specification.
curl -X POST https://sdp.suki-stage.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "partner_id": "your-partner-id",
    "partner_token": "your-jwt-token",
    "provider_id": "provider-123"
  }'
Save the suki_token from the response. This token is valid for 1 hour. When it is about to expire, you can get a new one by making the same POST request to /login with a valid partner_token.

​
Step 2: Create ambient session

To start an ambient session, send a POST request to the /api/v1/ambient/session/create endpoint with the following parameters in the request body:
This guide uses encounter_id. In older versions of the API, this parameter was named session_group_id. The old name will be deprecated in a future release.
The multilingual parameter is deprecated. Multilingual support is now true by default for all Suki for Partner users.
  1. encounter_id (Optional): A unique identifier for the patient encounter (also called a visit). This can be any alphanumeric string up to 255 characters long.
  2. ambient_session_id (Optional): A UUID v4 to identify the session. If you do not provide one, Suki will generate it and include it in the response.
curl -X POST https://sdp.suki-stage.com/api/v1/ambient/session/create \
  -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
  -H "sdp_provider_id: <sdp_provider_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "ambient_session_id": "123dfg-456dfg-789dfg-012dfg",
    "encounter_id": "123dfg-456dfg-789dfg-012dfg"
  }'
Save the ambient_session_id from the response. You will need it to stream audio and retrieve content.

​
Step 3: Seed context

After creating the session, you can send a POST request to the /api/v1/ambient/session//context endpoint to provide additional metadata.
Providing context significantly improves the accuracy of the generated clinical note.
Include the following parameters in the request body:
  • provider_specialty (Optional): The specialty of the provider (e.g., “cardiology”).
  • sections (Optional): A list of the clinical sections you want summarized, such as “Assessment and Plan” or “Chief Complaint”. If you do not provide this, a default set of sections will be used.
  • patient_info (Optional): An object containing date_of_birth (for accurate age calculation) and sex (MALE, FEMALE, OTHER, or UNKNOWN; defaults to UNKNOWN).
Refer to the Context API reference for the full request structure.

​
Step 4: Stream audio via WebSocket

After you create the ambient session and seed context (previous steps), open a WebSocket to wss://sdp.suki-stage.com/ws/stream. Upgrading before the session exists or before context is ready often fails. For authentication, use the Sec-WebSocket-Protocol header (browser clients) with the comma-separated value SukiAmbientAuth,<ambient_session_id>,<sdp_suki_token>, or send sdp_suki_token and ambient_session_id as separate HTTP headers on the upgrade (non-browser clients). See the Audio streaming API reference for the full wire format and code samples. Audio format: You must stream raw PCM in each AUDIO message (after Base64 encoding) with:
  • encoding: LINEAR16
  • sample_rate: 16KHz
  • channel: Mono
.wav files are containers; strip the usual 44-byte WAV header (or decode to PCM) before chunking. Sending RIFF headers as PCM hurts recognition.
For optimal performance, we recommend chunking the audio into 100ms packets.
Outbound WebSocket messages must each be one JSON text frame (one object per send). Use proto JSON field names: type and data for START_TIME and AUDIO. The data field is always standard Base64 (RFC 4648) of raw bytes. Do not send PCM as binary WebSocket frames on this endpoint. Required send order for a stream segment:
  1. START_TIME: data is Base64 of the UTF-8 RFC 3339 timestamp string.
  2. AUDIO: one or more messages with data set to Base64 of each PCM chunk.
  3. End marker: an AUDIO message whose data is Base64 of the three bytes EOF (ASCII), value RU9G. Do not use {"type":"end_of_stream"} for this protocol.
EVENT messages use {"type":"EVENT","event":"<ENUM>"} (not data for the action). Supported values include:
  • PAUSE: Pauses the stream.
  • RESUME: Resumes a paused audio stream.
  • CANCEL: Immediately mark an ambient session as CANCELLED in our system, it closes the WebSocket. The session cannot be resumed again; create a new session if you want to record again.
  • Deprecated ABORT: Aborts the stream due to an interruption. A note will be generated from the audio received so far. The session remains active and can be resumed.
  • KEEP_ALIVE: Pings the server to keep the connection alive during periods of inactivity (e.g., when paused).
When you are done sending audio, close the WebSocket, then call the end session endpoint (next step) and poll status and REST content endpoints for the final note and transcript. Final results are not guaranteed from the WebSocket alone.
Keep the connection alive: You must send a KEEP_ALIVE event at least once every five seconds when the stream is paused to prevent the connection from closing.
Stream behavior and timeouts: 1. Session Timeouts: If no audio data is sent for 25 seconds, Suki will disconnect the stream. 2. Paused Stream: If the stream is paused and receiving KEEP_ALIVE events, Suki will disconnect the stream after 30 minutes of inactivity.
CANCEL vs. ABORT: Sending CANCEL terminates the session completely. No note will be generated. Sending ABORT ends the current stream, but the session remains active. Suki will generate a note from the audio received before the interruption. Resume streaming to the same ambient_session_id later.

​
Step 5: End session

To complete the session and begin the note generation process, send a POST request to the /api/v1/ambient/session//end endpoint. This signals that no more audio will be sent for this session. 
curl -X POST "https://sdp.suki-stage.com/api/v1/ambient/session/YOUR_SESSION_ID/end" \
  -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
  -H "sdp_provider_id: <sdp_provider_id>"

​
Step 6: Retrieve generated content

Once the note is ready, Suki notifies your application. The recommended way to know when a note is ready is to use a webhook. Suki will send a session_summary_generated event to a webhook endpoint that you provide. Details on configuring your webhook and its authentication will be provided during the onboarding process. Retrieving content manually: Alternatively, you can use the following endpoints to check the status and retrieve the session’s content:
  1. GET /api/v1/ambient/session//status: Check the processing status of a session.
  2. GET /api/v1/ambient/session//content: Retrieve the final, structured clinical note.
  3. GET /api/v1/ambient/session//transcript: Get the full conversation transcript, including timestamps for each part of the dialogue.
# Get clinical note
curl -X GET "https://sdp.suki-stage.com/api/v1/ambient/session/YOUR_SESSION_ID/content?cumulative=false" \
  -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
  -H "sdp_provider_id: <sdp_provider_id>"

# Get transcript
curl -X GET "https://sdp.suki-stage.com/api/v1/ambient/session/YOUR_SESSION_ID/transcript" \
  -H "sdp_suki_token: YOUR_SUKI_TOKEN" \
  -H "sdp_provider_id: <sdp_provider_id>"
Session Duration RequirementYour ambient session must be at least 1 minute long for note generation to occur. Sessions shorter than 1 minute will receive a SKIPPED status, meaning no clinical note was generated.
For complete technical specifications, please refer to the relevant API Reference pages.

​
Next steps

After completing your first session, explore these resources to deepen your integration: Authentication API - Login, register, and JWKS configuration. Context API - Seed specialty, sections, and patient info for better note accuracy. Audio Streaming API - WebSocket connection details and message formats. Webhook - Configure webhooks to receive notifications when notes are ready.
Last modified on June 12, 2026