Voice Platform APIPlayback

Start audio playback

View as Markdown
**Rate limit: Per command** · **Burst:** 8 · **Refill:** 4 req/s Start finite-file, live-stream, or silence playback. Stops any active playback first (last-wins semantics). Before accepting a finite URL playback, the gateway probes each source with HEAD first and falls back to a ranged GET. A source that cannot be prepared returns a synchronous HTTP error, and no playback webhook is emitted. After a request is accepted, a later start failure emits `playback.failed`. **Triggered webhooks:** `playback.started`, `playback.stopped`, `playback.failed` (on error) **Note on `playback.started` timing.** `playback.started` fires at the true sound-start — the moment audio actually begins playing on the call, not when the request is accepted. The gateway stages the event at dispatch and emits it only when playback actually begins (audible), so `timestamp` reflects real audio start (usable to measure start latency). If playback never starts, `playback.failed` fires instead.

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

uuidstringRequired

Session UUID (format {5-char-prefix}-{uuid}).

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.

Request

This endpoint expects an object.
objectRequired
OR
objectRequired
OR
objectRequired

Response

Command accepted for async execution
operation_uuidstringformat: "uuid"
statusenum
already_endedtrueOptional

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
502
Bad Gateway Error
503
Service Unavailable Error