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

# Create Ambient Session

> Initialize a new ambient session for patient encounter documentation

<Callout title="Updates" color="orange" icon="bell">
  **Updated**

  The `multilingual` parameter is deprecated.

  Multilingual support is now **enabled by default** for all ambient sessions. You no longer need to pass this parameter. The API automatically supports conversations in multiple languages and generates the <Tooltip tip="The final structured medical documentation generated from a patient encounter, organized into standardized sections using LOINC codes." cta="View in Glossary" href="/Glossary/c">clinical note</Tooltip> in English.
</Callout>

Use this endpoint to create an <Tooltip tip="A single, time-bound instance of an ambient recording for a specific patient encounter that captures clinical conversations." cta="View in Glossary" href="/Glossary/a">ambient session</Tooltip>. Suki will generate an `ambient_session_id` and return it in the response.

Use the **`ambient_session_id`** to identify the <Tooltip tip="A single, time-bound instance of an ambient recording for a specific patient encounter." cta="View in Glossary" href="/Glossary/s">session</Tooltip>
in future API calls. Many Suki APIs use this ID to perform operations such as checking session status,
generating notes, retrieving transcripts, and other operations.

Store the **`ambient_session_id`** after you create a session, as it is required for most session-related operations.

### Request body fields

Both fields in the request body are optional. Suki generates any values you omit.

| Field                | Type          | Description                                                                                                                                                                                                                                      |
| -------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ambient_session_id` | string (UUID) | Unique identifier for this ambient session. Must be a string in UUID format. If omitted, Suki generates one and returns it in the response.                                                                                                      |
| `encounter_id`       | string (UUID) | Unique identifier for the patient encounter (visit). Must be a string in UUID format. Use the same `encounter_id` across multiple `session/create` calls to group several ambient sessions under the same visit. If omitted, Suki generates one. |

<Note>
  `encounter_id` must be a **string** in UUID format. Numeric IDs from your system must be converted to a string (for example, `String(id)`) before you send them.
</Note>

We recommend that recordings are at least **1 minute** long. Short recordings may not contain enough information for note generation.

<Note>
  **Important**:

  If the recording is too short, note generation may be **skipped**.
</Note>

## Code examples

<Tabs>
  <Tab title="Python">
    ```python expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    from typing import Any, Optional, TypedDict, cast

    import requests

    BASE_URL = "https://sdp.suki-stage.com"


    class CreateAmbientSessionRequest(TypedDict, total=False):
        ambient_session_id: str
        encounter_id: str


    class CreateAmbientSessionResponse(TypedDict):
        ambient_session_id: str


    class ApiHttpError(RuntimeError):
        """Wrong HTTP status; OpenAPI errors usually include JSON with message + code."""

        def __init__(self, status: int, url: str, detail: str) -> None:
            super().__init__(f"HTTP {status} {url}: {detail}")
            self.status = status
            self.url = url


    def _post_json_expect(url: str, headers: dict[str, str], payload: dict[str, Any], expect_status: int) -> dict[str, Any]:
        r = requests.post(url, json=payload, headers=headers, timeout=60)
        if r.status_code == expect_status:
            data = r.json()
            if isinstance(data, dict):
                return data
            raise ApiHttpError(expect_status, url, "response JSON was not an object")

        detail = ""
        try:
            err = r.json()
            if isinstance(err, dict) and isinstance(err.get("message"), str):
                detail = err["message"]
        except ValueError:
            detail = (r.text or "")[:500]
        raise ApiHttpError(r.status_code, url, detail or "(no body)")


    def create_ambient_session(
        suki_token: str,
        body: Optional[CreateAmbientSessionRequest] = None,
    ) -> CreateAmbientSessionResponse:
        """POST /api/v1/ambient/session/create (sdp_suki_token header required). HTTP 201."""
        url = f"{BASE_URL}/api/v1/ambient/session/create"
        headers = {"sdp_suki_token": suki_token, "sdp_provider_id": "<sdp_provider_id>", "Content-Type": "application/json"}
        data = _post_json_expect(url, headers, dict(body or {}), 201)
        sid = data.get("ambient_session_id")
        if not isinstance(sid, str) or not sid:
            raise ValueError(f"{url}: 201 response missing ambient_session_id")
        return cast(CreateAmbientSessionResponse, {"ambient_session_id": sid})


    if __name__ == "__main__":
        try:
            session = create_ambient_session(
                "<sdp_suki_token>",
                {
                    # Optional UUIDs; omit to let Suki generate.
                    "ambient_session_id": "123dfg-456dfg-789dfg-012dfg",
                    "encounter_id": "123dfg-456dfg-789dfg-012dfg",
                },
            )
            print(session["ambient_session_id"])
        except (ApiHttpError, ValueError) as e:
            print(e)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const BASE_URL = "https://sdp.suki-stage.com";

    type CreateAmbientSessionRequest = {
      ambient_session_id?: string;
      encounter_id?: string;
    };

    type CreateAmbientSessionResponse = { ambient_session_id: string };

    class ApiHttpError extends Error {
      status: number;
      url: string;
      constructor(status: number, url: string, detail: string) {
        super(`HTTP ${status} ${url}: ${detail}`);
        this.status = status;
        this.url = url;
      }
    }

    async function postJsonExpectObject(
      url: string,
      headers: Record<string, string>,
      body: Record<string, unknown>,
      expectStatus: number
    ): Promise<Record<string, unknown>> {
      const res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
      const text = await res.text();
      const json = text ? JSON.parse(text) : {};

      if (res.status !== expectStatus) {
        const msg = typeof (json as any)?.message === "string" ? (json as any).message : text?.slice(0, 500) || "(no body)";
        throw new ApiHttpError(res.status, url, msg);
      }
      if (json && typeof json === "object" && !Array.isArray(json)) return json as Record<string, unknown>;
      throw new ApiHttpError(res.status, url, "response JSON was not an object");
    }

    export async function createAmbientSession(
      sdpSukiToken: string,
      body: CreateAmbientSessionRequest = {}
    ): Promise<CreateAmbientSessionResponse> {
      const url = `${BASE_URL}/api/v1/ambient/session/create`;
      const data = await postJsonExpectObject(
        url,
        { sdp_suki_token: sdpSukiToken, sdp_provider_id: "<sdp_provider_id>", "Content-Type": "application/json" },
        body as Record<string, unknown>,
        201
      );
      const ambientSessionId = data.ambient_session_id;
      if (typeof ambientSessionId !== "string" || !ambientSessionId) {
        throw new Error(`${url}: 201 response missing ambient_session_id`);
      }
      return { ambient_session_id: ambientSessionId };
    }

    // Example usage
    const session = await createAmbientSession("<sdp_suki_token>", {
      // Optional UUIDs; omit to let Suki generate.
      ambient_session_id: "123dfg-456dfg-789dfg-012dfg",
      encounter_id: "123dfg-456dfg-789dfg-012dfg",
    });
    console.log(session.ambient_session_id);
    ```
  </Tab>
</Tabs>


## OpenAPI

````yaml POST /api/v1/ambient/session/create
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:
  /api/v1/ambient/session/create:
    post:
      tags:
        - /api/v1/ambient/session
      summary: Create ambient session
      description: >-
        Creates a new ambient session for patient encounter documentation.
        Returns an `ambient_session_id` to use in context, streaming, status,
        and content APIs. Both request body fields are optional; Suki generates
        any values you omit.
      parameters:
        - $ref: '#/components/parameters/ProviderIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/controllers.CreateSessionRequest'
            example:
              ambient_session_id: 123dfg-456dfg-789dfg-012dfg
              encounter_id: 123dfg-456dfg-789dfg-012dfg
        required: false
      responses:
        '201':
          description: Resource created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.CreateSessionResponse'
        '400':
          description: Bad request. The request body or parameters failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.BadRequestError'
        '401':
          description: Unauthorized. The Suki access token is missing, expired, or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.AuthenticationError'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.InternalServerError'
      security:
        - SukiTokenAuth: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --request POST \
              --url https://sdp.suki.ai/api/v1/ambient/session/create \
              --header 'Content-Type: application/json' \
              --header 'sdp_suki_token: <sdp_suki_token>' \
              --header 'sdp_provider_id: <sdp_provider_id>' \
              --data '{
              "ambient_session_id": "123dfg-456dfg-789dfg-012dfg",
              "encounter_id": "123dfg-456dfg-789dfg-012dfg"
            }'
components:
  parameters:
    ProviderIdHeader:
      name: sdp_provider_id
      in: header
      description: >-
        **Optional** - Stable identifier for the active provider. Omit for
        standard partners whose `partner_token` identifies the user.
        **Required** for Bearer partners and Single Auth Token authentication
        where multiple providers share one `partner_token`. Use the same
        `provider_id` you sent on Login or Register.
      required: false
      schema:
        type: string
        example: provider-123
  schemas:
    controllers.CreateSessionRequest:
      type: object
      properties:
        ambient_session_id:
          type: string
          description: >-
            **Optional** - UUID for this ambient session. Suki generates one
            when omitted and returns it in the response.
          example: 123dfg-456dfg-789dfg-012dfg
        encounter_id:
          type: string
          description: >-
            **Optional** - UUID for the patient encounter. Reuse the same value
            across multiple session create calls to group sessions under one
            visit. Suki generates one when omitted.
          example: 123dfg-456dfg-789dfg-012dfg
        multilingual:
          type: boolean
          description: >-
            **Deprecated.** Multilingual support is now true by default. To
            disable it, contact the Suki support team.
          example: true
          deprecated: true
      description: >-
        Optional session identifiers. Suki generates `ambient_session_id` and
        `encounter_id` when omitted.
    controllers.CreateSessionResponse:
      type: object
      properties:
        ambient_session_id:
          type: string
          example: 123dfg-456dfg-789dfg-012dfg
          description: >-
            UUID for the created ambient session. Store this for later API
            calls.
      description: New ambient session identifiers returned after create.
    controllers.BadRequestError:
      type: object
      properties:
        code:
          type: integer
          example: 400
          description: HTTP status code for the error.
        message:
          type: string
          example: invalid request
          description: Human-readable description of the validation or request error.
      description: Error response when the request fails validation.
    controllers.AuthenticationError:
      type: object
      properties:
        code:
          type: integer
          example: 401
          description: HTTP status code for the error.
        message:
          type: string
          example: invalid token
          description: Human-readable description of the authentication failure.
      description: Error response when authentication fails.
    controllers.InternalServerError:
      type: object
      properties:
        code:
          type: integer
          example: 500
          description: HTTP status code for the error.
        message:
          type: string
          example: internal server error
          description: Human-readable description of the server error.
      description: Error response when the server encounters an unexpected error.
  securitySchemes:
    SukiTokenAuth:
      type: apiKey
      in: header
      name: sdp_suki_token
      description: >-
        Suki access token for the authenticated provider. Obtain this by calling
        Login or Register with a valid `partner_token`. Pass the `suki_token`
        value from the JSON response as the `sdp_suki_token` header on REST
        requests and non-browser WebSocket upgrades. Browser WebSocket clients
        pass the token in `Sec-WebSocket-Protocol` instead. Tokens expire after
        one hour; call Login again to refresh.

````