Create Session | Speechify API

curl -X POST https://api.speechify.ai/v1/agents/id/sessions \
     -H "Content-Type: application/json" \
     -d '{}'

{
  "conversation": {
    "id": "conv_01kr410dd3yrst4chn5kn0t78f",
    "agent_id": "string",
    "room_name": "string",
    "status": "pending",
    "transport": "web",
    "created_at": "2024-01-15T09:30:00Z",
    "metadata": {},
    "message_count": 1,
    "room_sid": "string",
    "started_at": "2024-01-15T09:30:00Z",
    "ended_at": "2024-01-15T09:30:00Z",
    "duration_ms": 1,
    "cost_cents": 1,
    "recording_url": "string",
    "recording_started_at": "2024-01-15T09:30:00Z",
    "end_reason": null,
    "caller_identity": "string",
    "agent_snapshot": {
      "schema_version": 1,
      "captured_at": "2024-01-15T09:30:00Z",
      "name": "string",
      "prompt": "string",
      "first_message": "string",
      "language": "string",
      "llm_model": "string",
      "voice_id": "string",
      "temperature": 1.1,
      "memory_enabled": true,
      "memory_retention_days": 1,
      "tts_speaking_rate": 1.1,
      "tts_playback_rate": 1.1,
      "response_delay_seconds": 1.1
    },
    "dynamic_variables": {},
    "ivr_menu_id": "string",
    "ivr_path_taken": [
      {}
    ],
    "ivr_surrender_reason": null
  },
  "room": "string",
  "token": "string",
  "url": "string"
}

Mint a realtime voice session for the given agent. Widget-friendly counterpart to createConversation — same response shape, dual authentication:

Authenticated (Bearer): works for any agent the caller owns. Typical server-to-server flow where the embedding site’s backend mints a token and hands it to the browser so the API key never reaches the client.
Unauthenticated: works only when agent.is_public = true AND the request’s Origin header matches agent.allowed_origins (or that list is empty). When agent.hostname_allowlist is non-empty, the Origin hostname must additionally be a member of that list. Used directly by the <speechify-agent> web component.

Responds with the same CreateConversationResponse as createConversation.

Mint a realtime voice session for the given agent. Widget-friendly counterpart to `createConversation` — same response shape, dual authentication: * **Authenticated (Bearer)**: works for any agent the caller owns. Typical server-to-server flow where the embedding site's backend mints a token and hands it to the browser so the API key never reaches the client. * **Unauthenticated**: works only when `agent.is_public = true` AND the request's `Origin` header matches `agent.allowed_origins` (or that list is empty). When `agent.hostname_allowlist` is non-empty, the `Origin` hostname must additionally be a member of that list. Used directly by the `<speechify-agent>` web component. Responds with the same `CreateConversationResponse` as `createConversation`.

Path parameters

idstringRequired

Request

This endpoint expects an object.

user_identitystringOptional

Opaque identifier for the end-user (e.g. your app’s user ID). Stamped onto the conversation. Optional - defaults to an anonymous per-session ID.

dynamic_variablesmap from strings to anyOptional

Per-session variable overrides that merge on top of the agent’s stored variable defaults for this one session. Keys in the reserved system__ namespace are rejected at this boundary. Values must match the declared type of the corresponding variable definition on the agent (a string type expects a JSON string, number expects a JSON number, etc.).

Response

The created session with its realtime token + URL.

conversationobject

roomstring

tokenstring

Short-lived realtime session access token (JWT).

urlstring

Realtime session wss:// URL to connect to.

Errors

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

Mint a realtime voice session for the given agent. Widget-friendly counterpart to createConversation — same response shape, dual authentication:

Authenticated (Bearer): works for any agent the caller owns. Typical server-to-server flow where the embedding site’s backend mints a token and hands it to the browser so the API key never reaches the client.
Unauthenticated: works only when agent.is_public = true AND the request’s Origin header matches agent.allowed_origins (or that list is empty). When agent.hostname_allowlist is non-empty, the Origin hostname must additionally be a member of that list. Used directly by the <speechify-agent> web component.

Responds with the same CreateConversationResponse as createConversation.