Playlists API

Versioned playlist list that may expose adslot pages. The v1 list refuses a page holding an ad-bearing document with version_required instead of filtering it.

Pages like listPlaylists, newest first, at most 200 per page and fewer once a page holds 8 MiB of stored playlists. next_cursor is the position of the last returned row while more rows remain; pass it back as after, with the same filters, for the next page. next_cursor is null on the last page. library=true lists the organization Library's playlists instead (read-only; schedule them or create from their templates).

Authoring entry for the adslot page union. At most 16 adslot pages, at least one ordinary page with no visibility, and the reuse of one slot definition on different pages remain server checks. Reference resolution and DNS stay server checks.

A dashboard session (the page editor) creates the playlist live, never as a proposal, attributed to the person, and needs the project owner or a member who can approve (approver_required otherwise); media it names that waits for its review is media_pending_review (409), where an agent's live write approves it.

A write that carries an iframe page the Player web app cannot frame is stored all the same, and its answer carries warnings (PlaylistWarning) and the project's event log gets one playlist.iframe_framing_refused event per such page.

A write whose iframe src, fallback_src or application params read a screen token ({screen.field.NAME} and the others of the primitive schemas) that a screen showing the playlist lacks also answers with a screen_fact_missing warning naming the first 20 such screens; those screens' manifests leave that primitive out.

An iframe src or fallback_src that is a Google Slides, Docs or Sheets link (share, Publish to web or embed) or a Microsoft 365 OneDrive or SharePoint Embed link is stored rebuilt for the screen, where Slides loop and advance on the link's delayms held to the page's duration, Docs, Sheets, Word and Excel reload every 5 minutes.

A pasted <iframe> embed code in src or fallback_src is read for its src. A file that asks viewers to sign in is refused with document_not_shared (400), whose errors[0].field is that src or fallback_src and whose detail names the sharing setting to change.

Versioned update accepting the adslot page union. If-Match carries the playlist revision.

A dashboard session (the page editor) replaces the playlist live, never as a proposal, attributed to the person; it needs the project owner or a member who can approve (approver_required otherwise) and If-Match (invalid_request when absent); a playlist no person approved yet is playlist_not_approved (409), as for patchPlaylistStructure, and media a page names that waits for its review is media_pending_review (409).

A write that carries an iframe page the Player web app cannot frame is stored all the same, and its answer carries warnings (PlaylistWarning) and the project's event log gets one playlist.iframe_framing_refused event per such page.

A write whose iframe src, fallback_src or application params read a screen token ({screen.field.NAME} and the others of the primitive schemas) that a screen showing the playlist lacks also answers with a screen_fact_missing warning naming the first 20 such screens; those screens' manifests leave that primitive out.

An iframe src or fallback_src that is a Google Slides, Docs or Sheets link (share, Publish to web or embed) or a Microsoft 365 OneDrive or SharePoint Embed link is stored rebuilt for the screen, where Slides loop and advance on the link's delayms held to the page's duration, Docs, Sheets, Word and Excel reload every 5 minutes.

A pasted <iframe> embed code in src or fallback_src is read for its src. A file that asks viewers to sign in is refused with document_not_shared (400), whose errors[0].field is that src or fallback_src and whose detail names the sharing setting to change.

Change only supplied top-level fields: name, pages, audio, format or fields. Omitted fields are preserved from the same transaction snapshot. Supplied pages, audio and format replace the complete value; audio null removes the soundtrack and format null removes the format. Nested array elements are not merged.

A name-only edit of an approved playlist does not revalidate or re-resolve its unchanged content, including older stored page formats. Supplied content and audio/page cue relationships are validated. If-Match optionally guards the revision; identical patches are no-ops and idempotent retries replay the original answer.

Propose access and review policy behave as for PUT, including the warnings a supplied pages value earns for an iframe page the Player web app cannot frame. PUT remains a complete document replacement.

Tombstones one playlist owned by the authenticated project. Refused with resource_conflict (409) while any screen, archived or pending included, has it as its default, in its playlist schedule, or as its takeover, while a screen folder has it as its default, and while a campaign plays it.

The dashboard session may delete as well; it creates and replaces playlists with createPlaylistV2 and updatePlaylistV2 and changes their structure through patchPlaylistStructure.

A signed-in person changes a playlist's structure and never what its pages show: its name, the order of its pages, which pages stay, and each kept page's advance and visibility. pages is the complete new order; a stored page it omits is removed, and an id the playlist does not hold, or a repeated one, is invalid_request at pages[i].id.

A kept page's canvas, transition, audio_cue, primitives and comments are always the stored ones: the body has no member for them, and any other member is refused.

The kept pages go back through the same resolution and validation as any stored playlist, so a media item deleted since is refused (resource_conflict) and the playlist still keeps one ordinary page with no visibility, at most 16 ad slot pages and its audio_end cues. advance replaces the page's advance (an ad slot page has none); visibility replaces the page's visibility when an object, removes it when null and keeps it when omitted.

A change that leaves the playlist as stored is a no-op. If-Match carries the playlist revision and is required (invalid_request when absent, revision_conflict when stale). The write is live at once on every screen showing the playlist and is attributed to the person on playlist.updated; it is never a proposal, so the answer is never 202.

A playlist no person approved yet (approved_revision 0) is refused with playlist_not_approved (409): decide its review first. A name another playlist of the project uses is resource_conflict. The dashboard session only; agents change playlists with patchPlaylist, and a person changes what pages show with updatePlaylistV2.

The answer carries warnings (PlaylistWarning) as for any write, among them screen_fact_missing when a screen that shows the playlist lacks a value an iframe src or application params of its pages read. The body is at most 64 KiB.

The playlist's revisions, newest first: each revision a write stored (a create, a replace, a patch, a structure change, an applied review, a promote) with its name, its page count, the kind of change and who made it.

History begins with the revision a playlist held when revision history was first recorded: until its next write the list holds that revision alone, with change baseline. Revisions are kept for as long as the playlist is. At most 50 per page; next_cursor while more remain, null on the last page.

One revision of the playlist and the playlist as it stood at that revision: its name, pages, soundtrack and format, with revision set to this one. A revision the playlist never had, or one from before its history began, is not_found.

Makes an earlier revision current again by copying it forward: its pages, soundtrack and format become a new revision, the current one plus one, whose change is promoted and restored_from names the revision copied. The playlist keeps its current name, earlier revisions stay as they were, and every screen that shows the playlist updates as for any other write.

If-Match is required and names the current revision (invalid_request when absent, revision_conflict when stale). The pages are resolved again as a structure change resolves them: a selector matches today's media, and media or a web app the revision named that is gone or not ready refuses the promote with the problem a write would get.

A revision whose content is the current content changes nothing and answers the current playlist. Needs a credential that publishes live (forbidden for one whose writes are proposed for review) or a dashboard session of the project owner or a member who can approve (approver_required); a playlist no person approved yet is playlist_not_approved (409).

As for any write, the answer carries warnings (PlaylistWarning), among them screen_fact_missing when a screen that shows the playlist lacks a value an iframe src or application params of the promoted pages read.

Sets, or with null clears, field values of a playlist made from a template, and builds its pages again from the template's current revision: the values are checked like a create checks them, and brand changes made to the template since reach this copy. Send no values to only bring the copy up to date.

Review class like any playlist write: the owner or a member who can approve (dashboard session) and a Manage credential write live, an uploader only for its playlists and folders, and Propose turns the change into a review (202). A playlist that was not made from a template is invalid_request. If-Match is optional.

The playlists made from a template (at most 1000, by name), each with the template revision its pages were built from and whether the template has a newer one.

The pages a playlist made from the template with these values would hold, checked by every playlist rule. Computes only; nothing is stored.

Adds one page to an approved playlist without sending the others: at the end, or in front of the page named by before.

The pages the playlist already holds are kept as stored and checked again with the new one in a single pass, so the rules across pages (1 to 100 pages, one ordinary page with no visibility, 16 ad slot pages, 1024 media references) see the result: a rule broken is invalid_request with field (page.id when the id is taken, before when it names no page).

The page validity of the playlist is the page's own visibility (from, until, windows, data), in each screen's timezone, until exclusive.

Review class: under Propose the change becomes a review (202); a later page change of the same playlist by the same proposer extends that pending review while it is based on the live revision, so successive changes do not supersede each other, and approval applies them all or none (review_stale when the playlist moved on); another proposer's pending page-change review is neither extended nor superseded, and the change waits as resource_conflict (409).

With Manage, or from a dashboard session of the owner or a member who can approve (approver_required otherwise), it is live. If-Match is optional: when present it must be the live revision. A playlist no person approved yet is playlist_not_approved (409).

An uploader (docs/uploaders.md) adds only a media page of its folders to one of its playlists (outside_upload_scope otherwise); an uploader member at Propose is the review's proposer (kind person).

Replaces one page of an approved playlist, in place, without sending the others. The body is the page and its id is page_id. An unknown page is not_found.

Everything else is as for addPlaylistPage: validated with the kept pages in one pass, review class (202 under Propose, chained onto a pending page-change review), live with Manage or from an approving person, If-Match optional, playlist_not_approved for a playlist no person approved.

An uploader replaces only a media page of its folders, for another media page of its folders; at Propose the pages waiting in its own review are its to replace too.

Removes one page of an approved playlist. The playlist keeps 1 to 100 pages and one ordinary page with no visibility (invalid_request otherwise). An unknown page is not_found. Everything else is as for replacePlaylistPage. An uploader removes only a media page of its folders.