> ## Documentation Index > Fetch the complete documentation index at: https://developers.nlpearl.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Stream Token > The first step of a stream call: creates the call and returns the WebSocket `url`, a single-use `token` valid 60 seconds, and the audio format. Requires the `pearls:stream` scope. Then open `url?token=` within 60 seconds: [Stream WebSocket](/api-reference/v2/stream/websocket) describes the connection, the audio and the events. ## Errors A `400` lists its messages in `errors.validation`. Several `callData` problems are reported together. | Message in `errors.validation` | Cause | | --- | --- | | `Pearl not found` | `pearlId` is not a valid id, none of your Pearls has it, or the Pearl was deleted. | | `Stream calls are available for voice Pearls only.` | Your Pearl is a text Pearl. | | `The Pearl is not active.` | Your Pearl is paused. Activate it with [Set Activity State](/api-reference/v2/pearl/set-activity-state). | | `endUserId must not exceed 200 characters.` | `endUserId` is longer than 200 characters. | | `audioFormat 'X' is not supported. Valid: ulaw_8000, pcm_24000, opus_8000, opus_24000.` | `audioFormat` is not one of the four formats. | | `callData key cannot be null or whitespace.`
`callData key 'K' must not exceed 40 characters.`
`callData key 'K' contains invalid characters. Only letters, digits, underscores (_) and hyphens (-) are allowed.`
`callData value for key 'K' must not exceed 200 characters.` | A `callData` entry is invalid. | | `Missing pre-call variables: firstName, orderId.` | Required `callData` entries are absent or blank. | | `Call cannot be completed: The client has no remaining credits. Please recharge to continue.` | The account has no credits left. | | `Call cannot be completed: Account Suspended! Please contact support.` | The account is suspended. | | `The Pearl has no flow yet.`
`Invalid Conversation Flow` | Your Pearl has no usable flow. | | `The Pearl has no inbound settings.`
`The Pearl has no outbound settings.` | Your Pearl's direction settings are missing. | | `No agent is available for this Pearl right now, try again later.` | All your Pearl's [agents](/pages/agents) are busy, phone calls and stream calls together, or it has none. Retry later. | | `Could not start the call.` | An internal failure. The agent it reserved stays taken for about 90 seconds, so a retry may get `No agent is available…` until then. | Malformed JSON or a field of the wrong type (a number as `audioFormat`, for example) get the standard `400`, with the error under the field name. ## Agents and cancelling A successful create reserves one of your Pearl's [agents](/pages/agents) until the call ends. To cancel the call, before or during it, use [Hang Up Call](/api-reference/v2/call/hangup-call): a token that was never used is then refused, and its agent is freed. A token that is never used and never cancelled keeps the agent for about 90 seconds, and costs nothing. A create refused with `No agent is available…` or `Could not start the call.` still appears in the call history, as a call that never started. ## OpenAPI ````yaml post /v2/Pearl/{pearlId}/Stream/Token openapi: 3.0.1 info: title: NLPearl Client API description: A sample API that demonstrates features in the OpenAPI specification version: v2 servers: - url: https://api.nlpearl.ai description: Production Environement security: - bearer_auth: [] - oauth2_client_credentials: [] tags: - name: Pearl description: >- Manage your Pearls, the AI agents that handle your inbound and outbound calls. Create and configure Pearls, retrieve their details and settings, run or pause them, list and bulk-export their calls, monitor calls in progress, get analytics, and reset a customer's conversation memory. - name: Speech description: >- Turn text into speech with your voices, as a single clip or as a stream, and clone new voices from a recording. paths: /v2/Pearl/{pearlId}/Stream/Token: post: tags: - Pearl summary: Create Stream Token description: "The first step of a stream call: creates the call and returns the WebSocket `url`, a single-use `token` valid 60 seconds, and the audio format. Requires the `pearls:stream` scope.\r\n\r\nThen open `url?token=` within 60 seconds: [Stream WebSocket](/api-reference/v2/stream/websocket) describes the connection, the audio and the events.\r\n\r\n## Errors\r\n\r\nA `400` lists its messages in `errors.validation`. Several `callData` problems are reported together.\r\n\r\n| Message in `errors.validation` | Cause |\r\n| --- | --- |\r\n| `Pearl not found` | `pearlId` is not a valid id, none of your Pearls has it, or the Pearl was deleted. |\r\n| `Stream calls are available for voice Pearls only.` | Your Pearl is a text Pearl. |\r\n| `The Pearl is not active.` | Your Pearl is paused. Activate it with [Set Activity State](/api-reference/v2/pearl/set-activity-state). |\r\n| `endUserId must not exceed 200 characters.` | `endUserId` is longer than 200 characters. |\r\n| `audioFormat 'X' is not supported. Valid: ulaw_8000, pcm_24000, opus_8000, opus_24000.` | `audioFormat` is not one of the four formats. |\r\n| `callData key cannot be null or whitespace.`
`callData key 'K' must not exceed 40 characters.`
`callData key 'K' contains invalid characters. Only letters, digits, underscores (_) and hyphens (-) are allowed.`
`callData value for key 'K' must not exceed 200 characters.` | A `callData` entry is invalid. |\r\n| `Missing pre-call variables: firstName, orderId.` | Required `callData` entries are absent or blank. |\r\n| `Call cannot be completed: The client has no remaining credits. Please recharge to continue.` | The account has no credits left. |\r\n| `Call cannot be completed: Account Suspended! Please contact support.` | The account is suspended. |\r\n| `The Pearl has no flow yet.`
`Invalid Conversation Flow` | Your Pearl has no usable flow. |\r\n| `The Pearl has no inbound settings.`
`The Pearl has no outbound settings.` | Your Pearl's direction settings are missing. |\r\n| `No agent is available for this Pearl right now, try again later.` | All your Pearl's [agents](/pages/agents) are busy, phone calls and stream calls together, or it has none. Retry later. |\r\n| `Could not start the call.` | An internal failure. The agent it reserved stays taken for about 90 seconds, so a retry may get `No agent is available…` until then. |\r\n\r\nMalformed JSON or a field of the wrong type (a number as `audioFormat`, for example) get the standard `400`, with the error under the field name.\r\n\r\n## Agents and cancelling\r\n\r\nA successful create reserves one of your Pearl's [agents](/pages/agents) until the call ends. To cancel the call, before or during it, use [Hang Up Call](/api-reference/v2/call/hangup-call): a token that was never used is then refused, and its agent is freed. A token that is never used and never cancelled keeps the agent for about 90 seconds, and costs nothing.\r\n\r\nA create refused with `No agent is available…` or `Could not start the call.` still appears in the call history, as a call that never started." parameters: - name: pearlId in: path description: >- Your Pearl's id. It must be an active voice Pearl. Find it on your Pearl's overview page, in the **Settings** popover. required: true schema: type: string requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/StreamCallCreateRequest' description: Represents the data required to create a stream token. example: endUserId: crm-77812 callData: firstName: Dana orderId: A-1234 audioFormat: opus_24000 text/json: schema: allOf: - $ref: '#/components/schemas/StreamCallCreateRequest' description: Represents the data required to create a stream token. example: endUserId: crm-77812 callData: firstName: Dana orderId: A-1234 audioFormat: opus_24000 application/*+json: schema: allOf: - $ref: '#/components/schemas/StreamCallCreateRequest' description: Represents the data required to create a stream token. example: endUserId: crm-77812 callData: firstName: Dana orderId: A-1234 audioFormat: opus_24000 responses: '200': description: 'The call was created: connect with the `token` before it expires.' content: text/plain: schema: $ref: '#/components/schemas/StreamCallCreated' example: callId: 6720f3c1a8b4e5d6f7a8b9c0 url: wss://agents.nlpearl.ai/Stream/WebSocket token: wst_kX9vQ2... expiresAt: '2026-10-28T09:01:00Z' audio: encoding: opus sampleRate: 24000 channels: 1 frameMs: 20 application/json: schema: $ref: '#/components/schemas/StreamCallCreated' example: callId: 6720f3c1a8b4e5d6f7a8b9c0 url: wss://agents.nlpearl.ai/Stream/WebSocket token: wst_kX9vQ2... expiresAt: '2026-10-28T09:01:00Z' audio: encoding: opus sampleRate: 24000 channels: 1 frameMs: 20 text/json: schema: $ref: '#/components/schemas/StreamCallCreated' example: callId: 6720f3c1a8b4e5d6f7a8b9c0 url: wss://agents.nlpearl.ai/Stream/WebSocket token: wst_kX9vQ2... expiresAt: '2026-10-28T09:01:00Z' audio: encoding: opus sampleRate: 24000 channels: 1 frameMs: 20 '400': description: >- A validation or business rule failed. `errors.validation` lists the messages: see Errors above. content: text/plain: schema: $ref: '#/components/schemas/ValidationProblemDetails' example: type: https://tools.ietf.org/html/rfc7231#section-6.5.1 title: One or more validation errors occurred. status: 400 errors: validation: - 'Missing pre-call variables: firstName.' application/json: schema: $ref: '#/components/schemas/ValidationProblemDetails' example: type: https://tools.ietf.org/html/rfc7231#section-6.5.1 title: One or more validation errors occurred. status: 400 errors: validation: - 'Missing pre-call variables: firstName.' text/json: schema: $ref: '#/components/schemas/ValidationProblemDetails' example: type: https://tools.ietf.org/html/rfc7231#section-6.5.1 title: One or more validation errors occurred. status: 400 errors: validation: - 'Missing pre-call variables: firstName.' '401': description: The credentials are missing or invalid. '403': description: The key or token lacks the `pearls:stream` scope. '500': description: An unexpected server error. components: schemas: StreamCallCreateRequest: type: object properties: endUserId: maxLength: 200 type: string description: "Your own id for the person on the call, such as a customer id, an e-mail or a phone number, up to 200 characters. A stream call has no phone number, so this takes its place: in the call history, in your Pearl's [memory](/pages/knowledge_base#memory), and in the flow's [Phone Number](/pages/variables) variable. Send the same value for the same person every time, and never one value for different people.\r\n \r\n Optional. Absent, `null` or blank, the call has no end user: the Phone Number variable is empty, and the Pearl neither recalls an earlier call nor remembers this one." nullable: true callData: type: object additionalProperties: type: string description: "The flow's [pre-call variables](/api-reference/flow_variables), by variable name: the same dictionary as a phone call's `callData`.\r\n \r\n**Required entries:** every variable used in the opening sentence, and every input of a pre-call API, present and not blank. Other variables are optional.\r\n \r\nKeys are letters (any script), digits, `_` and `-`, up to 40 characters. Values are strings, up to 200 characters." nullable: true audioFormat: type: string description: "The audio format of the call, the same in both directions. We recommend `opus_24000`: HD for far less bandwidth.\r\n \r\n- `opus_24000`: Opus at 24 kHz, HD.\r\n- `opus_8000`: Opus at 8 kHz, phone quality.\r\n- `ulaw_8000`: 8 kHz G.711 μ-law, phone quality.\r\n- `pcm_24000`: 24 kHz 16-bit little-endian PCM, HD.\r\n \r\nCase-insensitive. Absent, `null` or empty means `ulaw_8000`, and any other value is refused." default: ulaw_8000 nullable: true additionalProperties: false description: Represents the data required to create a stream token. StreamCallCreated: type: object properties: callId: type: string description: >- The call's id: the same id as in [Get Call](/api-reference/v2/call/get-call), the call list and the webhooks. nullable: true url: type: string description: >- The WebSocket URL. Open it with the token: `url?token=`. Always use the returned value rather than a fixed address. nullable: true token: type: string description: >- The single-use token for the connection, starting with `wst_`. It is valid for 60 seconds and is consumed by the first successful connection. Treat it as a secret. From a server you can send it in the `Authorization: Bearer` header instead of the query. nullable: true expiresAt: type: string description: >- When the token stops being accepted, in ISO 8601 UTC: creation plus 60 seconds. format: date-time audio: allOf: - $ref: '#/components/schemas/StreamCallAudioFormat' description: The format of every audio frame, in both directions. nullable: true additionalProperties: false description: Represents what your server needs to connect a stream call. ValidationProblemDetails: type: object properties: type: type: string nullable: true title: type: string nullable: true status: type: integer format: int32 nullable: true detail: type: string nullable: true instance: type: string nullable: true errors: type: object additionalProperties: type: array items: type: string nullable: true additionalProperties: {} StreamCallAudioFormat: type: object properties: encoding: type: string description: >- The audio encoding: `mulaw` (8-bit mu-law), `pcm_s16le` (16-bit little-endian PCM) or `opus` (one Opus packet per frame). nullable: true sampleRate: type: integer description: 'The sample rate, in hertz: `8000` or `24000`.' format: int32 channels: type: integer description: 'The number of audio channels: always `1` (mono).' format: int32 frameMs: type: integer description: 'The duration of each audio frame, in milliseconds: always `20`.' format: int32 additionalProperties: false description: >- Represents the audio format of a stream call, the same in both directions. securitySchemes: bearer_auth: type: http description: >- Specify the authorization token. For more information, check out the [Authorization Guide](/api-reference/authorization). scheme: bearer oauth2_client_credentials: type: oauth2 description: >- OAuth2 client_credentials grant. Use the Id of an OAuth API key as `client_id` and its one-time secret as `client_secret`. flows: clientCredentials: tokenUrl: /oauth/token scopes: pearls:read: List and view Pearls pearls:write: >- Create and update Pearls (settings, conversation flows, voices); implies pearls:read pearls:moderate: Run/pause Pearls and reset customer memory; implies pearls:read pearls:analytics: Read Pearl analytics; implies pearls:read pearls:leads: Manage and read outbound leads; implies pearls:read pearls:calls: >- Read calls and recordings, make and delete calls; implies pearls:read pearls:stream: >- Create stream tokens and run calls over a WebSocket; implies pearls:read account:phone_numbers: >- Read account phone numbers and text channels, manage custom VoIP numbers, import Twilio numbers and delete phone numbers account:users: Read account users account:advanced: Manage advanced account settings (blacklist) account:billing: Read account information and credit balance account:audit_log: Read the audit log tts: Synthesise speech and clone voices ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.