> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.telekesher.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.telekesher.dev/_mcp/server.

# 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](/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
  [Awaiting asynchronous operations](/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.

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](/webhooks/call-events#call-lifecycle) 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](/webhooks/overview) for event payloads and delivery
behavior.

## 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 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](/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 or streaming 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/collect-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](/api/web-socket)** 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.

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