---
title: "Start a voice session"
method: POST
path: "/api/v1/voice/sessions"
tags: ["Voice"]
---

# Start a voice session

`POST /api/v1/voice/sessions`

## Request

- Base URL: `https://your-deployment.example.com`
- URL: `https://your-deployment.example.com/api/v1/voice/sessions`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Opens a real-time voice conversation on the platform default voice agent, attached to an existing session (`sessionId`) or a new one, and returns the `clientBootstrap` to hand to the ElevenLabs Conversational AI SDK client-side (`Conversation.startSession`): connect with `signedUrl`, apply any overrides, and forward `sessionToken` as `custom_llm_extra_body.b4m_session`. Transcripts are appended to the session as the call runs. When credits are enforced, the maximum call length is reserved up front and reconciled down by `POST /api/v1/voice/sessions/{id}/end`, so always end the call. Pass `isReconnect: true` to re-attach a dropped transport without a second reservation. `POST /api/voice/v2/sessions` is a legacy alias of this endpoint. Authenticate with an API key (`b4m_live_`) or a JWT.

## Request body

- CreateVoiceSessionRequest
  - `sessionId` string: Attach the call to this existing session (notebook). Omit to create a new one.
  - `reasoningModelId` string: Chat model that answers each spoken turn. Defaults to the platform voice default.
  - `isReconnect` boolean: Set when re-establishing a dropped transport for the same `sessionId`: the live credit hold from the original connect is reused instead of reserving (and charging) a second time.

## Response `200`

The call is provisioned. `clientBootstrap` is consumed by the ElevenLabs Conversational AI SDK in the client; `signedUrl` is short-lived, so connect promptly.

- CreateVoiceSessionResponse200
  - `session` object, required
    - `id` string, required
    - `name` string, required
  - `reasoningModelId` string, required: The model that will answer, after any platform remap.
  - `clientBootstrap` object, required
    - `transport` 'elevenlabs-conversational', required
    - `signedUrl` string, required: Short-lived ElevenLabs signed WebSocket URL for this conversation.
    - `agentId` string, required: ElevenLabs agent the conversation runs on.
    - `voiceOverrideId` string: Caller's TTS voice override, applied via the SDK `overrides.tts.voiceId`.
    - `systemPromptOverride` string: Caller's system-prompt override, applied via the SDK `overrides.agent.prompt.prompt`.
    - `sessionToken` string, required: Signed, session-bound token to forward to ElevenLabs as `custom_llm_extra_body.b4m_session`. Treat it as a credential.

## Other responses

- `400`: No default voice agent is configured for this deployment.
- `401`: Missing or invalid credentials.
- `403`: The API key does not hold `ai:generate`, Voice is not enabled on this deployment (`voiceV2Enabled` is off), or the caller already has the maximum number of concurrent voice sessions open (end one first).
- `404`: The `sessionId` does not exist or is not owned by the caller (a malformed id is also a 404).
- `405`: The path does not serve this HTTP method.
- `409`: Another call on the same session was provisioned concurrently and holds its reservation; this request's reservation is refunded. Retry.
- `422`: Request body failed validation, or the caller cannot afford the up-front reservation - the latter is tagged `errorCode: "insufficient_credits"`.
- `502`: ElevenLabs failed to provision the conversation; any reserved credits are refunded.
- `503`: This deployment has no ElevenLabs server API key configured (`errorCode: "provider_not_configured"`).

---

[API](https://skmtc.dev/bike4mind/apis/bike4mind-api.md) · [All operations](https://skmtc.dev/bike4mind/apis/bike4mind-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bike4mind/apis/bike4mind-api/revisions/d437aaac22ac?raw)