> ## 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>. An ambient session is one recording for a patient <Tooltip tip="One patient visit or appointment with a healthcare provider. In Suki, an encounter can group one or more ambient sessions so related recordings and notes stay tied to the same clinical visit." cta="View in Glossary" href="/Glossary/e">encounter</Tooltip> (visit). One encounter can include one or more ambient sessions.

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

<Tip>
  For Start Ambient UI guidance, ID handling, and fields required for interoperability, refer to [Create an ambient session](/documentation/how-to/ambient-clinical-notes/create-ambient-session) guide.
</Tip>

## Request body fields

You can create an ambient session with an empty request body. Suki generates `ambient_session_id` and returns `composition_id`.

Add a field when you need to control how the session is identified or grouped:

* **`ambient_session_id`**: Supply your own session UUID.
* **`emr_encounter_id`**: Tie the note to a patient visit for cross-modality interoperability.
* **`encounter_id`**: Group re-ambient sessions on one note. Pass it on the first session, reuse the same value on later sessions, and store it locally. Create does not return this field.

All fields are **optional** when creating a standalone ambient session.

| Field                | Type          | Details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `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 encounter_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 the ID 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 field." cta="View in Glossary" href="/Glossary/e#emr-encounter-id">EMR Encounter ID</Tooltip>. Links the ambient session to the patient visit. Must be a UUID.                                                                              |
| `encounter_id`       | string        | <Tooltip tip="Ambient API field used to group re-ambient sessions for one note. Pass it as encounter_id on ambient session create (up to 255 characters). Distinct from EMR Encounter ID." cta="View in Glossary" href="/Glossary/e#encounter-id">Encounter ID</Tooltip>. Groups sessions for the same clinical note. Pass on the first session and reuse on re-ambient sessions. Maximum 255 characters. The create response does not return this field.                                        |

<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

**Language tabs (agents):** Equivalent code samples are available in: Python, TypeScript. Humans see one language at a time. Use the variant that matches the user's stack; behavior is the same across tabs.

<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  # Required for re-ambient workflows

    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; // Required for re-ambient workflows

    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: >-
        Session identifiers for Ambient session create. Pass `emr_encounter_id`
        to enable cross-modality interoperability and `encounter_id` for
        re-ambient workflows.
      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 for standalone sessions** - UUID for your EMR or EHR
            visit. One EMR encounter can contain multiple notes. Required for
            cross-modality Ambient workflows.
          example: 123dfg-456dfg-789dfg-012dfg
        encounter_id:
          type: string
          description: >-
            **Required for re-ambient workflows** - Groups re-ambient sessions
            for one note. Reuse the same value for every re-ambient session on
            that 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.

````