create engine session
curl --request POST \
--url https://api.anam.ai/v1/engine/session \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"clientLabel": "<string>",
"personaConfig": {},
"environment": {
"livekitUrl": "<string>"
},
"sessionOptions": {
"sessionReplay": {
"enableSessionReplay": true
},
"dataRetention": {
"recording": false,
"transcripts": true
},
"videoQuality": "high",
"showAIAvatarDisclosure": true,
"regionPolicy": "preferred",
"videoWidth": 1152,
"videoHeight": 768
},
"clientMetadata": {}
}
'import requests
url = "https://api.anam.ai/v1/engine/session"
payload = {
"clientLabel": "<string>",
"personaConfig": {},
"environment": { "livekitUrl": "<string>" },
"sessionOptions": {
"sessionReplay": { "enableSessionReplay": True },
"dataRetention": {
"recording": False,
"transcripts": True
},
"videoQuality": "high",
"showAIAvatarDisclosure": True,
"regionPolicy": "preferred",
"videoWidth": 1152,
"videoHeight": 768
},
"clientMetadata": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
clientLabel: '<string>',
personaConfig: {},
environment: {livekitUrl: '<string>'},
sessionOptions: {
sessionReplay: {enableSessionReplay: true},
dataRetention: {recording: false, transcripts: true},
videoQuality: 'high',
showAIAvatarDisclosure: true,
regionPolicy: 'preferred',
videoWidth: 1152,
videoHeight: 768
},
clientMetadata: {}
})
};
fetch('https://api.anam.ai/v1/engine/session', 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://api.anam.ai/v1/engine/session",
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([
'clientLabel' => '<string>',
'personaConfig' => [
],
'environment' => [
'livekitUrl' => '<string>'
],
'sessionOptions' => [
'sessionReplay' => [
'enableSessionReplay' => true
],
'dataRetention' => [
'recording' => false,
'transcripts' => true
],
'videoQuality' => 'high',
'showAIAvatarDisclosure' => true,
'regionPolicy' => 'preferred',
'videoWidth' => 1152,
'videoHeight' => 768
],
'clientMetadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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://api.anam.ai/v1/engine/session"
payload := strings.NewReader("{\n \"clientLabel\": \"<string>\",\n \"personaConfig\": {},\n \"environment\": {\n \"livekitUrl\": \"<string>\"\n },\n \"sessionOptions\": {\n \"sessionReplay\": {\n \"enableSessionReplay\": true\n },\n \"dataRetention\": {\n \"recording\": false,\n \"transcripts\": true\n },\n \"videoQuality\": \"high\",\n \"showAIAvatarDisclosure\": true,\n \"regionPolicy\": \"preferred\",\n \"videoWidth\": 1152,\n \"videoHeight\": 768\n },\n \"clientMetadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://api.anam.ai/v1/engine/session")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"clientLabel\": \"<string>\",\n \"personaConfig\": {},\n \"environment\": {\n \"livekitUrl\": \"<string>\"\n },\n \"sessionOptions\": {\n \"sessionReplay\": {\n \"enableSessionReplay\": true\n },\n \"dataRetention\": {\n \"recording\": false,\n \"transcripts\": true\n },\n \"videoQuality\": \"high\",\n \"showAIAvatarDisclosure\": true,\n \"regionPolicy\": \"preferred\",\n \"videoWidth\": 1152,\n \"videoHeight\": 768\n },\n \"clientMetadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.anam.ai/v1/engine/session")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"clientLabel\": \"<string>\",\n \"personaConfig\": {},\n \"environment\": {\n \"livekitUrl\": \"<string>\"\n },\n \"sessionOptions\": {\n \"sessionReplay\": {\n \"enableSessionReplay\": true\n },\n \"dataRetention\": {\n \"recording\": false,\n \"transcripts\": true\n },\n \"videoQuality\": \"high\",\n \"showAIAvatarDisclosure\": true,\n \"regionPolicy\": \"preferred\",\n \"videoWidth\": 1152,\n \"videoHeight\": 768\n },\n \"clientMetadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"engineHost": "<string>",
"engineProtocol": "<string>",
"signallingEndpoint": "<string>",
"clientConfig": {},
"region": "eu"
}{
"error": "avatar_unusable",
"message": "Avatar avatar-1 has no engine key and cannot be used in a session. Choose a usable avatar, or create a replacement with imageUrl, then update your session configuration or saved persona to use its avatarId. The unusable avatar can be deleted once nothing references it.",
"avatarId": "avatar-1"
}{
"error": "billing_payment_required",
"message": "Your organization has an overdue payment. An owner can restore access from Billing.",
"recovery_url": "https://lab.anam.ai/subscription?billing=overdue"
}{
"error": "session_region_not_available",
"message": "Session region selection is not available for this organization"
}{
"error": "tools_not_found",
"message": "Tools not found: f56eba79-5403-40e0-9b09-6ae6c4757e21. Remove them from personaConfig.toolIds, or use the IDs of tools that exist in your organization.",
"toolIds": [
"f56eba79-5403-40e0-9b09-6ae6c4757e21"
]
}{
"error": "<string>",
"message": "<string>",
"code": "DICTIONARY_UNAVAILABLE"
}{
"error": "<string>",
"message": "<string>"
}create engine session
Start a live persona session.
Two authentication modes are supported via the Authorization: Bearer header:
- Session token (browser clients): pass a session token minted by
POST /v1/auth/session-token. The session configuration was bound to the token when it was created, so the body only carries optionalclientMetadata. This is the flow the client-side SDKs use; you normally don’t call this endpoint yourself. - API key (server-side SDKs): pass your API key directly and supply the session configuration
in the request body — the same shape as the
/v1/auth/session-tokenbody (personaConfig,environment,sessionOptions, plus optionalclientLabelandclientMetadata;expiresInSeconds,maxSessionsandwidgetConfigdo not apply). This skips the session-token exchange. Only use this from a secure server-side context — never expose an API key in a browser.
POST
/
v1
/
engine
/
session
create engine session
curl --request POST \
--url https://api.anam.ai/v1/engine/session \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"clientLabel": "<string>",
"personaConfig": {},
"environment": {
"livekitUrl": "<string>"
},
"sessionOptions": {
"sessionReplay": {
"enableSessionReplay": true
},
"dataRetention": {
"recording": false,
"transcripts": true
},
"videoQuality": "high",
"showAIAvatarDisclosure": true,
"regionPolicy": "preferred",
"videoWidth": 1152,
"videoHeight": 768
},
"clientMetadata": {}
}
'import requests
url = "https://api.anam.ai/v1/engine/session"
payload = {
"clientLabel": "<string>",
"personaConfig": {},
"environment": { "livekitUrl": "<string>" },
"sessionOptions": {
"sessionReplay": { "enableSessionReplay": True },
"dataRetention": {
"recording": False,
"transcripts": True
},
"videoQuality": "high",
"showAIAvatarDisclosure": True,
"regionPolicy": "preferred",
"videoWidth": 1152,
"videoHeight": 768
},
"clientMetadata": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
clientLabel: '<string>',
personaConfig: {},
environment: {livekitUrl: '<string>'},
sessionOptions: {
sessionReplay: {enableSessionReplay: true},
dataRetention: {recording: false, transcripts: true},
videoQuality: 'high',
showAIAvatarDisclosure: true,
regionPolicy: 'preferred',
videoWidth: 1152,
videoHeight: 768
},
clientMetadata: {}
})
};
fetch('https://api.anam.ai/v1/engine/session', 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://api.anam.ai/v1/engine/session",
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([
'clientLabel' => '<string>',
'personaConfig' => [
],
'environment' => [
'livekitUrl' => '<string>'
],
'sessionOptions' => [
'sessionReplay' => [
'enableSessionReplay' => true
],
'dataRetention' => [
'recording' => false,
'transcripts' => true
],
'videoQuality' => 'high',
'showAIAvatarDisclosure' => true,
'regionPolicy' => 'preferred',
'videoWidth' => 1152,
'videoHeight' => 768
],
'clientMetadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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://api.anam.ai/v1/engine/session"
payload := strings.NewReader("{\n \"clientLabel\": \"<string>\",\n \"personaConfig\": {},\n \"environment\": {\n \"livekitUrl\": \"<string>\"\n },\n \"sessionOptions\": {\n \"sessionReplay\": {\n \"enableSessionReplay\": true\n },\n \"dataRetention\": {\n \"recording\": false,\n \"transcripts\": true\n },\n \"videoQuality\": \"high\",\n \"showAIAvatarDisclosure\": true,\n \"regionPolicy\": \"preferred\",\n \"videoWidth\": 1152,\n \"videoHeight\": 768\n },\n \"clientMetadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://api.anam.ai/v1/engine/session")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"clientLabel\": \"<string>\",\n \"personaConfig\": {},\n \"environment\": {\n \"livekitUrl\": \"<string>\"\n },\n \"sessionOptions\": {\n \"sessionReplay\": {\n \"enableSessionReplay\": true\n },\n \"dataRetention\": {\n \"recording\": false,\n \"transcripts\": true\n },\n \"videoQuality\": \"high\",\n \"showAIAvatarDisclosure\": true,\n \"regionPolicy\": \"preferred\",\n \"videoWidth\": 1152,\n \"videoHeight\": 768\n },\n \"clientMetadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.anam.ai/v1/engine/session")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"clientLabel\": \"<string>\",\n \"personaConfig\": {},\n \"environment\": {\n \"livekitUrl\": \"<string>\"\n },\n \"sessionOptions\": {\n \"sessionReplay\": {\n \"enableSessionReplay\": true\n },\n \"dataRetention\": {\n \"recording\": false,\n \"transcripts\": true\n },\n \"videoQuality\": \"high\",\n \"showAIAvatarDisclosure\": true,\n \"regionPolicy\": \"preferred\",\n \"videoWidth\": 1152,\n \"videoHeight\": 768\n },\n \"clientMetadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"engineHost": "<string>",
"engineProtocol": "<string>",
"signallingEndpoint": "<string>",
"clientConfig": {},
"region": "eu"
}{
"error": "avatar_unusable",
"message": "Avatar avatar-1 has no engine key and cannot be used in a session. Choose a usable avatar, or create a replacement with imageUrl, then update your session configuration or saved persona to use its avatarId. The unusable avatar can be deleted once nothing references it.",
"avatarId": "avatar-1"
}{
"error": "billing_payment_required",
"message": "Your organization has an overdue payment. An owner can restore access from Billing.",
"recovery_url": "https://lab.anam.ai/subscription?billing=overdue"
}{
"error": "session_region_not_available",
"message": "Session region selection is not available for this organization"
}{
"error": "tools_not_found",
"message": "Tools not found: f56eba79-5403-40e0-9b09-6ae6c4757e21. Remove them from personaConfig.toolIds, or use the IDs of tools that exist in your organization.",
"toolIds": [
"f56eba79-5403-40e0-9b09-6ae6c4757e21"
]
}{
"error": "<string>",
"message": "<string>",
"code": "DICTIONARY_UNAVAILABLE"
}{
"error": "<string>",
"message": "<string>"
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Label for the session, recorded for usage attribution. API-key auth only.
Session persona configuration (API-key auth only). Same shape as the
/v1/auth/session-token request: supply personaId for a persona you've already
created, or avatarId/voiceId/llmId/systemPrompt for an ephemeral persona.
An avatar-only config (avatarId without voiceId and without
enableAudioPassthrough: true) is only accepted together with a LiveKit,
Agora or ElevenLabs Agent integration environment; on the default Anam
WebRTC transport send an ephemeral config with voiceId and llmId (llmId
"CUSTOMER_CLIENT_V1" for a client-side LLM) or set
enableAudioPassthrough to true. Otherwise the request fails
with 400 avatar_only_requires_integration.
Knowledge tools accept optional fixed topK (integer 1–100), minScore
(number 0–1), maxContextTokens (integer 1–200,000; content only) and
neighborChunks (integer 0–10, default 0) on each tool. Omit or set null to retain defaults. Invalid values return 400.
Inline tools are supported; each client/webhook tool's parameters (and webhook
queryParameters) JSON Schema must serialize to 10,000 bytes or less (UTF-8).
voiceGenerationOptions.pronunciationDictionaryId selects a pronunciation
dictionary for the session (see SessionPronunciationDictionary); its latest
saved entries are applied when the session starts.
Optional environment configuration (e.g. LiveKit settings). API-key auth only.
Show child attributes
Show child attributes
Optional session options for API-key-authenticated session creation, including data retention (recording and transcripts), video quality/dimensions, AI avatar disclosure, egress, and engine-region routing. For session-token authentication, configure these options when creating the token.
Show child attributes
Show child attributes
Optional client metadata forwarded to the engine (e.g. supportsPubSubSignalling).
Response
Session started
Host of the engine serving this session. Omitted for LiveKit/Agora integrations.
Actual region that served the session. Omitted when the serving session-service does not report it.
Available options:
eu, us