Sign in

v2

latestOpenAPI 3.1.02026-08-013435189.7 KB
playlists

Publish a playlist

Publish the draft playlist as the new LIVE snapshot. Always async (ADR 0003): the resolver marks StreamState.processing_state as processing, signals PreparePlaylistWorkflow, and returns. Editor polls Playlist.publishStatus to observe the PREPARING -> IDLE / FAILED transition. Top-level errors carry extensions.code one of: STALE_DRAFT, EMPTY_PLAYLIST, BROKEN_ITEM, RECIPE_MISMATCH, NOT_LIVE, NOT_FOUND, INTERNAL.

post/playlists/{id}/publish

Path parameters

idstring required

Resource identifier.

Headers

Idempotency-Keystring

Optional client-generated key. A repeated request with the same key replays the original response (within 24h) instead of re-executing — safe retries.

Request body

expectedDraftVersioninteger required

Required (asymmetric vs ApplyPlaylistOperationsInput.basedOnVersion, which is optional). Publish is the ONLY user-action that mutates runtime state, so editor-side OCC must be deliberate (NB-07). On STALE_DRAFT the editor refetches Playlist { version diff } using the returned currentVersion and retries.

playlistIdstring required

Response

Successful response.

copiedFromstring nullable
createdAtstring date-time required
hasUnpublishedChangesboolean required

snapshot != nil && Playlist.version > snapshot.version. Returns false during the B-11 STREAMING+no-snapshot window — deliberate: the stream is live but nothing has been published yet.

idstring required
kind'video' | 'audio' required
liveVersioninteger required

PlaylistSnapshot.version — Playlist.version frozen at the last LIVE write. Returns 0 when no snapshot exists OR during the B-11 STREAMING+no-snapshot transient window (WriteInitialPlaylistSnapshot retry).

mode'sequential' | 'shuffle' required
publishStatus'IDLE' | 'PENDING' | 'PREPARING' | 'FAILED' | 'NOT_LIVE' required

Workflow-state derivation. NB-13: PREPARING wins over PENDING even when a concurrent edit advances Playlist.version while a publish is preparing.

streamIDstring required
updatedAtstring date-time required
versioninteger required

Bumped by 1 per committed spec mutation batch. Used for optimistic concurrency and as the snapshot handle for PreparePlaylistWorkflow.