> For complete lifecycle-event payload schemas and examples, use the canonical overview: Session /api/sessions; Room lifecycle, participants, 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 Reference

> Build reliable calling experiences with Vorbal APIs for calls, media, messaging, and webhooks.

## Docs

- [Authentication](https://docs.vorbal.dev/api/authentication.md): Authenticate API requests.
- [API changelog](https://docs.vorbal.dev/api/api-changelog.md): Integration-relevant changes to the Vorbal API
- [Event delivery](https://docs.vorbal.dev/api/event-delivery.md): Understand webhook metadata, signature verification, retries, failures, and event ordering.
- [Session](https://docs.vorbal.dev/api/sessions.md): Complete Session resource and lifecycle-event reference, including payload schemas and examples.
- [WebSocket overview](https://docs.vorbal.dev/api/web-socket.md): Complete WebSocket Session connection and lifecycle-event reference.
- [Room](https://docs.vorbal.dev/api/rooms.md): Complete Room resource and event reference for room lifecycle, participants, and room playback.
- [RoomParticipant](https://docs.vorbal.dev/api/room-participants.md): Room-participant API overview; complete participant lifecycle-event schemas and examples are in the Room overview.
- [Room Playback overview](https://docs.vorbal.dev/api/room-playback.md): Room Playback API overview; complete room-playback event schemas and examples are in the Room overview.
- [Recording](https://docs.vorbal.dev/api/recording.md): Complete Recording resource and lifecycle-event reference, including speech-activity events and payload examples.
- [Playback overview](https://docs.vorbal.dev/api/playback.md): Complete Session playback command and lifecycle-event reference, including payload schemas and examples.
- [Keypad (DTMF)](https://docs.vorbal.dev/api/keypad-input.md): Complete keypad-input command and event reference for individual DTMF presses and collected digits.
- [Message](https://docs.vorbal.dev/api/messages.md): Complete Message resource and lifecycle-event reference for outbound SMS.

## API Docs

- API Overview > Event delivery [Webhook signature public keys](https://docs.vorbal.dev/api/event-delivery/webhooks/get-webhook-public-keys.md)
- API Overview > Sessions & Calls [List sessions](https://docs.vorbal.dev/api/sessions/list.md)
- API Overview > Sessions & Calls [Get session details](https://docs.vorbal.dev/api/sessions/get.md)
- API Overview > Sessions & Calls [Originate outbound call](https://docs.vorbal.dev/api/sessions/dial.md)
- API Overview > Sessions & Calls [Answer a call](https://docs.vorbal.dev/api/sessions/answer.md)
- API Overview > Sessions & Calls [Reject an incoming call](https://docs.vorbal.dev/api/sessions/reject.md)
- API Overview > Sessions & Calls [Cancel an unanswered outgoing call](https://docs.vorbal.dev/api/sessions/cancel.md)
- API Overview > Sessions & Calls [Delete session](https://docs.vorbal.dev/api/sessions/delete.md)
- API Overview > WebSocket [Create a WebSocket session](https://docs.vorbal.dev/api/web-socket/connect-websocket.md)
- API Overview > Rooms [List rooms](https://docs.vorbal.dev/api/rooms/list.md)
- API Overview > Rooms [Get room status](https://docs.vorbal.dev/api/rooms/get.md)
- API Overview > Rooms [Create a room](https://docs.vorbal.dev/api/rooms/create.md)
- API Overview > Rooms [Delete room](https://docs.vorbal.dev/api/rooms/delete.md)
- API Overview > Room Participants [List room participants](https://docs.vorbal.dev/api/room-participants/list.md)
- API Overview > Room Participants [Add a session to the room](https://docs.vorbal.dev/api/room-participants/add.md)
- API Overview > Room Participants [Get a single room participant](https://docs.vorbal.dev/api/room-participants/get.md)
- API Overview > Room Participants [Remove a participant from the room](https://docs.vorbal.dev/api/room-participants/remove.md)
- API Overview > Room Participants [Mute room participant](https://docs.vorbal.dev/api/room-participants/mute.md)
- API Overview > Room Participants [Unmute room participant](https://docs.vorbal.dev/api/room-participants/unmute.md)
- API Overview > Room Participants [Set room participant volume](https://docs.vorbal.dev/api/room-participants/volume.md)
- API Overview > Room Playback [Play audio in room](https://docs.vorbal.dev/api/room-playback/play.md)
- API Overview > Room Playback [Pause room playback](https://docs.vorbal.dev/api/room-playback/pause.md)
- API Overview > Room Playback [Start recording room audio](https://docs.vorbal.dev/api/room-playback/start-recording.md)
- API Overview > Room Playback [Stop recording room audio](https://docs.vorbal.dev/api/room-playback/stop-recording.md)
- API Overview > Room Playback [Seek room playback](https://docs.vorbal.dev/api/room-playback/seek.md)
- API Overview > Room Playback [Stop room playback](https://docs.vorbal.dev/api/room-playback/stop.md)
- API Overview > Room Playback [Set room playback volume](https://docs.vorbal.dev/api/room-playback/volume.md)
- API Overview > Room Playback [Resume room playback](https://docs.vorbal.dev/api/room-playback/resume-room-playback.md)
- API Overview > Recording [List session recordings](https://docs.vorbal.dev/api/recording/list.md)
- API Overview > Recording [Get a session recording](https://docs.vorbal.dev/api/recording/get.md)
- API Overview > Recording [Start recording](https://docs.vorbal.dev/api/recording/create.md)
- API Overview > Recording [Stop recording](https://docs.vorbal.dev/api/recording/stop.md)
- API Overview > Recording [Mask (pause writing) the active recording](https://docs.vorbal.dev/api/recording/mask.md)
- API Overview > Recording [Unmask (resume writing) the active recording](https://docs.vorbal.dev/api/recording/unmask.md)
- API Overview > Playback [Start audio playback](https://docs.vorbal.dev/api/playback/play.md)
- API Overview > Playback [Pause playback](https://docs.vorbal.dev/api/playback/pause.md)
- API Overview > Playback [Resume playback](https://docs.vorbal.dev/api/playback/resume.md)
- API Overview > Playback [Seek within playback](https://docs.vorbal.dev/api/playback/seek.md)
- API Overview > Playback [Restart playback](https://docs.vorbal.dev/api/playback/restart.md)
- API Overview > Playback [Stop playback](https://docs.vorbal.dev/api/playback/stop.md)
- API Overview > Playback [Upload pushed playback audio](https://docs.vorbal.dev/api/playback/upload-playback-audio.md)
- API Overview > Keypad (DTMF) [Collect DTMF input with optional playback](https://docs.vorbal.dev/api/keypad-input/collect.md)
- API Overview > Keypad (DTMF) [Cancel in-progress DTMF collection](https://docs.vorbal.dev/api/keypad-input/cancel.md)
- API Overview > Keypad (DTMF) [Send DTMF sequence](https://docs.vorbal.dev/api/keypad-input/send.md)
- API Overview > Keypad (DTMF) [Cancel outbound DTMF sequence](https://docs.vorbal.dev/api/keypad-input/cancel-dtmf-send.md)
- API Overview > Payments [Collect a payment card](https://docs.vorbal.dev/api/payments/collect-secure-payment-card.md)
- API Overview > Payments [Cancel payment-card collection](https://docs.vorbal.dev/api/payments/cancel-secure-payment-card-collection.md)
- API Overview > Payments [Collect CVV](https://docs.vorbal.dev/api/payments/collect-secure-payment-cvv.md)
- API Overview > Payments [Cancel CVV collection](https://docs.vorbal.dev/api/payments/cancel-secure-payment-cvv-collection.md)
- API Overview > Payments [Create a charge](https://docs.vorbal.dev/api/payments/create-secure-payment-charge.md)
- API Overview > Messages [List messages](https://docs.vorbal.dev/api/messages/list-messages.md)
- API Overview > Messages [Send an outbound SMS message](https://docs.vorbal.dev/api/messages/create-message.md)
- API Overview > Messages [Get SMS message status](https://docs.vorbal.dev/api/messages/get-message-status.md)
- API Overview > Application configuration [Get application configuration](https://docs.vorbal.dev/api/application-configuration/get-application-configuration.md)
- API Overview > Application configuration [Update application configuration](https://docs.vorbal.dev/api/application-configuration/update-application-configuration.md)
- API Overview > Health [Health check](https://docs.vorbal.dev/api/health/health-check.md)
- API Overview > Health [Liveness probe](https://docs.vorbal.dev/api/health/liveness-check.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.vorbal.dev/openapi.json)
- [OpenAPI YAML](https://docs.vorbal.dev/openapi.yaml)


> **Note:** This page contains both a page directory (above) and the landing page content (below). The page directory is generated for agent use and does not appear on the landing page.

> For complete lifecycle-event payload schemas and examples, use the canonical overview: Session /api/sessions; Room lifecycle, participants, 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 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](/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. 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](/api/event-delivery) 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.

```json
{
  "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](/api/sessions#lifecycle-events)
* [Room lifecycle, participant, and playback events](/api/rooms#lifecycle-participant-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 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](/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 participants, and control
  participant volume and room playback.
* **[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 participant 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, with separate sending and
  delivery state.

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

> **Tip**
>
> For generated clients and automated tooling, download the machine-readable
> [OpenAPI 3.1 specification](/openapi.yaml).