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

  * Pass **`emr_encounter_id`** to enable cross-modality ambient interoperability.
  * The response now includes **`composition_id`**. Use it as `note_id` with the note-level Ambient APIs.
  * The `multilingual` parameter is deprecated. Multilingual support is enabled by default for all ambient sessions.
</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 returns an <Tooltip tip="Unique identifier for one ambient recording session in Ambient APIs. Create ambient session returns ambient_session_id (you can also pass one on create). Use it for session-scoped operations such as context, streaming, status, and session content. Distinct from Session Group ID and EMR Encounter ID." cta="View in Glossary" href="/Glossary/s#session-id-ambient-apis">`ambient_session_id`</Tooltip> and a <Tooltip tip="Identifier returned as composition_id from ambient session create for the note artifact linked to the session. Use it as note_id with note-level Ambient APIs." cta="View in Glossary" href="/Glossary/c#composition-id">`composition_id`</Tooltip>.
Use **`ambient_session_id`** for session-scoped operations such as context, streaming, status, and session content.

Store the **`composition_id`** from the response. You will pass this value as the <Tooltip tip="Unique identifier for an interoperable ambient note. Create ambient session returns composition_id; pass that value as note_id to note-level ambient endpoints such as note content, note context, and note structured data." cta="View in Glossary" href="/Glossary/n#note-id-ambient-apis">`note_id`</Tooltip> when you call the following note-level Ambient APIs:

<div className="doc-guide-btn-row">
  <a href="/api-reference/ambient-content/note-content" className="doc-guide-btn">
    Get Note Content
  </a>

  <a href="/api-reference/ambient-content/note-context" className="doc-guide-btn">
    Get Note Context
  </a>

  <a href="/api-reference/ambient-content/note-structured-data" className="doc-guide-btn">
    Get Note Structured Data
  </a>
</div>

To learn how to use ambient across modalities, refer to the [Ambient interoperability](/documentation/concepts/ambient-clinical-notes/ambient-interoperability) guide.

### Request body fields

All fields in the request body are **optional**. Suki generates values you omit, except that cross-modality interoperability requires `emr_encounter_id`.

| Field                | Type          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ambient_session_id` | string (UUID) | <Tooltip tip="Unique identifier for one ambient recording session in Ambient APIs. Create ambient session returns ambient_session_id (you can also pass one on create). Use it for session-scoped operations such as context, streaming, status, and session content. Distinct from Session Group ID and EMR Encounter ID." cta="View in Glossary" href="/Glossary/s#session-id-ambient-apis">Session ID (Ambient APIs)</Tooltip>. If omitted, Suki generates one and returns it in the response.                                                                    |
| `emr_encounter_id`   | string (UUID) | <Tooltip tip="The partner EMR or EHR visit identifier (emr_encounter_id) that anchors interoperable ambient notes across modalities. Required for cross-modality ambient workflows. Must be a UUID today. Distinct from the Ambient API encounter_id session group field." cta="View in Glossary" href="/Glossary/e#emr-encounter-id">EMR Encounter ID</Tooltip>. Pass a UUID when you want the same note to work across Ambient APIs and SDKs. Without this field, the note is not interoperable across modalities.                                                 |
| `encounter_id`       | string        | <Tooltip tip="Identifier that groups ambient sessions for the same note so you can re-ambient across modalities. On ambient session create, pass it as encounter_id (up to 255 characters). Distinct from EMR Encounter ID." cta="View in Glossary" href="/Glossary/s#session-group-id">Session Group ID</Tooltip>. Pass the same value when you continue or re-ambient a note. Up to **255** characters. If you omit it on the first session, Suki generates one and it matches the returned `composition_id`. The create response does not include `encounter_id`. |

<Note>
  **Important**:

  * We recommend that recordings are at least **1 minute** long. Short recordings may not contain enough information for note generation.
  * If the recording is too short, note generation may be **skipped**.
  * For interoperable workflows, pass a valid UUID for `emr_encounter_id`.
  * To continue a note on another modality, pass the existing `emr_encounter_id`.
  * Do not create sessions for the same `emr_encounter_id` at the same time. Wait at least **1 second** between create requests for that encounter. Faster back-to-back creates can return a conflict.
</Note>

## Code examples

<Tabs>
  <Tab title="Python">
    ```python expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import json
    import requests

    BASE_URL = "https://sdp.suki.ai"
    CREATE_SESSION_URL = f"{BASE_URL}/api/v1/ambient/session/create"

    # Get sdp_suki_token from Login: POST /api/v1/auth/login
    sdp_suki_token = "<sdp_suki_token>"

    # Required for single_auth partners
    sdp_provider_id = "<sdp_provider_id>"

    # Set these from your system. Omit a field by leaving the value as None.
    # All request body fields are optional. Suki generates values you omit.
    # Pass emr_encounter_id for cross-modality Ambient interoperability.
    ambient_session_id = None  # Optional UUID for this Ambient session
    emr_encounter_id = None  # UUID for your EMR encounter
    encounter_id = None  # Optional session group ID

    headers = {
        "sdp_suki_token": sdp_suki_token,
        "sdp_provider_id": sdp_provider_id,
        "Content-Type": "application/json",
    }

    payload = {}
    if ambient_session_id:
        payload["ambient_session_id"] = ambient_session_id
    if emr_encounter_id:
        payload["emr_encounter_id"] = emr_encounter_id
    if encounter_id:
        payload["encounter_id"] = encounter_id

    response = requests.post(
        CREATE_SESSION_URL,
        headers=headers,
        json=payload,
        timeout=60,
    )

    print("HTTP status:", response.status_code)

    try:
        response_body = response.json()
    except ValueError:
        print("Response was not JSON:")
        print(response.text)
        raise SystemExit(1)

    print("Response body:")
    print(json.dumps(response_body, indent=2))

    if response.status_code == 201:
        created_ambient_session_id = response_body["ambient_session_id"]
        composition_id = response_body["composition_id"]

        print("ambient_session_id:", created_ambient_session_id)
        print("composition_id:", composition_id)
        print(
            "Use ambient_session_id for session APIs "
            "(context, stream, status, session content)."
        )
        print(
            "Use composition_id as note_id for note-level Ambient APIs "
            "(note content, note context, note structured data)."
        )
    else:
        print("Create Ambient session failed.")
        if isinstance(response_body, dict):
            print("code:", response_body.get("code"))
            print("message:", response_body.get("message"))
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const BASE_URL = "https://sdp.suki.ai";
    const CREATE_SESSION_URL = `${BASE_URL}/api/v1/ambient/session/create`;

    // Get sdp_suki_token from Login: POST /api/v1/auth/login
    const sdpSukiToken = "<sdp_suki_token>";

    // Required for single_auth partners
    const sdpProviderId = "<sdp_provider_id>";

    // Set these from your system. Omit a field by leaving the value undefined.
    // All request body fields are optional. Suki generates values you omit.
    // Pass emr_encounter_id for cross-modality Ambient interoperability.
    const ambientSessionId: string | undefined = undefined; // Optional UUID for this Ambient session
    const emrEncounterId: string | undefined = undefined; // UUID for your EMR encounter
    const encounterId: string | undefined = undefined; // Optional session group ID

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

    type CreateAmbientSessionResponse = {
      ambient_session_id: string;
      composition_id: string;
    };

    type ApiErrorResponse = {
      code?: number;
      message?: string;
    };

    const payload: CreateAmbientSessionRequest = {};
    if (ambientSessionId) {
      payload.ambient_session_id = ambientSessionId;
    }
    if (emrEncounterId) {
      payload.emr_encounter_id = emrEncounterId;
    }
    if (encounterId) {
      payload.encounter_id = encounterId;
    }

    const response = await fetch(CREATE_SESSION_URL, {
      method: "POST",
      headers: {
        sdp_suki_token: sdpSukiToken,
        sdp_provider_id: sdpProviderId,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(payload),
    });

    const responseText = await response.text();
    let responseBody: CreateAmbientSessionResponse | ApiErrorResponse | unknown;

    try {
      responseBody = responseText ? JSON.parse(responseText) : {};
    } catch {
      console.error("Response was not JSON:");
      console.error(responseText);
      throw new Error("Create Ambient session returned non-JSON response");
    }

    console.log("HTTP status:", response.status);
    console.log("Response body:", JSON.stringify(responseBody, null, 2));

    if (response.status === 201) {
      const session = responseBody as CreateAmbientSessionResponse;
      console.log("ambient_session_id:", session.ambient_session_id);
      console.log("composition_id:", session.composition_id);
      console.log(
        "Use ambient_session_id for session APIs (context, stream, status, session content)."
      );
      console.log(
        "Use composition_id as note_id for note-level Ambient APIs (note content, note context, note structured data)."
      );
    } else {
      const error = responseBody as ApiErrorResponse;
      console.error("Create Ambient session failed.");
      console.error("code:", error.code);
      console.error("message:", error.message);
    }
    ```
  </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: Creates an 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:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/controllers.CreateSessionRequest'
            example:
              ambient_session_id: 123dfg-456dfg-789dfg-012dfg
              emr_encounter_id: 123dfg-456dfg-789dfg-012dfg
              encounter_id: 123dfg-456dfg-789dfg-012dfg
      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** 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
  schemas:
    controllers.CreateSessionRequest:
      type: object
      description: >-
        Optional session identifiers for Ambient session create. Pass
        `emr_encounter_id` to enable cross-modality interoperability.
      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
        emr_encounter_id:
          type: string
          description: >-
            **Optional** - UUID for your EMR or EHR visit. Pass this when you
            want the same Ambient note to work across APIs and SDKs. Required
            for cross-modality Ambient workflows.
          example: 123dfg-456dfg-789dfg-012dfg
        encounter_id:
          type: string
          description: >-
            **Optional** - Session group ID that groups Ambient sessions under
            one note. Pass the same value when you continue or re-ambient a
            note. Up to 255 characters. If omitted on the first session, Suki
            generates one.
          example: 123dfg-456dfg-789dfg-012dfg
        multilingual:
          type: boolean
          description: >-
            **Deprecated.** Multilingual support is enabled by default for all
            Ambient sessions.
          example: false
          deprecated: true
    controllers.CreateSessionResponse:
      type: object
      description: Identifiers returned after Ambient session create.
      properties:
        ambient_session_id:
          type: string
          description: >-
            UUID for the created Ambient session. Store this for later session
            API calls.
          example: 123dfg-456dfg-789dfg-012dfg
        composition_id:
          type: string
          description: >-
            ID of the note for this session. Pass this value as `note_id` when
            you call the note-level Ambient APIs.
          example: 123dfg-456dfg-789dfg-012dfg
    controllers.BadRequestError:
      description: Bad Request Response
      type: object
      properties:
        code:
          type: integer
          example: 400
        message:
          type: string
          example: invalid request
    controllers.AuthenticationError:
      description: Authentication Failure Response
      type: object
      properties:
        code:
          type: integer
          example: 401
        message:
          type: string
          example: invalid token
    controllers.InternalServerError:
      description: Internal Server Error Response
      type: object
      properties:
        code:
          type: integer
          example: 500
        message:
          type: string
          example: internal server error
  securitySchemes:
    SukiTokenAuth:
      type: apiKey
      in: header
      name: sdp_suki_token
      description: >-
        Suki access token (`suki_token`) from Login or Register. Expires after
        one hour.

````