> ## 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.
# Audio Streaming
> WebSocket endpoint for real-time audio streaming during Ambient sessions
Use this API to stream audio to the speech service over a WebSocket connection for ambient and Form filling sessions.
For more information on how to handle the **handshake**, **wire format**, **message order**, and **error handling**, refer to [Stream ambient audio over WebSocket](/documentation/how-to/audio-streaming/ambient-audio-streaming), [WebSocket streaming wire format](/documentation/how-to/audio-streaming/websocket-streaming-wire-format), and [Complete the session after streaming](/documentation/how-to/audio-streaming/websocket-streaming-complete-session).
## Prerequisites
Complete these steps **before** opening the WebSocket.
Opening `/ws/stream` before the session and context are ready often leads to handshake failures or a broken stream.
* **Authenticate** and obtain `sdp_suki_token`
* **Create an ambient session** with POST [`/api/v1/ambient/session/create`](/api-reference/ambient-sessions/create). A successful create returns **201 Created**; keep the `ambient_session_id` you used or received.
* **Seed session context** with POST [`/api/v1/ambient/session/{ambient_session_id}/context`](/api-reference/ambient-sessions/context). Send the JSON body your integration requires (see that endpoint for the full schema).
* **Authenticate and open the WebSocket** on `wss://sdp.suki-stage.com/ws/stream`. To stream audio, you must first establish an **authenticated WebSocket connection**. The authentication method you use depends on your client types: browser or non-browser.
## Browser clients
When connecting from a browser, include the `Sec-WebSocket-Protocol` header as part of the WebSocket handshake.
Set the header value as a single comma-separated string. The order must be:
* Subprotocol name
* Token - Your `sdp_suki_token`
* Ambient session ID - Your ambient session ID
Avoid adding spaces between values unless your client library requires it.
For example:
```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
Sec-WebSocket-Protocol: SukiAmbientAuth,,
```
The server negotiates this subprotocol to establish the connection.
## Non-browser clients
For non-browser clients such as mobile apps, backend services, or testing tools, pass authentication details as separate HTTP headers in the WebSocket upgrade request. Do not use the `Sec-WebSocket-Protocol` header.
Include the following headers:
* `sdp_suki_token` - Session token from login.
* `sdp_provider_id` - Provider identifier. Optional for standard partners; **Required** for Single Auth Token authentication.
* `ambient_session_id` - The ID for the current ambient session.
If you push non-JSON payloads where the server expects JSON, you can see parse errors (for example invalid character or null byte errors).
## Full code examples
For end-to-end ambient and Form filling streaming examples, start with these tutorials:
## OpenAPI
````yaml GET /ws/stream
openapi: 3.0.1
info:
title: Suki Developer Platform
description: >-
REST and WebSocket APIs for the Suki Developer Platform. Authenticate with
Login or Register to obtain a Suki access token, then integrate ambient
clinical documentation, form filling, transcription, and reference metadata
endpoints.
contact: {}
version: '1.0'
servers:
- url: https://sdp.suki.ai
description: >-
Production base URL for Suki Developer Platform REST APIs. WebSocket
endpoints use the same host with `wss://`.
security:
- SukiTokenAuth: []
paths:
/ws/stream:
get:
tags:
- /ws
summary: Stream ambient audio
description: >-
Opens a WebSocket to stream audio for ambient or form-filling sessions.
Create the session and seed context before connecting. Browser clients
authenticate with `Sec-WebSocket-Protocol`; non-browser clients send
`sdp_suki_token`, optional `sdp_provider_id`, and `ambient_session_id`
as headers.
parameters:
- name: Sec-WebSocket-Protocol
in: header
description: >-
Required FOR BROWSER CLIENTS ONLY. Sent during WebSocket handshake.
Browsers must use the same subprotocol the grpc-wsproxy maps to
Authorization:
'SukiAmbientAuth,,'
(comma-separated; token second, ambient session id third). Other
subprotocol names are not mapped and typically yield 401.
schema:
type: string
- name: ambient_session_id
in: header
description: >-
Required for non-browser clients only. Session UUID from Create
Ambient Session or Create Form filling Session.
required: true
schema:
type: string
- $ref: '#/components/parameters/ProviderIdHeader'
responses:
'101':
description: Switching Protocols - Indicates successful WebSocket handshake.
content:
application/json:
schema:
type: string
'200':
description: >-
OK - May indicate successful stream processing or completion (e.g.,
sending 'EOF' message). Specific meaning depends on implementation
after handshake.
content:
application/json:
schema:
type: string
'400':
description: Bad Request - Invalid parameters, headers, or request format.
content:
application/json:
schema:
type: string
'401':
description: >-
Unauthorized - Authentication failed (invalid token/session,
incorrect protocol/headers).
content:
application/json:
schema:
type: string
'403':
description: >-
Forbidden - Client is authenticated but not authorized for this
action.
content:
application/json:
schema:
type: string
'500':
description: Internal Server Error - Abnormal closure or server-side issue.
content:
application/json:
schema:
type: string
security:
- SukiTokenAuth: []
x-codeSamples:
- lang: bash
label: cURL
source: |-
curl --request GET \
--url https://sdp.suki.ai/ws/stream \
--header 'sdp_suki_token: ' \
--header 'sdp_provider_id: ' \
--header 'ambient_session_id: '
components:
parameters:
ProviderIdHeader:
name: sdp_provider_id
in: header
description: >-
**Optional** for standard partners.
**Required** for:
- **Bearer authentication.** Use the same `provider_id` returned by the
Login or Register API.
- **Single Auth Token authentication.** Include the same `provider_id`
on every request as `sdp_provider_id`.
required: false
schema:
type: string
example: provider-123
securitySchemes:
SukiTokenAuth:
type: apiKey
in: header
name: sdp_suki_token
description: >-
Suki access token (`suki_token`) from Login or Register. Expires after
one hour.
````