Sessions

Creates either a provider-direct S2S session with a scoped OpenAI, Gemini Live, or xAI credential, or a cascade session with browser-safe LiveKit transport credentials.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Header Parameters

Idempotency-Key?string

Required when the session resolves to s2s. Reuse the same value after an ambiguous timeout to recover the same reservation.

Lengthlength <= 256

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

mode?string

Creates the LiveKit-backed STT → LLM → TTS pipeline. Optional for backward compatibility.

agentId?string

Optional pointer to a persisted agent row whose fields seed this session. When supplied, the agent's systemPrompt, voice, intent, and llmOptions become defaults; any per-call field on this body overrides the agent's stored value. When absent, intent is required.

intent?

constraints?

voice?string

Force a specific TTS voice id.

systemPrompt?string

Initial agent instructions.

llm?

ttsOptions?

turnHandling?

Per-call turn-taking posture for a browser session. Replaces the agent's stored turnHandling wholesale for this session.

webhookTags?

Case-sensitive routing tags for workspace webhook endpoints. Requires agentId.

Propertiesproperties <= 20

metadata?

Arbitrary key/value pairs stored on the session row.

ttlSeconds?integer

Join-token TTL. Bounds how long the returned transport token stays valid to connect — not how long the session may run. Use maxDurationSeconds to cap connected duration.

Default900

Range1 <= value <= 86400

maxDurationSeconds?integer

Hard cap on session lifetime in seconds, measured from session creation (not from client connect). The session is force-ended when the deadline passes, even if the client stays connected — a client that joins late gets the remainder. Billing accrues per second from session creation (on an outbound phone call that includes dialing and ringing; failed sessions and carrier-refused dials are not billed), so this is the spend guardrail for abandoned clients.

Default3600

Range30 <= value <= 14400

identity?string

Transport participant identity. Defaults to user_<uuid>.

Length1 <= length <= 128

mode?string

Creates a provider-direct S2S session. Optional when agentId resolves to an S2S agent.

agentId?string

Optional persisted agent whose prompt, voice, language intent, and registered tools seed the S2S session.

Length1 <= length

intent?

constraints?

s2s?

Provider-native S2S configuration. Omit both provider and model to let Speko route; if either is supplied, both are required.

webhookTags?

Case-sensitive workspace webhook routing tags. Requires agentId.

Propertiesproperties <= 20

metadata?

Arbitrary key/value pairs stored on the session row.

ttlSeconds?integer

Requested maximum S2S session horizon. The returned entitlement or provider credential may authorize a shorter initial slice.

Default1800

Range1 <= value <= 3600

Response Body

`application/json`

{
  "mode": "cascade",
  "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
  "transportToken": "string",
  "transportUrl": "http://example.com",
  "conversationToken": "string",
  "livekitUrl": "http://example.com",
  "roomName": "speko_...",
  "identity": "string",
  "expiresAt": "2019-08-24T14:15:22Z"
}

{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}

{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}

Empty

{
  "error": "Failed to dispatch voice agent",
  "code": "SESSION_CREATE_FAILED"
}

Empty

Authorization

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

402

403

409

422

429

500application/json

502

503

`application/json`

`application/json`

`application/json`

`application/json`