Sessions

Mints browser-safe media transport credentials, persists the pipeline config, and dispatches an agent worker. Use the returned `transportToken` and `transportUrl` with `@spekoai/client` to join from a browser.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

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?

metadata?

Arbitrary key/value pairs stored on the session row.

ttlSeconds?integer

Token TTL.

Default900

Range1 <= value <= 86400

identity?string

Transport participant identity. Defaults to user_<uuid>.

Length1 <= length <= 128

Response Body

`application/json`

{
  "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"
}

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

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`