Create Session | SpeechifyAI API

curl -X POST https://api.speechify.ai/v1/agents/agent_01jqr8x9zg5k2m3n4p5q6r7s8t/sessions \
     -H "Content-Type: application/json" \
     -d '{
  "user_identity": "example",
  "dynamic_variables": {
    "product_name": "Acme Pro",
    "support_tier": 2
  }
}'

{
  "conversation": {
    "id": "conv_01kr410dd3yrst4chn5kn0t78f",
    "agent_id": "agent_01jqr8x9zg5k2m3n4p5q6r7s8t",
    "status": "pending",
    "transport": "web",
    "created_at": "2026-06-24T18:03:11Z",
    "metadata": {},
    "message_count": 10,
    "started_at": "2026-06-24T18:03:11Z",
    "ended_at": "2026-06-24T18:03:11Z",
    "duration_ms": 5000,
    "cost_cents": 1,
    "recording_url": "example",
    "recording_started_at": "2026-06-24T18:03:11Z",
    "caller_identity": "example",
    "from_number": "example",
    "to_number": "example",
    "agent_snapshot": {
      "schema_version": 1,
      "captured_at": "2026-06-24T18:03:11Z",
      "name": "Example name",
      "prompt": "example",
      "first_message": "example",
      "language": "en-US",
      "llm_provider": "example",
      "llm_model": "gpt-4o",
      "llm_base_url": "example",
      "llm_extra_body": {},
      "voice_id": "voice_01jqr8x9zg5k2m3n4p5q6r7s8t",
      "temperature": 1,
      "memory_enabled": true,
      "memory_retention_days": 1,
      "tts_playback_rate": 1,
      "response_delay_seconds": 1,
      "stt_override": "example",
      "amd": {
        "enabled": true,
        "on_voicemail": {
          "action": "hangup"
        },
        "on_ivr": {
          "action": "proceed"
        },
        "on_unavailable": {
          "action": "hangup"
        }
      },
      "save_audio_recording": true,
      "navigator_mode": true,
      "ivr_memory_enabled": true,
      "inactivity_timeout_seconds": 30,
      "background_noise_preset": "office",
      "background_noise_volume": 1
    },
    "dynamic_variables": {},
    "ivr_menu_id": "menu_01jqr8x9zg5k2m3n4p5q6r7s8t",
    "ivr_path_taken": [
      {}
    ]
  },
  "token": "tok_01jqr8x9zg5k2m3n4p5q6r7s8t",
  "url": "https://example.com/webhook"
}

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

agent_idstringRequired

Agent id (prefixed external id, agent_...).

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 headers

X-Request-IDstring

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an X-Request-ID request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an `X-Request-ID` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope.

RateLimit-Limit-Callsinteger

Active-call concurrency budget: the per-workspace cap on simultaneously-active voice calls (the voice analog of a token axis). Sent on successful call-start responses (web session, outbound call).

RateLimit-Remaining-Callsinteger

Active-call concurrency budget: free active-call slots after this call reserved one. 0 on a 429 that rejected for concurrency exhaustion (concurrency_limit_reached).

Response

The created session with its realtime token + URL.

conversationobject

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