Skip to main content
POST
Create a voice session

Authorizations

Authorization
string
header
required

Organization API key. Keep it on your server.

Headers

Idempotency-Key
string
required

Unique ID for one intended launch. Reuse this key and the identical body when retrying that launch.

Required string length: 1 - 200

Body

application/json
voice_id
string<uuid>
required

Voice UUID available to the organization.

face_id
string<uuid> | null

Compatible face UUID; omit or use null for audio only.

prompt
string | null

Instructions for this conversation. Omit or use null for voice defaults; text must not be blank.

Required string length: 1 - 32000
greeting
string | null

Omit for the standard greeting; null disables it. Nonblank custom text is delivered according to the selected voice.

Required string length: 1 - 500
mcps
object[]

Connections and tools available for this session. Each connection may appear once.

Maximum array length: 8
participant_identity
string
default:browser

Identity for the participant joining the room.

Required string length: 1 - 100
tags
string[]

Application labels.

Maximum array length: 20
metadata
object

Application context; exclude secrets.

Response

Successful response

id
string<uuid>
required

Use this session ID for status, token refresh, end, and transcript requests.

status
enum<string>
required
Available options:
created,
active,
completed,
failed,
cancelled
room_name
string
required

Room name for the connection.

livekit_url
string<uri>
required

LiveKit connection URL returned by the service.

participant_token
string | null
required

Short-lived participant credential, or null after the session becomes terminal.

created_at
string<date-time>
required
started_at
string<date-time> | null
required
ended_at
string<date-time> | null
required
workflow_run_id
string<uuid> | null

Present for a workflow session; identifies its workflow run.