Skip to main content

Suki Ambient APIs

The Suki Ambient APIs allow you to generate clinical notes from real-time conversations between providers and patients. The APIs use standard endpoints for most operations and HTTP status codes for responses. For streaming audio data, the APIs provide WebSocket endpoints that enable real-time audio transmission and event notifications.

What You Can Do

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.

API Versions

The Suki Platform APIs use version v1, which is the stable version. All API endpoints use the /api/v1/ prefix in the URL.

v1: Stable version of the API. Features in the stable version are fully-supported over the lifetime of the major version. If there are any breaking changes, then the next major version of the API will be created and the existing version will be deprecated after a reasonable period of time. Non-breaking changes may be introduced to the API without changing the major version.

Early Access: Some features may be available in Early Access phase. These features are under development and may be subject to changes. While Early Access features use the v1 API version, they may receive updates based on feedback.

If you require stability in your production environment and cannot risk breaking changes, you should carefully review Early Access features before implementing them in production.

All features listed in this documentation are available in v1. For detailed information about versioning policies, backward compatibility, and migration strategies, refer to our API Reference Guidelines.

Postman Collection

Looking for a quick way to get started? Download our Postman collection below to test the Suki Ambient APIs.

Postman is a powerful and user-friendly API interface that displays requests and responses in structured formats. You can integrate and explore the Suki Ambient API through Postman.

Download Collection For Postman

API Capabilities

80+ Languages

Multilingual Support

Suki supports over 80 languages for ambient sessions.

Learn More →
Customizable

Personalization

Personalize the clinical note generation process for each provider.

Learn More →
PBC

PBC (Problem-Based Charting)

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

Learn More →

New APIs

NEW

Create Dictation Session

Initialize a new dictation session for real-time audio transcription.

View Endpoint →
NEW

Stream Audio To Dictation Session

Stream audio data to the dictation service via WebSocket connection.

View Endpoint →
NEW

End Dictation Session

Complete a dictation session and trigger transcript generation.

View Endpoint →

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 APIs Workflow

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

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

Authentication

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.

Registration

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.

Session Creation

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.

Context

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.

Streaming

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. Pause is no longer supported
    • 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 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.
  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. Sending CANCEL terminates the session completely. No summary will be generated.
  2. Sending ABORT ends 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.

Note Generation

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 note: 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 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.