Anam.ai Sessions API
The Sessions API from Anam.ai — 9 operation(s) for sessions.
OpenAPI Specification
openapi: 3.1.0
info:
title: Anam AI Avatars Sessions API
version: '1.0'
servers:
- url: https://api.anam.ai
description: Anam API
security:
- BearerAuth: []
tags:
- name: Sessions
paths:
/v1/auth/session-token:
post:
description: Create a new session token used to initialise Anam client side SDKs
requestBody:
description: 'Configuration for the session to be created. Supply `personaConfig.personaId` to use a persona you''ve already created (stateful), or the set `avatarId`/`voiceId`/`llmId`/`systemPrompt` to configure the persona at run time (ephemeral).
The returned token is valid for one hour and bound to this exact config.
Server-side SDKs in a secure context can skip this exchange and start a session directly by calling `POST /v1/engine/session` with their API key and the same configuration in the request body.
'
required: true
content:
application/json:
examples:
default:
$ref: '#/components/examples/SessionTokenCreate'
schema:
type: object
properties:
clientLabel:
type: string
description: The client label for the session
personaConfig:
oneOf:
- type: object
properties:
name:
type: string
example: Cara
avatarId:
type: string
example: 071b0286-4cce-4808-bee2-e642f1062de3
avatarModel:
type: string
example: cara-4
description: Avatar model version. `cara-3` and `cara-4` are generally available; models with the '-latest' suffix are invite only and require organization-level access.
enum:
- cara-3
- cara-4
- cara-4-latest
voiceId:
type: string
example: de23e340-1416-4dd8-977d-065a7ca11697
llmId:
type: string
example: a7cf662c-2ace-4de1-a21e-ef0fbf144bb7
systemPrompt:
type: string
example: You are a helpful assistant
maxSessionLengthSeconds:
type: number
example: 600
skipGreeting:
type: boolean
example: false
uninterruptibleGreeting:
type: boolean
description: When true, the greeting message cannot be interrupted by the user.
example: false
initialMessage:
type: string
nullable: true
description: Custom first message the persona speaks to open the conversation. If empty or not provided, the persona generates its own greeting.
example: Hi there! I'm excited to chat with you today.
voiceDetectionOptions:
$ref: '#/components/schemas/VoiceDetectionOptions'
languageCode:
type: string
description: ISO 639-1 formatted language code override for transcription, replaces organisation level settings and multilingual (default) mode.
voiceGenerationOptions:
description: Configuration options for voice generation.
oneOf:
- $ref: '#/components/schemas/ElevenLabsV1VoiceGenerationOptions'
- $ref: '#/components/schemas/ElevenLabsV2VoiceGenerationOptions'
- $ref: '#/components/schemas/CartesiaSonic3VoiceGenerationOptions'
- $ref: '#/components/schemas/FishAudioVoiceGenerationOptions'
directorNotes:
type: object
description: Per-session performance overrides for the avatar. Only applied on cara-4 avatars (avatarModel `cara-4` or `cara-4-latest`); if set on a cara-3 avatar they are ignored (silently stripped) and the session proceeds without them. `presetStyle` and `customStylePrompt` are mutually exclusive. These work best when the selected voice matches the intended performance.
properties:
presetStyle:
type: string
enum:
- happy
- warm
- playful
- supportive
- sad
- angry
- distressed
description: Built-in performance style for the avatar to follow. Mutually exclusive with customStylePrompt. Works best with a matching voice, which we've labelled as expressive.
example: warm
customStylePrompt:
type: string
maxLength: 2000
description: Free-form performance style prompt for the avatar to follow. Mutually exclusive with presetStyle. Works best with a matching voice, which we've labelled as expressive.
example: Warm smile, composed, slightly amused, looking directly at camera
expressivity:
type: number
minimum: 0
maximum: 1
description: Controls how closely the avatar follows the selected style or cue. 0 is subtle, 1 follows it most strongly and can become unstable; omit the field to use the default. Works best with a matching voice, which we've labelled as expressive.
example: 0.5
tools:
type: array
description: Runtime tool definitions made available to the persona for this session. Each item is one of a client tool, a server knowledge tool, a server webhook tool, or a system tool. For client and webhook tools, `parameters` (and, for webhook tools, `queryParameters`) is a JSON Schema object the LLM fills at call time; each such object must serialize to 10,000 bytes or less (UTF-8), otherwise the request is rejected. Use `toolIds` instead to reference tools you've pre-created via `/v1/tools` (those are not subject to this inline size limit).
items:
type: object
required:
- type
- name
additionalProperties: true
properties:
type:
type: string
enum:
- client
- server
- system
description: Tool kind. `server` tools additionally set `subtype` (`knowledge` or `webhook`).
name:
type: string
description: Unique tool name the LLM calls.
description:
type: string
maxLength: 1024
parameters:
type: object
description: JSON Schema for the arguments the LLM provides (client and webhook tools). Must serialize to 10,000 bytes or less.
example:
- type: client
name: open_calendar
description: Open the calendar UI in the client app.
parameters:
type: object
properties:
date:
type: string
description: Date to jump to, in YYYY-MM-DD format.
toolIds:
type: array
description: IDs of tools pre-created via `/v1/tools` to make available to the persona for this session.
items:
type: string
format: uuid
- type: object
properties:
personaId:
type: string
sessionOptions:
type: object
properties:
sessionReplay:
type: object
properties:
enableSessionReplay:
type: boolean
example: true
default: true
videoQuality:
type: string
enum:
- high
- auto
description: '''high'' pins highest bitrate, ''auto'' enables adaptive bitrate.'
example: high
videoWidth:
type: integer
description: 'Output video frame width in pixels. Supply together with `videoHeight` (both or neither). Omit to use the avatar model''s default. Supported pairs depend on the avatar model — cara-3: `720x480`; cara-4: `1152x768`. Unsupported pairs are rejected (the session is not silently downgraded).'
example: 1152
videoHeight:
type: integer
description: Output video frame height in pixels. Supply together with `videoWidth` (both or neither). See `videoWidth`.
example: 768
egress:
type: object
description: 'Set egress to an alternative egress transport mode. The avatar''s audio/video are published to
a 3rd party transport and not delivered over the native webRTC channel.
The WebRTC peer connection still exists for signalling and the data channel (interrupts, status).
Requires `personaConfig.enableAudioPassthrough=true`. Discriminated on `mode`.
'
required:
- mode
properties:
mode:
type: string
enum:
- daily
description: Egress provider. Only `daily` is supported today.
example: daily
daily:
type: object
description: Required when `mode` is `daily`.
required:
- roomUrl
properties:
roomUrl:
type: string
format: uri
description: Daily room URL the avatar should join as a publisher.
example: https://your-domain.daily.co/avatar-room
token:
type: string
description: Optional Daily meeting token. Omit for public rooms.
userName:
type: string
description: Optional display name for the avatar participant. Defaults to "anam-avatar".
responses:
'200':
description: Successfully started session
content:
application/json:
schema:
$ref: '#/components/schemas/SessionToken'
examples:
default:
$ref: '#/components/examples/SessionTokenResponse'
'400':
description: Invalid request body
'401':
description: Unauthorized - Invalid or missing API key
'403':
description: Forbidden - API key lacks the required permission, the session config is not authorized for the organization, or the plan does not permit the requested option.
'500':
description: 'Server error. Note: currently any non-validation error is returned as a 500, eventhough the error might be due to joining the room or related to token validation.'
tags:
- Sessions
operationId: createSessionToken
summary: create session token
x-mint:
metadata:
title: create session token
mcp:
enabled: true
name: create-session-token
description: Create a new session token used to initialise Anam client side SDKs
/v1/sessions:
get:
description: Returns a list of all sessions for the organization
parameters:
- in: query
name: page
schema:
type: integer
minimum: 1
default: 1
description: Page number for pagination
- in: query
name: perPage
schema:
type: integer
minimum: 1
maximum: 100
default: 10
description: Number of items per page (max 100)
- in: query
name: search
schema:
type: string
description: Search term to filter sessions by ID or client label
- in: query
name: apiKeyId
schema:
type: string
format: uuid
description: Filter sessions by API key ID
- in: query
name: personaId
schema:
type: string
format: uuid
description: Filter sessions by persona ID
- in: query
name: organizationId
schema:
type: string
description: List sessions of another organization. Restricted to Anam-internal admin API keys; other keys receive 403.
responses:
'200':
description: Successfully retrieved sessions
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Session'
meta:
$ref: '#/components/schemas/Pagination'
examples:
default:
$ref: '#/components/examples/SessionListResponse'
'400':
description: Bad request - Invalid query parameters
'401':
description: Unauthorized - Invalid or missing API key
'403':
description: Forbidden - API key lacks the required permission
'500':
description: Server error
tags:
- Sessions
operationId: listSessions
summary: list sessions
x-mint:
metadata:
title: list sessions
mcp:
enabled: true
name: list-sessions
description: Returns a list of all sessions for the organization
/v1/sessions/concurrency:
get:
summary: Get current concurrency status
description: Returns the organization's concurrent-session limit, an approximate count of sessions currently in use, whether a new session can likely be started, and an estimated wait time until a slot frees. Intended as an advisory pre-check before starting a session (e.g. to gate a "Start" button or show a wait estimate). The count is the Lab's optimistic view and can briefly over-report; the authoritative limit is enforced when a session is actually created, which may still return 429.
parameters:
- in: query
name: organizationId
schema:
type: string
description: Report the concurrency status of another organization. Restricted to Anam-internal admin API keys; other keys receive 403.
responses:
'200':
description: Current concurrency status for the organization
content:
application/json:
schema:
$ref: '#/components/schemas/ConcurrencyStatus'
'401':
description: Unauthorized - Invalid or missing API key
'403':
description: Forbidden - API key lacks the required permission
'500':
description: Server error
tags:
- Sessions
operationId: getSessionConcurrency
x-mint:
metadata:
title: get session concurrency status
mcp:
enabled: true
name: get-session-concurrency
description: Returns the organization's concurrent-session limit, an approximate count of sessions currently in use, whether a new session can likely be started, and an estimated wait time until a slot frees. Intended as an advisory pre-check before starting a session (e.g. to gate a "Start" button or show a wait estimate). The count is the Lab's optimistic view and can briefly over-report; the authoritative limit is enforced when a session is actually created, which may still return 429.
/v1/sessions/analytics:
get:
description: Returns aggregated latency analytics across sessions — percentile distributions (p50/p90/p95/p99/max/avg) for each stage of the transcription → LLM → TTS → first-audio path, interruption and error rates, tool call outcomes, and a sample of the slowest turns. Only sessions where Anam runs the conversational pipeline (turnkey, custom LLM and ElevenLabs agent sessions) produce analytics reports; LiveKit and audio-passthrough sessions count toward `sessionCount` but never carry analytics. Defaults to the last 24 hours; the maximum range is 31 days. Reports are aggregated from the 1000 most recent report-capable sessions matching the filters — session types that never produce reports don't consume that window — and the `truncated` field reports when more report-capable sessions matched. Narrow the time range or filters to analyse busier periods exhaustively.
parameters:
- in: query
name: from
schema:
type: string
format: date-time
description: Start of the time range (ISO 8601). Defaults to 24 hours before `to`.
- in: query
name: to
schema:
type: string
format: date-time
description: End of the time range (ISO 8601). Defaults to now.
- in: query
name: personaId
schema:
type: string
format: uuid
description: Only include sessions for this persona.
- in: query
name: apiKeyId
schema:
type: string
format: uuid
description: Only include sessions minted by this API key.
- in: query
name: clientLabel
schema:
type: string
description: Only include sessions whose client label matches exactly.
- in: query
name: sessionType
schema:
type: string
enum:
- turnkey
- custom_llm_server
- custom_llm_client
- livekit
- elevenlabs_agent
description: Only include sessions of this type.
- in: query
name: organizationId
schema:
type: string
description: Aggregate sessions of another organization. Restricted to Anam-internal admin API keys; other keys receive 403.
responses:
'200':
description: Successfully computed aggregate analytics
content:
application/json:
schema:
type: object
properties:
from:
type: string
format: date-time
to:
type: string
format: date-time
filters:
type: object
description: Echo of the applied filters.
properties:
personaId:
type:
- string
- 'null'
apiKeyId:
type:
- string
- 'null'
clientLabel:
type:
- string
- 'null'
sessionType:
type:
- string
- 'null'
sessionCount:
type: integer
description: Total sessions matching the filters in the range, whether or not they produced an analytics report.
sessionsWithReports:
type: integer
description: Sessions whose analytics report was aggregated. Reports are read from the 1000 most recent report-capable matching sessions; session types that never produce reports don't consume that window.
truncated:
type: boolean
description: True when more than 1000 report-capable sessions matched; only reports among the most recent 1000 of them were aggregated.
turnCount:
type: integer
latencies:
type: object
description: Percentile distributions per latency stage, computed across all turns.
properties:
transcriptionLatencySeconds:
$ref: '#/components/schemas/LatencyStats'
llmTimeToFirstOutputSeconds:
$ref: '#/components/schemas/LatencyStats'
llmGenerationDurationSeconds:
$ref: '#/components/schemas/LatencyStats'
ttsGenerationDurationSeconds:
$ref: '#/components/schemas/LatencyStats'
ttsTimeToFirstAudioSeconds:
$ref: '#/components/schemas/LatencyStats'
firstAudioLatencySeconds:
$ref: '#/components/schemas/LatencyStats'
speakingDurationSeconds:
$ref: '#/components/schemas/LatencyStats'
userSpeechDurationSeconds:
$ref: '#/components/schemas/LatencyStats'
counts:
type: object
properties:
completedTurns:
type: integer
interruptedTurns:
type: integer
interruptedBeforeAudioTurns:
type: integer
description: Turns interrupted before the persona started speaking.
totalErrors:
type: integer
totalWarnings:
type: integer
sessionsWithErrors:
type: integer
sessionsWithWarnings:
type: integer
toolCalls:
type: object
properties:
total:
type: integer
succeeded:
type: integer
failed:
type: integer
byName:
type: object
additionalProperties:
type: integer
rates:
type: object
properties:
interruptionRate:
type:
- number
- 'null'
interruptedBeforeAudioRate:
type:
- number
- 'null'
errorSessionRate:
type:
- number
- 'null'
warningSessionRate:
type:
- number
- 'null'
toolCallFailureRate:
type:
- number
- 'null'
slowestTurns:
type: array
description: The slowest turns per headline latency metric, for jumping straight to problem sessions.
items:
type: object
properties:
sessionId:
type: string
format: uuid
correlationId:
type:
- string
- 'null'
metric:
type: string
enum:
- transcriptionLatencySeconds
- llmTimeToFirstOutputSeconds
- ttsTimeToFirstAudioSeconds
- firstAudioLatencySeconds
valueSeconds:
type: number
sessionStartTime:
type: string
format: date-time
personaId:
type:
- string
- 'null'
clientLabel:
type:
- string
- 'null'
examples:
default:
$ref: '#/components/examples/SessionAnalyticsAggregateResponse'
'400':
description: Bad request - Invalid query parameters or date range
'401':
description: Unauthorized - Invalid or missing API key
'403':
description: Forbidden - API key lacks the required permission
'500':
description: Server error
tags:
- Sessions
operationId: getAggregatedSessionAnalytics
summary: get aggregated session analytics
x-mint:
metadata:
title: get aggregated session analytics
mcp:
enabled: true
name: get-aggregated-session-analytics
description: Returns aggregated latency analytics across sessions — percentile distributions (p50/p90/p95/p99/max/avg) for each stage of the transcription → LLM → TTS → first-audio path, interruption and error rates, tool call outcomes, and a sample of the slowest turns. Only sessions where Anam runs the conversational pipeline (turnkey, custom LLM and ElevenLabs agent sessions) produce analytics reports; LiveKit and audio-passthrough sessions count toward `sessionCount` but never carry analytics. Defaults to the last 24 hours; the maximum range is 31 days. Reports are aggregated from the 1000 most recent report-capable sessions matching the filters — session types that never produce reports don't consume that window — and the `truncated` field reports when more report-capable sessions matched. Narrow the time range or filters to analyse busier periods exhaustively.
/v1/sessions/{id}:
get:
description: Returns a session by ID, including the tool calls made during the session once it has ended and the engine has delivered its session report (`toolCalls` is empty until then, and always empty for LiveKit and audio-passthrough sessions, which never produce a report). Tool call names, timing, status and errors are always included; call arguments, results and accessed-document names are only included when transcripts were enabled for the session and the session is not zero-data-retention, since they embed conversation content. HTTP headers and credential-like keys are never returned. Anam-internal admin API keys may fetch sessions of any organization.
parameters:
- in: path
name: id
schema:
type: string
format: uuid
required: true
description: Session ID
responses:
'200':
description: Successfully retrieved session
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Session'
- type: object
properties:
toolCalls:
type: array
description: Tool calls made during the session, in conversational order. Empty until the session has ended and its report has been delivered.
items:
$ref: '#/components/schemas/SessionToolCallDetail'
examples:
default:
$ref: '#/components/examples/SessionResponse'
'400':
description: Bad request - Invalid session ID
'401':
description: Unauthorized - Invalid or missing API key
'403':
description: Forbidden - API key lacks the required permission
'404':
description: Not Found - Session not found
'500':
description: Server error
tags:
- Sessions
operationId: getSession
summary: get session
x-mint:
metadata:
title: get session
mcp:
enabled: true
name: get-session
description: Returns a session by ID, including the tool calls made during the session once it has ended and the engine has delivered its session report (`toolCalls` is empty until then, and always empty for LiveKit and audio-passthrough sessions, which never produce a report). Tool call names, timing, status and errors are always included; call arguments, results and accessed-document names are only included when transcripts were enabled for the session and the session is not zero-data-retention, since they embed conversation content. HTTP headers and credential-like keys are never returned. Anam-internal admin API keys may fetch sessions of any organization.
/v1/sessions/{id}/transcript:
get:
description: Returns the conversation transcript for a session. Anam-internal admin API keys may fetch transcripts for sessions of any organization.
parameters:
- in: path
name: id
schema:
type: string
format: uuid
required: true
description: Session ID
responses:
'200':
description: Successfully retrieved transcript
content:
application/json:
schema:
type: object
properties:
sessionId:
type: string
description: The session ID
personaName:
type: string
description: Name of the persona in the session
startTime:
type: string
format: date-time
description: Session start time
endTime:
type:
- string
- 'null'
format: date-time
description: Session end time
durationMs:
type:
- integer
- 'null'
description: Session duration in milliseconds
totalMessages:
type: integer
description: Total number of messages in the transcript
transcriptsEnabled:
type: boolean
description: Whether transcripts were enabled for this session
messages:
type: array
items:
type: object
properties:
role:
type: string
enum:
- user
# --- truncated at 32 KB (77 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/anamai/refs/heads/main/openapi/anamai-sessions-api-openapi.yml