API Overview

The Voice Platform API is an app-scoped HTTP/JSON API. Use it to create and inspect voice resources and to issue commands that control their lifecycle and media. The reference is organized by resource and capability so you can move from a general workflow to the exact endpoint contract.

Using the API

• Send your application API key with every protected request. See Authentication.
• Shared conventions for timestamps, phone numbers, and URLs are documented in Formats.
• Most commands are asynchronous. A successful command commonly returns 202 Accepted with an operation_uuid; use the corresponding webhook event to observe the result. See Awaiting asynchronous operations.
• Use idempotency keys on supported mutating requests so retries do not repeat an operation. See Idempotency.
• Handle failures according to the public error envelope and retry guidance in Errors and Rate limits.

Design approach

The HTTP API exposes low-level, resource-oriented primitives so applications can compose workflows without being constrained by a high-level abstraction. Future SDKs and code examples will add higher-level helpers.

Behavioral choices are explicit in the HTTP API; future SDKs may provide convenient defaults.

When a command produces a lifecycle or media webhook, the event normally carries the same operation_uuid, so your application can correlate it with the request. recording.ended carries the originating recording/start UUID, including when a later stop command caused the event. Some commands only confirm dispatch; the command’s API reference and relevant webhook reference identify what confirmation to expect.

A standalone WebSocket Session follows the WebSocket connection lifecycle. See Call events for each lifecycle. Identifier, timestamp, number, and URL conventions are shared across these contracts.

Events and delivery

The platform sends webhooks as call and media state changes occur. Events include call.created, call.answered, playback.started, and recording.ended. Most command lifecycle events carry the command’s operation_uuid, allowing your application to correlate an event with the request that initiated it.

Webhook delivery is at-least-once, with retries, dead-letter handling, signed payloads, and per-session ordering guarantees. Support currently configures one webhook URL for each application; self-service webhook configuration is planned. The webhook URL cannot be selected per call. See the Webhook reference for event payloads and delivery behavior.

Reference groups

• Sessions are the platform’s fundamental primitive. A Session can represent a phone call, an AI agent, a WebRTC or SIP participant, or a standalone WebSocket connection. Use Sessions to originate outbound calls, answer or end calls, inspect dial and session state, control media, record audio, and receive lifecycle events.
• Rooms provide a virtual shared space where two or more Sessions can participate in the same conversation. Create and inspect Rooms, add or remove Sessions, mute or unmute members, and control member and room playback volume.
• Playback plays audio into an individual Session. Play URL-based or streaming audio, play silence, and pause, resume, stop, seek, or restart playback.
• Room playback plays URL-based or streaming audio into a Room’s shared mix, where every member can hear it.
• Recording captures audio from a Session or mixed Room and makes the result available through time-limited pull and live URLs. Session recordings can mask and unmask sensitive audio. Each recording URL expires at the time in its expires_at field.
• Keypad input from a human Session can be collected as individual key presses or as a structured dialog. Play a prompt, collect and validate digits, or cancel an in-progress collection.
• WebSocket audio creates standalone WebSocket Sessions or relays any Session’s audio bidirectionally to your own wss:// backend. Relays support pause and resume, mute and unmute, and buffer flush controls.

Each endpoint page states the request, response, and event behavior that applies to that operation.