Voice Platform APIRoom Playback

Start recording room audio

View as Markdown
Start one persistent mixed [Recording](/api/recording) of the room. The accepted [Operation](/api) and Recording share the flat response body. The Recording remains active while the room is empty and across service recovery. The response and webhooks expose its opaque `recording_uuid` and signed, time-bounded public URLs; internal paths are not exposed. **Triggered webhooks:** `command.recording.start.accepted` immediately, followed by `recording.became_available` when liveness succeeds. If that check does not confirm liveness, the room Recording remains active and no `recording.failed` webhook is emitted. A later stop emits `recording.ended`.

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

room_idstringRequired

Room ID (format {prefix}-room-{uuid}). The UUID portion is lowercase hexadecimal — uppercase hex is rejected with 400.

Headers

Idempotency-KeystringOptionalformat: "^[a-zA-Z0-9._-]+$"<=128 characters
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.

Response

Room recording start accepted
operation_uuidstringformat: "uuid"
statusenum
recording_uuidstringformat: "^rec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
Stable opaque identifier for this Recording.
expires_atdatetime

Exact expiry instant of pull_url, derived from the URL’s signed expiration.

pull_urlstringformat: "uri"
Fetches the whole Recording so far. Its configurable validity window defaults to 24 hours from this response's emission.
room_idstringOptional

Owning Room; mutually exclusive with session_uuid.

session_uuidstringOptional

Owning Session; mutually exclusive with room_id.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error