API overview

The Vorbal API is an app-scoped HTTP/JSON API: each API key sees only its own application’s resources. 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 Handling asynchronous commands.
• 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.

The HTTP API makes each behavioral choice explicit, so your application sets a behavior instead of inheriting a hidden default. Future SDKs may add convenient defaults.

When a command produces a lifecycle or media event, the event normally carries the same operation_uuid, so your application can correlate it with the request. It is an opaque correlation token, not a resource or polling URL. recording.ended carries the originating Recording create operation 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 WebSocket Session follows the WebSocket connection lifecycle rather than a phone call’s, so its lifecycle events differ. See Session events for each lifecycle. Sessions, commands, and their events share the same identifier, timestamp, number, and URL conventions; see Formats.

Events and delivery

The platform sends webhooks as call and media state changes occur. Events include session.created, session.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 retries transient failures within a five-minute delivery window and provides dead-letter handling. Payloads are signed. The platform preserves per-session delivery ordering. Each application has one webhook URL. Use GET /api/v1/app to read the application’s configuration. Use PATCH /api/v1/app to update its webhook URL. The webhook URL cannot be selected per call. See the Event delivery guide for delivery behavior.

Find event payloads and examples

The owning resource or capability overview is the canonical reference for each event. Use these pages when you need an event’s trigger, payload schema, example, correlation fields, or terminal-outcome semantics:

• Session lifecycle events
• Room lifecycle, member, and playback events
• Session playback events
• Recording events
• Keypad input events
• Message events
• WebSocket events

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 WebSocket Session. 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 files, push live raw 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 can be collected from a human Session as individual key presses or a structured dialog, or sent toward a remote party as a timed DTMF sequence. Play a prompt, collect and validate digits, send keys and waits, or cancel an in-progress collection.
• WebSocket Sessions create a media-only Session. The Session stays active while the WebSocket connection is open. If the connection fails or closes, the Session ends.
• Messages send outbound SMS and expose independent provider-sending and recipient-delivery state.

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