API overview

The Vorbal API is an HTTP/JSON API. Use it to create and inspect voice resources and 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. Configure one webhook URL. Use GET /api/v1/app to read the configuration and PATCH /api/v1/app to update the webhook URL. The webhook URL cannot be selected per call. See the Event delivery guide for delivery behavior.

GET /api/v1/app also returns the effective limits.max_concurrent_dial_setups value. It applies to pending and ringing outbound calls across routes, defaults to 1, and uses 0 for unlimited. The field is read-only for API-key callers and is managed in Admin application limits. When this cap is full, a new dial returns 529 with Retry-After: 5 before monthly dial quota admission; the platform does not wait for capacity.

{
  "limits": {
    "max_concurrent_dial_setups": 1
  }
}

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, participant, 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 an inbound or outbound phone call or a 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 participants, and control participant volume and room playback.
• 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 participant 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, with separate sending and delivery state.

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