API OverviewRoom Playback

Start recording room audio

View as Markdown
Start one persistent mixed [Recording](/api/recording) of the room. The Recording remains active while the room is empty and across service recovery. A `202` response confirms that the start request was accepted. It does not mean the Recording is available yet. The response also includes the current Recording details: - The `recording_uuid`. - A signed, time-bounded public `media_url`, without internal paths. Availability is reported separately: - If the Recording becomes available, the platform emits `recording.became_available`. - If the Recording does not become available, it remains active and the platform does not emit `recording.failed`. When you later stop the Recording, the platform emits `recording.ended`. See [Recording lifecycle events](/api/recording#lifecycle-events) for complete payload schemas and examples.

Authentication

AuthorizationBearer
Application auth. Send `Authorization: Bearer <app_uuid>:<api_key>` using any active key in the app's collection. See [Authentication](https://voice-platform.docs.buildwithfern.com/api/authentication) for details.

Path parameters

room_idstringRequired

Case-sensitive room identifier.

Headers

Idempotency-KeystringOptionalformat: "^[a-zA-Z0-9._-]+$"<=128 characters
Optional key for safely retrying mutating requests. See [Idempotency](https://voice-platform.docs.buildwithfern.com/idempotency) for details.
Operation-IdstringOptionalformat: "uuid"

optional client-supplied lowercase RFC-4122 v4 UUID returned as operation_uuid; platform generates one when omitted; correlation metadata distinct from Idempotency-Key.

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 identifier for this Recording.
expires_atdatetime

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

media_urlstringformat: "uri"

Starts at byte zero and follows the growing Recording until EOF. After finalization, the same URL serves a finite, range-capable WAV. Validity defaults to 24 hours.

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