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

# Form Filling Audio Streaming

> WebSocket endpoint for streaming visit audio during Form filling sessions

Use this API to stream visit audio over the Partner WebSocket (`GET /ws/stream`) for Form filling sessions.

## Related guides

<Columns col={2}>
  <Card title="Stream Ambient Audio Overview" icon="book" href="/documentation/how-to/audio-streaming/ambient-audio-streaming" horizontal />

  <Card title="Ambient Streaming Wire Format" icon="book" href="/documentation/how-to/audio-streaming/websocket-streaming-wire-format-ambient" horizontal />

  <Card title="Complete the Ambient Session after Streaming" icon="book" href="/documentation/how-to/audio-streaming/websocket-streaming-complete-session" horizontal />
</Columns>

<Warning>
  Pass the `ambient_session_id` returned by [Create Form filling session](/form-filling-api-reference/form-filling-sessions/create) in the WebSocket handshake.

  Do **not** reuse an `ambient_session_id` from [Create ambient session](/api-reference/ambient-sessions/create). Both APIs return a field named `ambient_session_id`, but each ID belongs to a different product session and is not interchangeable.
</Warning>

## Prerequisites

Complete these steps before you open the WebSocket.

<Warning>
  Opening `/ws/stream` before the session and context are ready can cause handshake failures or a broken stream.
</Warning>

* **Authenticate** and obtain `sdp_suki_token`.
* **Create a Form filling session** with <Badge color="blue" size="sm">POST</Badge> [`/api/v1/form-filling/session/create`](/form-filling-api-reference/form-filling-sessions/create). Save the `ambient_session_id` from the **201 Created** response.
* **Seed session context** (recommended) with <Badge color="blue" size="sm">POST</Badge> [`/api/v1/form-filling/session/{ambient_session_id}/context`](/form-filling-api-reference/form-filling-sessions/context). Include `form_template_id` values when you send context.
* **Open the WebSocket** at `wss://sdp.suki-stage.com/ws/stream` (staging) or `wss://sdp.suki.ai/ws/stream` (production). Use your Form filling `ambient_session_id` in the handshake.

## Browser clients

Send `Sec-WebSocket-Protocol` during the handshake as one comma-separated string, in this order:

* Subprotocol name.
* `sdp_suki_token`.
* Form filling session ID (`ambient_session_id`).

<Note>
  Do not add spaces between values unless your client library requires them.
</Note>

Example:

```bash theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
Sec-WebSocket-Protocol: SukiAmbientAuth,<sdp_suki_token>,<ambient_session_id>
```

The server negotiates this subprotocol to establish the connection.

## Non-browser clients

For mobile apps, backend services, or testing tools, pass headers on the WebSocket upgrade request. Do not use `Sec-WebSocket-Protocol`.

* `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` - Form filling session ID from [Create Form filling session](/form-filling-api-reference/form-filling-sessions/create).

<Warning>
  Sending non-JSON payloads where the server expects JSON can cause parse errors (for example invalid character or null byte errors).
</Warning>

## Full code examples

For end-to-end Form filling streaming examples, start with these tutorials:

<div className="doc-guide-btn-row">
  <a href="/documentation/tutorials/form-filling-websocket-code-example" className="doc-guide-btn">
    Build Form Filling Streaming Client
  </a>

  <a href="/documentation/tutorials/overview" className="doc-guide-btn">
    All Tutorials
  </a>
</div>


## 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,<sdp_suki_token>,<ambient_session_id>'
            (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: <sdp_suki_token>' \
              --header 'sdp_provider_id: <sdp_provider_id>' \
              --header 'ambient_session_id: <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.

````