Skip to main content
Web SDK Hero Light The Suki Ambient API enables you to generate clinical notes directly from real-time conversations. Built on principles and standard HTTP status codes, it also provides WebSocket endpoints for streaming audio and receiving live events. With the Suki Ambient API, you can:
  • Send provider and encounter data to initiate a session.
  • Retrieve the AI-generated clinical note at the end of the conversation.
  • Access the complete conversation transcript for review or storage.
By integrating these capabilities, you can seamlessly automate and enhance clinical documentation workflows within your healthcare application.
The Ambient APIs are currently in an Early Access phase. To request access, please contact our partnership team.
Looking for a quick way to get started? Download our Postman collection below to get started.

Download Collection For Postman

​
API Key Capabilities

Multilingual Support

Suki supports over 80 languages for ambient sessions.

Personalization

Personalize the clinical note generation process for each provider.

PBC (Problem-Based Charting)

Ensure the generated clinical note reflects the most up-to-date clinical picture.

​
Before You Begin: Access & Credentials

To use the Suki Ambient API, you first need a set of partner credentials. To get your credentials, please contact our partnership team. They will guide you through the onboarding process and provide everything you need to get started.

​
Ambient API Workflow

To integrate with the Suki Ambient API, you will follow a session-based workflow.

​
Workflow Diagram

​
Step-By-Step Overview

1

Authenticate your session

You must first sign in to get an access token (sdp_suki_token).
2

Create a session

Initiate a new session for a specific patient encounter. This returns an ambient_session_id that you will use for the next steps.
3

Seed context (Optional)

Provide additional metadata such as provider specialty, patient information, and desired note sections to improve accuracy.
4

Stream audio

Send the real-time audio stream of the patient-clinician conversation to the Suki WebSocket endpoint.
5

End the session

Signal that the conversation is over. This action triggers the AI to begin generating the note.
6

Retrieve the note

Fetch the final, structured clinical note and the full transcript after the platform finishes processing. You can use webhooks (recommended) or polling to know when content is ready.

​
Getting Started With Ambient APIs

Follow the steps below to create an ambient session and generate a clinical note from a conversation.
For complete technical specifications, please refer the relevant API Reference page.

​
Client < > Suki Interaction

To begin, you must authenticate to get your access token. Send a POST request to the /login endpoint with the following parameters in the request body:
  1. partner_id: Your unique partner ID, which we provide to you securely offline.
  2. partner_token: The user’s OAuth 2.0 ID token from your identity provider.
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 an access token called sdp_suki_token.You must include this sdp_suki_token in the authorization header for all subsequent API calls.Handling an unregistered userIf the user is not yet registered in our system, the /login request will fail. In this case, you must first call the /register endpoint to create the user, then call /login again.
Token Expiration: The sdp_suki_token has a limited lifetime. 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.
If a user is not yet registered, you must call the /register endpoint to register a new user in the Suki partner system.You only need to call this endpoint once for each new user.
The full API specification for this endpoint will be added here.
To start an ambient session, send a POST request to the /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.
  1. encounter_id: 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.
After creating the session, you can send a POST request to the /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:
  1. provider_specialty (Optional): The specialty of the provider (e.g., “cardiology”).
  2. 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. See Appendix A for a list of standard sections.
  3. patient_info (Optional): An object containing the following patient information:
    • date_of_birth: The patient’s date of birth. This is used for accurate age calculation.
    • sex: The patient’s sex (MALE, FEMALE, OTHER, or UNKNOWN). Defaults to UNKNOWN.
Once you have created a session, you can begin streaming audio to it over a WebSocket connection.Connect to the WebSocket endpoint at wss://<your-suki-endpoint>/stream.Audio formatYou must stream raw audio data with the following specifications:
  • encoding: LINEAR16
  • sample_rate: 16KHz
  • channel: Mono
For optimal performance, we recommend chunking the audio into 100ms packets.WebSocket messagesThe WebSocket connection supports two types of messages: AUDIO and EVENT.
  • AUDIO: Carries the raw audio data in the required format.
  • EVENT: Signifies a specific action on the stream. The supported events are:
    • PAUSE: Pauses the audio stream.
    • RESUME: Resumes a paused audio stream.
    • CANCEL: Cancels the session. No note will be generated.
    • 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).
    • EOF: Indicates the end of the file or stream.
Stream behavior and timeouts
Keep the connection aliveYou must send a KEEP_ALIVE event at least once every five seconds when the stream is paused to prevent the connection from closing.
  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
  1. SendingCANCELterminates the session completely. No summary will be generated.
  2. SendingABORTends the current stream, but the session remains active. Suki will generate a note from the audio received before the interruption. You can resume streaming to the same ambient_session_id later.
To complete the session and begin the note generation process, send a POST request to the /session/end endpoint. This signals that no more audio will be sent for this session.Getting the generated noteOnce 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 manuallyAlternatively, you can use the following endpoints to check the status and retrieve the session’s content:
  1. GET /status: Check the processing status of a session.
  2. GET /content: Retrieve the final, structured clinical note.
  3. GET /transcript: Get the full conversation transcript, including timestamps for each part of the dialogue.

​
Next Steps

Explore the following API references to get started with the Suki Ambient API:

Ambient API

Learn about the Ambient API

Login API

Learn about the Login API

Register API

Learn about the Register API