> For complete lifecycle-event payload schemas and examples, use the canonical overview: Session /api/sessions; Room lifecycle, members, and room playback /api/rooms; Session playback /api/playback; Recording /api/recording; DTMF /api/keypad-input; Messages /api/messages; WebSocket Session /api/web-socket. Use /api/event-delivery for transport behavior. Endpoint pages name relevant events, but these overviews are the canonical references. # 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](/api/authentication). * Shared conventions for timestamps, phone numbers, and URLs are documented in [Formats](/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](/async-operations). * Use idempotency keys on supported mutating requests so retries do not repeat an operation. See [Idempotency](/idempotency). * Handle failures according to the public error envelope and retry guidance in [Errors](/errors) and [Rate limits](/rate-limits). ## Design approach The HTTP API exposes low-level, [resource-oriented](https://google.aip.dev/121) 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](/api/sessions#session-lifecycle) for each lifecycle. Sessions, commands, and their events share the same identifier, timestamp, number, and URL conventions; see [Formats](/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](/api/event-delivery) 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](/api/sessions#lifecycle-events) * [Room lifecycle, member, and playback events](/api/rooms#lifecycle-member-and-playback-events) * [Session playback events](/api/playback#lifecycle-events) * [Recording events](/api/recording#lifecycle-events) * [Keypad input events](/api/keypad-input#lifecycle-events) * [Message events](/api/messages#lifecycle-events) * [WebSocket events](/api/web-socket#lifecycle-events) ## Reference groups * **[Sessions](/api/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](/api/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](/api/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](/api/room-playback)** plays URL-based or streaming audio into a Room's shared mix, where every member can hear it. * **[Recording](/api/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](/api/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](/api/web-socket)** 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](/api/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. For generated clients and automated tooling, download the machine-readable [OpenAPI 3.1 specification](/openapi.yaml).