Start recording
**Rate limit: Per command** · **Burst:** 4 · **Refill:** 1 req/s
Start a [Recording](/api/recording) of the call via the gateway recording
service. The accepted [Operation](/api) is returned immediately;
use its `operation_uuid` to correlate the command lifecycle. Once
`command.recording.start.accepted` supplies `recording_uuid`, use that
identifier to correlate the Recording's complete webhook lifecycle.
Requires recording to be enabled on this gateway. Each request opens a stream, and recording normally starts once per call.
Output is 8 kHz mono mixed WAV (both legs combined). Format is not configurable.
**Triggered webhooks:**
- `command.recording.start.accepted` (immediate, when recording begins; carries
`recording_uuid`, the signed public `pull_url`, and the
`operation_uuid` of this `recording/start` command). Actual
recording errors surface later as `recording.failed`.
- `recording.became_available` (once the gateway confirms the recording is
durably ingested; carries the explicit `pull_url` and `live_url`
signed links) — or `recording.failed` if it never confirms within
the validation window.
- When `enable_voice_activity_events` is true,
`recording.speech.started` and `recording.speech.ended` report
customer speech transitions for the lifetime of this recording.
Sensitivity and speech/silence confirmation durations are configurable.
The signed `pull_url` carried by `command.recording.start.accepted` is immediately
fetchable — the recording can be streamed while it is still in progress.
`pull_url` fetches the whole recording so far.
Treat the complete URL as an opaque, time-bounded bearer capability and
use it exactly as emitted; do not construct, parse, or modify its host,
path, or token. Its default 24-hour window starts when
`command.recording.start.accepted` is emitted, not when recording stops.
Authentication
AuthorizationBearer
Application auth. Send `Authorization: Bearer <app_uuid>:<api_key>`. See [Authentication](https://voice-platform.docs.buildwithfern.com/api/authentication) for details.
Path parameters
uuid
Session UUID (format {5-char-prefix}-{uuid}).
Headers
Idempotency-Key
Optional client-generated key for a mutating endpoint. It identifies one method, route, query, content type, and exact raw body within the authenticated app. Reusing it for a different request returns 422. While its record exists, a retry replays the original accepted response when available. Keys are valid for 1 hour. Allowed characters: letters, digits, dot, hyphen, underscore; max 128 characters. See the Idempotency guide.
Request
This endpoint expects an object.
operation_uuid
Optional caller-supplied per-command correlation id, a bare lowercase RFC-4122 v4 UUID (no prefix). Echoed back as `operation_uuid` in the 202 ack. A later lifecycle webhook carries it only when the gateway can unambiguously associate that event with this command; the field is correlation, not proof of causation. When omitted, the gateway mints one. Not an idempotency key — request deduplication is the `Idempotency-Key` header. Invalid input (not a v4 UUID) is rejected with `400 invalid_request`.
enable_voice_activity_events
When true, emit recording.speech.started and
recording.speech.ended while this session recording is
active. Detection is passive and does not alter recorded audio.
Not supported for standalone type: ws sessions or room recordings.
voice_activity_config
Required tuning when voice activity events are enabled. Supplying
this object requires
enable_voice_activity_events: true; otherwise the request is
rejected.
Response
Command accepted for async execution
operation_uuid
status
already_ended
Optional. Set to true on idempotent terminal commands when the session was already in a terminal state at the time the request was received. Absent otherwise.
Errors
400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
409
Conflict Error
413
Content Too Large Error
415
Unsupported Media Type Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error