> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ambient API Quickstart

> Step-by-step guide to authenticate, create a session, stream audio, and retrieve the clinical note

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 an `sdp_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.

<Tip>
  **Using an AI coding tool?**

  Copy the following prompt to add the Suki developer documentation as a skill and [MCP server](/documentation/mcp) 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](/documentation/ai-optimized-documentation).

  <Prompt description="Install the Suki developer docs as a skill to get context on Suki's developer tools, APIs, and SDKs. Add the [MCP server](/documentation/mcp) for documentation search." icon="gear" iconType="regular" actions={["copy", "cursor"]}>
    Install the Suki developer docs as skill to get context on Suki's developer tools, APIs, and SDKs.

    npx skills add [https://developer.suki.ai](https://developer.suki.ai)

    Then add the Suki developer docs MCP server for access to documentation search. Follow the MCP instructions at [https://developer.suki.ai/documentation/mcp](https://developer.suki.ai/documentation/mcp).
  </Prompt>
</Tip>

## Access and credentials

You need partner credentials to use the Suki Ambient API.

Contact our [Partnership team](https://www.suki.ai/suki-partners/) to get your credentials. They will guide you through the [Onboarding process](/documentation/partner-onboarding) 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 <Tooltip tip="JSON Web Key Set. A set of keys containing the public keys used to verify any JWT issued by the authorization server." cta="View in Glossary" href="/Glossary/j">JWKS</Tooltip> endpoint (or Okta authorization server) for token validation

Refer to the [Partner onboarding](/documentation/partner-onboarding) and [Partner authentication](/documentation/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).

<Callout icon="code" color="#FFC107" iconType="regular">
  **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.
</Callout>

## 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](/api-reference/authentication/login) endpoint with the following parameters in the request body:

1. **partner\_id**: Your unique <Tooltip tip="A unique identifier assigned by Suki during onboarding that links an application to its configuration in the Suki Developer Platform." cta="View in Glossary" href="/Glossary/p">Partner ID</Tooltip>, which we provide to you securely offline.
2. **partner\_token**: The user's OAuth 2.0 ID token (<Tooltip tip="A secure, digitally signed JWT issued by a partner's identity provider after user authentication, passed to Suki SDK for user verification." cta="View in Glossary" href="/Glossary/p">Partner Token</Tooltip>) from your identity provider.
3. **provider\_id** (Optional): Unique identifier for the <Tooltip tip="A healthcare professional within an organization who uses Suki's services to document patient care." cta="View in Glossary" href="/Glossary/p">provider</Tooltip>. 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 <Tooltip tip="The access token returned by Suki's authentication API, used to authorize subsequent API requests to the Suki platform." cta="View in Glossary" href="/Glossary/s">Suki Token</Tooltip> (`suki_token`) that you must include as the `sdp_suki_token` header for all subsequent API calls.

<Note>
  **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](/api-reference/authentication/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](/api-reference/authentication/register) for the full specification.
</Note>

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  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"
    }'
  ```
</CodeGroup>

<Tip>
  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`.
</Tip>

## Step 2: Create ambient session

To start an ambient session, send a **POST** request to the [/api/v1/ambient/session/create](/api-reference/ambient-sessions/create) endpoint with the following parameters in the request body:

<Note>
  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.
</Note>

<Note>
  The `multilingual` parameter is deprecated. Multilingual support is now **true** by default for all Suki for Partner users.
</Note>

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.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  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"
    }'
  ```
</CodeGroup>

<Tip>
  Save the `ambient_session_id` from the response. You will need it to stream audio and retrieve content.
</Tip>

## Step 3: Seed context

After creating the session, you can send a **POST** request to the [/api/v1/ambient/session/{ambient_session_id}/context](/api-reference/ambient-sessions/context) endpoint to provide additional metadata.

<Note>
  Providing **context** significantly improves the accuracy of the generated clinical note.
</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](/api-reference/ambient-sessions/context) 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](/api-reference/ambient-sessions/audio-stream) 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

<Note>
  `.wav` files are containers; strip the usual **44-byte** WAV header (or decode to PCM) before chunking. Sending RIFF headers as PCM hurts recognition.
</Note>

<Tip>
  For optimal performance, we recommend chunking the audio into **100ms packets**.
</Tip>

**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.
* <Badge color="red" size="sm">Deprecated</Badge> **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.

<Tip>
  **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.
</Tip>

<Note>
  **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.
</Note>

<Note>
  **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.
</Note>

## Step 5: End session

To complete the session and begin the note generation process, send a **POST** request to the [/api/v1/ambient/session/{ambient_session_id}/end](/api-reference/ambient-sessions/end) endpoint. This signals that you will not send more audio for this session.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  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>"
  ```
</CodeGroup>

## 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/{ambient_session_id}/status](/api-reference/ambient-content/status): Check the processing status of a session.
2. [GET /api/v1/ambient/session/{ambient_session_id}/content](/api-reference/ambient-content/content): Retrieve the final, structured clinical note.
3. [GET /api/v1/ambient/session/{ambient_session_id}/transcript](/api-reference/ambient-content/transcript): Get the full conversation transcript, including **timestamps** for each part of the dialogue.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  # 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>"
  ```
</CodeGroup>

<Warning>
  **Session Duration Requirement**

  Your 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.
</Warning>

<Note>
  For complete technical specifications, please refer to the relevant API Reference pages.
</Note>

## Next steps

After completing your first session, explore these resources to deepen your integration:

<Icon icon="file-lines" iconType="solid" /> [Authentication API](/api-reference/authentication/login) - Login, register, and JWKS configuration.

<Icon icon="file-lines" iconType="solid" /> [Context API](/api-reference/ambient-sessions/context) - Seed specialty, sections, and patient info for better note accuracy.

<Icon icon="file-lines" iconType="solid" /> [Audio Streaming API](/api-reference/ambient-sessions/audio-stream) - WebSocket connection details and message formats.

<Icon icon="file-lines" iconType="solid" /> [Webhook](/api-reference/asynchronous/webhook) - Configure webhooks to receive notifications when notes are ready.