Reviews API

The project's reviews (docs/reviews.md): playlist and screen changes proposed under Propose access, the campaign, screen folder and move writes that reach a protected screen (kind protected_change, docs/screen-scope.md), and for an ad network the creatives buyers submitted (kind ad_creative).

Newest first, at most limit (default 50, at most 100) per page; pass next_cursor back as cursor with the same filters. state pending (the default), decided (every other state) or all; kind narrows to one kind.

A dashboard session reads every kind; a bearer reads the kinds its capabilities cover (playlists for playlist_change, screens for screen_change and protected_change, advertising for ad_creative), and a kind it cannot read is an empty page. pending_count counts the pending reviews of every kind the caller sees.

A caller limited to screens sees only the screen_change and protected_change reviews whose whole reach is inside its scope (a review that selects screens by tag never is) and the playlist_change reviews; ad_creative reviews are hidden from it, and pending_count counts what it sees.

One review. A playlist change adds preview: the live and the proposed playlist in the stored shape (pages with resolved_media); live is null for a create. A bearer that cannot read the review's kind (see listReviews) gets not_found, as does a caller limited to screens for a review whose reach is not inside its scope.

The project a review belongs to, for the email link: a signed-in person who is a member of that project gets its id and name and switches to it (PUT /api/session/project) before reading the review. Anyone else gets not_found. Works whatever project the session has selected.

Approves a pending review as a person who can approve (the project owner or a member with can_approve; else approver_required). The flag is read again inside the decision's transaction, so a person whose approval was turned off meanwhile decides nothing (approver_required). Staff shadow sessions cannot decide.

A playlist update is applied with the base revision as If-Match; when the live playlist moved on the review becomes stale and the call answers review_stale.

A create or update whose tag, folder or all selectors would now play media they did not resolve when proposed, that the review does not name and that the live version does not already play, also becomes stale (review_stale).

A screen change replays its stored request (a tag resolves now): the call applies screens for a few seconds and the rest continue in the background while screen_change.result.applying is true.

A screen change waiting on a pending playlist review answers review_blocked naming it; one whose playlist has no approved version answers playlist_not_approved. include_dependents also approves, in order, the screen changes waiting on this playlist review. Events of the applied change carry the person as actor and the proposing agent as agent.

The answer carries warnings (PlaylistWarning): screen_fact_missing when the approved change puts pages whose iframe src or application params read a screen token on screens that lack it. A decided review is review_not_pending; repeating the same decision replays.

A review marked protected (a protected_change, or a screen_change that reached a protected screen) is decided by an approver other than the proposer and the person responsible for the proposing agent: second_approver_required (403) otherwise, and when the proposer cannot be traced to a person (docs/screen-scope.md).

An approver limited to screens decides only a review whose whole reach is inside the scope (outside_screen_scope, 403). A protected_change is applied by this request, as the approving person, at the revision it was proposed against; a campaign or folder that changed or went since, or screens that moved on, make the review stale (review_stale, 409).

A dependent that cannot be approved reports the same codes in dependents[].problem.

Rejects a pending review with a reason the proposer reads. Approver only, as approveReview; an approver limited to screens decides only a review inside its scope (outside_screen_scope), and no person limited to screens decides an ad creative. Nothing changes on glass; a rejected playlist create stays unapproved.

Asks the proposer for changes with a note they read; the proposer proposes again. Approver only, as approveReview. For an ad creative the buyer reads the note on the creative. A scoped approver is limited as in rejectReview.

Withdraws a pending playlist, screen or protected_change review. A bearer withdraws only what its own agent or service client proposed (forbidden otherwise); a person withdraws as an approver or as the proposer's responsible person; a person limited to screens withdraws only a review inside its scope (outside_screen_scope).

A withdrawn playlist create stays unapproved.