Campaigns API

Lists the project's campaigns in precedence order (at most 100), the order resolution reads them. reserved is present on every campaign.

A caller limited to screens (docs/screen-scope.md) sees every campaign, with editable true only when the whole audience is inside its scope (a tag leaf and the root every-screen rule never are; an all rule needs one contained child, an any rule every child) and the caller may change what plays.

Creates a campaign: every screen in its audience switches to playlist_id while from, until and windows hold in the screen's timezone (screenrig.schedule/v1; omit all three for always), and back when they stop holding.

A screen resolves its playlist as its takeover, then the first campaign that applies in precedence order (priority, higher first, then the most recently created), then its playlist schedule, then its default playlist. A campaign applies only to a screen with a default playlist; one with from, until or windows needs the screen's timezone.

The playlist must exist and be approved (playlist_not_approved). Screens switch within a minute; GET /api/campaigns/{id}/screens shows each screen's standing. An organization has at most 100 campaigns across its projects (campaign_limit_reached).

Appends campaign.created. reserved true reserves the campaign, and only a person who can approve sets it (reserved_item for an agent, a service client or anyone else), appending campaign.reserved_changed.

A caller limited to screens (docs/screen-scope.md) creates a campaign only for an audience inside its scope (folder and screen_id leaves; no tag, no every screen), else outside_screen_scope, and only as a person who can approve (approver_required).

A campaign whose audience reaches a protected screen is a protected_change review decided by a second approver (202 pending_review) at every access level. reserved true is protected folders and paused true on a new campaign (a draft) is schedule change control, both part of the Enterprise plan; a project whose plan lacks it is refused with feature_not_in_plan (402).

What a campaign write would change, without making it. With id, body is the PATCH body of that campaign; without, it is the POST body of a new one. The body is checked as the write checks it (an audience rule, a window, an unapproved playlist, a screen folder the project does not have).

The answer lists the screens that would gain the campaign on their stack and those that would lose it (count, and the first 500 screen ids), and the schedule calendar of the screens in the old and the new audience as it is (before) and as it would be (after) over from to to (default: a week from now; at most 93 days), grouped as GET /api/schedule/calendar groups.

A paused campaign is on no stack, so publishing one gains its audience; an edit that keeps the campaign on a screen's stack gains and loses nothing and shows in the calendars. Read access: nothing is written.

One campaign. reserved is always present; editable is present for a caller limited to screens (see listCampaigns).

Changes the members the body sets; null clears from, until or windows. paused true stops the campaign on every screen and false resumes it. A paused campaign is a draft: it is on no screen's stack, and a write that leaves it paused re-resolves no screen.

Publishing it for a test is this PATCH with paused false and an audience that is a test folder or a few screens; POST /api/campaigns/{id}/promote then copies that audience onto the real one. Every screen of the old and the new audience re-resolves within a minute. Appends campaign.updated. If-Match guards the revision.

Each write is stored in the campaign's history (GET /api/campaigns/{id}/revisions). campaign.updated. If-Match guards the revision. reserved sets or clears the reserved flag (a reserved campaign is changed, paused or un-reserved only by a person who can approve: reserved_item otherwise); a flip appends campaign.reserved_changed.

A caller limited to screens (docs/screen-scope.md) changes a campaign only when its stored and new audience are inside its scope (outside_screen_scope; otherwise it is read-only to them).

A campaign that reaches a protected screen is a protected_change review decided by a second approver (202 pending_review). reserved true on a campaign that is not reserved is protected folders, which the Enterprise plan includes; a project whose plan lacks it is refused with feature_not_in_plan (402).

Pausing or resuming a campaign, and editing or releasing a reserved one, are open on every plan.

Deletes the campaign and its revision history. Every screen showing it returns to what it would show without it within a minute. Appends campaign.deleted. If-Match guards the revision. A reserved campaign is deleted only by a person who can approve (reserved_item).

A caller limited to screens (docs/screen-scope.md) deletes a campaign only when its audience is inside its scope (outside_screen_scope). A campaign that reaches a protected screen is a protected_change review decided by a second approver (202 pending_review).

The campaign's revisions, newest first: the campaign as stored after each write by a person, an agent or a schedule import (a create, an update, a promote, a restore), with the kind of change and who made it.

History begins with the revision a campaign held when revision history was first recorded: until its next write the list holds that revision alone, with change baseline. A campaign whose history holds no revision with paused false is a draft. Revisions are kept for as long as the campaign is and go with it.

At most 50 per page; next_cursor while more remain, null on the last page.

Makes an earlier revision current again by copying it forward through the same write as PATCH: its name, playlist, audience, rule, placement, priority and paused become a new revision (change restored, restored_from the revision copied), checked as an update is (its playlist must still exist and be approved), and every screen of the old and the new audience re-resolves, unless the campaign was paused and stays paused.

Earlier revisions stay as they were. If-Match is required and names the current revision (invalid_request when absent, revision_conflict when stale). A revision whose content is the current content changes nothing and answers the current campaign. The same access as PATCH.

Publishes a test. A test publish is a PATCH of a draft with paused false and an audience that is a test folder or a few screens; promote then copies the audience of revision (the draft's own, paused, revision) onto the campaign in one write (change promoted, restored_from the revision copied) and every screen of the old and the new audience re-resolves.

Refused (invalid_request, naming revision) when that revision was not paused, since it is not a draft, and when the campaign is paused now, since there is no test to promote. If-Match is required and names the current revision. A revision whose audience is the current one changes nothing. The same access as PATCH.

Promote is schedule change control, which the Enterprise plan includes; a project whose plan lacks it is refused with feature_not_in_plan (402). Revision history, restore and previews are open on every plan.

The campaign's reach. counts covers every live screen in its audience (audience, then one count per status); items is one page of those screens in screen id order with the campaign's standing on each (see CampaignStatus).

A caller limited to screens (docs/screen-scope.md) sees and counts only the audience screens inside its scope; counts and paging cover that set.