Create Ambient Session

POST

api

ambient

session

create

cURL

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"
}'

import requests

url = "https://sdp.suki.ai/api/v1/ambient/session/create"

payload = {
    "ambient_session_id": "123dfg-456dfg-789dfg-012dfg",
    "emr_encounter_id": "123dfg-456dfg-789dfg-012dfg",
    "encounter_id": "123dfg-456dfg-789dfg-012dfg"
}
headers = {
    "sdp_suki_token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {sdp_suki_token: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    ambient_session_id: '123dfg-456dfg-789dfg-012dfg',
    emr_encounter_id: '123dfg-456dfg-789dfg-012dfg',
    encounter_id: '123dfg-456dfg-789dfg-012dfg'
  })
};

fetch('https://sdp.suki.ai/api/v1/ambient/session/create', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sdp.suki.ai/api/v1/ambient/session/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ambient_session_id' => '123dfg-456dfg-789dfg-012dfg',
    'emr_encounter_id' => '123dfg-456dfg-789dfg-012dfg',
    'encounter_id' => '123dfg-456dfg-789dfg-012dfg'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "sdp_suki_token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sdp.suki.ai/api/v1/ambient/session/create"

	payload := strings.NewReader("{\n  \"ambient_session_id\": \"123dfg-456dfg-789dfg-012dfg\",\n  \"emr_encounter_id\": \"123dfg-456dfg-789dfg-012dfg\",\n  \"encounter_id\": \"123dfg-456dfg-789dfg-012dfg\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("sdp_suki_token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sdp.suki.ai/api/v1/ambient/session/create")
  .header("sdp_suki_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ambient_session_id\": \"123dfg-456dfg-789dfg-012dfg\",\n  \"emr_encounter_id\": \"123dfg-456dfg-789dfg-012dfg\",\n  \"encounter_id\": \"123dfg-456dfg-789dfg-012dfg\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sdp.suki.ai/api/v1/ambient/session/create")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["sdp_suki_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ambient_session_id\": \"123dfg-456dfg-789dfg-012dfg\",\n  \"emr_encounter_id\": \"123dfg-456dfg-789dfg-012dfg\",\n  \"encounter_id\": \"123dfg-456dfg-789dfg-012dfg\"\n}"

response = http.request(request)
puts response.read_body

{
  "ambient_session_id": "123dfg-456dfg-789dfg-012dfg",
  "composition_id": "123dfg-456dfg-789dfg-012dfg"
}

{
  "code": 400,
  "message": "invalid request"
}

{
  "code": 401,
  "message": "invalid token"
}

{
  "code": 500,
  "message": "internal server error"
}

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.

Use this endpoint to create an . Suki returns an and a . 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 when you call the following note-level Ambient APIs:

Get Note Content Get Note Context Get Note Structured Data

To learn how to use ambient across modalities, refer to the 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)	. If omitted, Suki generates one and returns it in the response.
`emr_encounter_id`	string (UUID)	. 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	. 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`.

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.

Code examples

Python
TypeScript

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"))

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);
}

Authorizations

sdp_suki_token

string

header

required

Suki access token (suki_token) from Login or Register. Expires after one hour.

Headers

sdp_provider_id

string

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.

Example:

"provider-123"

Body

application/json

Optional session identifiers for Ambient session create. Pass emr_encounter_id to enable cross-modality interoperability.

ambient_session_id

string

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

string

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

string

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

boolean

deprecated

Deprecated. Multilingual support is enabled by default for all Ambient sessions.

Example:

false

Response

Resource created successfully.

Identifiers returned after Ambient session create.

ambient_session_id

string

UUID for the created Ambient session. Store this for later session API calls.

Example:

"123dfg-456dfg-789dfg-012dfg"

composition_id

string

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"

Last modified on July 23, 2026

Ambient Session Management APIs

Seed Ambient Session Context

⌘I

cURL

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"
}'

import requests

url = "https://sdp.suki.ai/api/v1/ambient/session/create"

payload = {
    "ambient_session_id": "123dfg-456dfg-789dfg-012dfg",
    "emr_encounter_id": "123dfg-456dfg-789dfg-012dfg",
    "encounter_id": "123dfg-456dfg-789dfg-012dfg"
}
headers = {
    "sdp_suki_token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {sdp_suki_token: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    ambient_session_id: '123dfg-456dfg-789dfg-012dfg',
    emr_encounter_id: '123dfg-456dfg-789dfg-012dfg',
    encounter_id: '123dfg-456dfg-789dfg-012dfg'
  })
};

fetch('https://sdp.suki.ai/api/v1/ambient/session/create', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sdp.suki.ai/api/v1/ambient/session/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ambient_session_id' => '123dfg-456dfg-789dfg-012dfg',
    'emr_encounter_id' => '123dfg-456dfg-789dfg-012dfg',
    'encounter_id' => '123dfg-456dfg-789dfg-012dfg'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "sdp_suki_token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sdp.suki.ai/api/v1/ambient/session/create"

	payload := strings.NewReader("{\n  \"ambient_session_id\": \"123dfg-456dfg-789dfg-012dfg\",\n  \"emr_encounter_id\": \"123dfg-456dfg-789dfg-012dfg\",\n  \"encounter_id\": \"123dfg-456dfg-789dfg-012dfg\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("sdp_suki_token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sdp.suki.ai/api/v1/ambient/session/create")
  .header("sdp_suki_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ambient_session_id\": \"123dfg-456dfg-789dfg-012dfg\",\n  \"emr_encounter_id\": \"123dfg-456dfg-789dfg-012dfg\",\n  \"encounter_id\": \"123dfg-456dfg-789dfg-012dfg\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sdp.suki.ai/api/v1/ambient/session/create")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["sdp_suki_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ambient_session_id\": \"123dfg-456dfg-789dfg-012dfg\",\n  \"emr_encounter_id\": \"123dfg-456dfg-789dfg-012dfg\",\n  \"encounter_id\": \"123dfg-456dfg-789dfg-012dfg\"\n}"

response = http.request(request)
puts response.read_body

{
  "ambient_session_id": "123dfg-456dfg-789dfg-012dfg",
  "composition_id": "123dfg-456dfg-789dfg-012dfg"
}

{
  "code": 400,
  "message": "invalid request"
}

{
  "code": 401,
  "message": "invalid token"
}

{
  "code": 500,
  "message": "internal server error"
}

​Request body fields

​Code examples

Authorizations

Headers

Body

Response

Request body fields

Code examples