Skip to main content
POST
/
v1
/
sessions
Create a real-time voice session
curl --request POST \
  --url https://api.speko.dev/v1/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "intent": {
    "language": "<string>",
    "vertical": "general",
    "optimizeFor": "balanced"
  },
  "constraints": {
    "allowedProviders": {
      "stt": [
        "<string>"
      ],
      "llm": [
        "<string>"
      ],
      "tts": [
        "<string>"
      ]
    }
  },
  "voice": "<string>",
  "systemPrompt": "<string>",
  "llm": {
    "temperature": 1,
    "maxTokens": 2
  },
  "ttsOptions": {
    "sampleRate": 2,
    "speed": 1.25
  },
  "metadata": {},
  "ttlSeconds": 900,
  "identity": "<string>"
}
'
{
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "conversationToken": "<string>",
  "livekitUrl": "<string>",
  "roomName": "<string>",
  "identity": "<string>",
  "expiresAt": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
intent
object
required
constraints
object
voice
string

Force a specific TTS voice id.

systemPrompt
string

Initial agent instructions.

llm
object
ttsOptions
object
metadata
object

Arbitrary key/value pairs stored on the session row.

ttlSeconds
integer
default:900

Token TTL.

Required range: 1 <= x <= 86400
identity
string

LiveKit participant identity. Defaults to user_<uuid>.

Required string length: 1 - 128

Response

Session created

sessionId
string<uuid>
required
conversationToken
string
required

LiveKit JWT for the browser to join the room.

livekitUrl
string<uri>
required
roomName
string
required
Example:

"speko_..."

identity
string
required
expiresAt
string<date-time>
required