Projects API

Returns current confirmation details, deletion blockers and archived devices that will be disconnected. allowed is false, with a reason, when the caller may not delete the project (only its owner or an administrator of its organization may; for an agent, its responsible person) or a blocker remains.

The owner transfers ownership to a verified existing project member; this grants no new membership. The new owner's membership leaves any screen_scope and upload_scope, so the new owner reaches the whole project.

A dashboard session of an admin of the project's organization who is a member transfers ownership the same way, from whoever owns the project; an organization admin who is not a member uses PUT /api/organizations/{org_id}/projects/{project_id}/owner.

Owner-authorized move transfers screen occupancy and new usage to the destination payer atomically; historical charges keep their payer. A destination already holding as many live projects as its plan allows is project_limit_reached, whose required_plan names the plan with room, absent at Enterprise.

Lists destinations the owner administers or whose verified domain matches their verified email.

Lists every active membership of the identity, with organization and owner context, including memberships omitted from this token or its grant's consent. Each entry marks in_token; discovery adds no authority and has no 64-project cap.

Creates a named project owned by the verified responsible person. With no organization named, it goes to the person's verified-domain organization, else the current project's organization, else the organization the person used most recently among those they administer or hold as their free one, else a new organization.

An organization name selects exactly one visible match, otherwise creates a new organization. A person holds one free Standard organization; a new organization beyond it is free_organization_limit, naming the one they hold.

An organization holds at most as many live projects as its plan allows (Standard 1, Plus 3, Premium 10, Education 50, Enterprise 100, widened by its featuresets); one more is project_limit_reached, whose required_plan names the plan with room, absent at Enterprise (contact support).

An exact idempotent retry redelivers its sealed membership credential for ten minutes. Enrollment is exempt from the limit.

Under an agent access JWT (identity scope, access:manage, a grant with identity access Manage) no project token is delivered; the project joins the grant with Manage and every capability, and a refresh with its project_id returns a token for it.

Lists invitation lifecycle records for the current project, excluding sign-in resets. Recipient addresses are visible to the owning project, which supplied them. Tokens and credential URLs are never listed.

Creates member or ad-buyer invitations. Email delivery never returns a credential. Link delivery is member-only and returns one URL, including on exact idempotent replay within 24 hours. Email invitations expire after seven days; links expire after 24 hours. Outstanding email invitations of the same kind, address, and project are reused.

A member limited to screens does not invite people (outside_screen_scope).

A project_member email invitation to a person who would be an external guest of the project's organization (it is not their home organization) is subject to that organization's guest policy, and guest_not_allowed (403) answers when the policy (allow, domains or none) does not admit the address. Accepting the invitation checks again.

Staff and the organization's own admins are exempt. A screen_scope on the invitation is screen scope, which the Enterprise plan includes; a project whose plan lacks it is refused with feature_not_in_plan (402).

Revokes an outstanding invitation. An accepted invitation returns invitation_consumed. A member limited to screens does not revoke invitations (outside_screen_scope).

Accepts a sign-in reset request without revealing whether a person holds the address.

A person whose address is unverified, such as a self-serve signup, is found too, and completing that reset, which its owner must confirm with replace_unverified_account, gives the inbox's owner a new account (a new person with the reset's credential, a new organization and project) and deletes the unverified person, whom nobody had shown the address belonged to.

A reset link expires one hour after it was last requested. While a person's link is live and less than a day old, another request sends that same link again (at most once every ten minutes) and moves its expiry to one hour from the request, so a request never stops the link already in the inbox; otherwise a new link replaces it. There is no limit per address.

Completing a reset removes the person's other passkeys (every passkey for a password reset), removes the password when the new credential is a passkey, discards a pending email change and ends every session. With or without a person, the request also re-sends at most ten invitations addressed to the email, and any one invitation at most once an hour.

Of the ten most recent non-deleted projects whose contact address matches, each active project with a catalog plan and ownership still pending from enrollment gets its enrollment invitation back, even when it expired or its recipient already joined as an ordinary member.

Accepting that enrollment invitation with the existing sign-in completes the ownership claim; requesting recovery alone changes no ownership or credentials. Pending emailed member and ad-buyer invitations to active projects with a catalog plan, and pending organization admin invitations to live organizations, fill the rest, newest first.

A re-sent invitation keeps its ID and gets a new link and expiry; the old link stops working and the project's outstanding invitation count is unchanged. An expired enrollment returns as a new invitation that takes an invitation slot again, so the count rises by one, and it is skipped when the project is full.

Other expired invitations, and revoked, accepted and link invitations, are not re-sent.

Creates a new project and its first agent through explicit bundled-CLI enrollment, even when the contact address already belongs to a person or project. The contact email stays unverified and grants no authority; malformed addresses return invalid_request.

Queues an enrollment invitation in the same transaction. project_name is optional; omission uses a readable two-word name. Exact idempotent replay precedes rate limits. Persist the permanent credential before reporting success; its replay envelope expires at issuance_expires_at and later retries return credential_issuance_expired.

The idempotency record lasts 24 hours.

Starts an AgentID (OIDC) browser sign-in on the API host derived from the runtime public origin (https://play.<domain> -> https://api.<domain>). Sets a single-use binding cookie and redirects to the AgentID authorization endpoint with PKCE S256. Answers only on the API host.

While the relying party has no client id and secret the route renders a plain unavailable page with 503.

Completes an AgentID browser sign-in on the API host. Requires iss equal to the configured issuer, the binding cookie, and an unexpired single-use transaction.

Exchanges the code with client_secret_basic and PKCE, verifies the ES256 id_token (iss, aud, exp with 60 s skew, nonce) against the cached JWKS, calls userinfo and enforces the owner rules, then renders a single-use claim-code page. A subject already bound to an agent renders the already-enrolled page.

This route never creates a project, identity, or invitation.

The calling project. Does not debit the 1-credit API meter, so a zero-remaining project can still read remaining and recover. After a successful project principal, authenticated /api JSON and problem responses include ScreenRig-Credits-Remaining, ScreenRig-Credits-Reset, and ScreenRig-Credits-Included as whole credits.

SSE, runtime, content, and unauthenticated responses omit them.

Renames the current project. Names contain 1–60 printable characters and no URL-looking text.

Only the project's owner or an administrator of its organization may delete it; any other caller is refused with forbidden. A person must also be a member of the project.

An agent needs the target membership project capability and deletes for its responsible person, who must be the owner or an organization administrator; an agent without a responsible person cannot delete, except the agent that enrolled the project while no person has accepted its enrollment.

Also requires the current name and revision, zero non-archived screens, no credit, reservations or debt in its own wallet and no live advertising. A negative balance run up under free or launch terms does not block; deletion writes it off with a project_delete_writeoff ledger entry. Queues member notices and uses the irreversible tombstone.

The calling project's plan, independent advertiser/screens flags with their revision, the derived effective capability set, the plan features it has (plan_features) and its limits (limits). Never reflects a client claim; an unknown plan fails closed as forbidden.

The organization's own audit log: changes to its administrators, domains and billing settings, with the same entries, filters and formats as GET /api/audit. Requires an administrator of the organization. Part of the audit log, which the Enterprise plan includes; an organization whose plan lacks it is refused with feature_not_in_plan (402).

Every plan records its changes.

The organization's notifications, of every channel, oldest first (at most 50).

A notification belongs to the organization and covers every project of it, including projects added later (project_ids absent), or the chosen projects (project_ids); it acts on the screens, sources, campaigns and cards of those projects exactly as a project notification does. status is failing while any covered project's deliveries are, and failing_since, last_success_at and last_failure_at fold the covered projects' (the earliest failure start, the latest success and failure).

A webhook's signing secret is never returned here. Requires an administrator of the organization; anyone else is not_found.

Creates a notification of the organization, with the members of POST /api/notifications and the projects it covers: project_ids absent or null covers every project of the organization (those it has and those it gets), a list covers exactly those, each a live project of this organization (invalid_request otherwise).

An email notification's recipients are owner (each covered project's owner), or user_ids of people of the organization (its admins and home members) or members of a covered project; each project still mails only the people who are members of it.

An organization has at most 50 notifications, not counting the defaults the system makes (notification_limit_reached). The same plan features gate the channels, rules and conditions as on the project routes, judged on the organization's plan. Each covered project gets notification.created, and the change is recorded in the organization's audit log.

A webhook's signing secret is returned only in this answer and in rotate-secret; one secret signs every covered project's deliveries. An exact retry with the same Idempotency-Key returns this same answer, secret included, for twenty-four hours.

One notification of the organization, as GET /api/organizations/{org_id}/notifications shows it.

Changes any member PATCH /api/notifications/{id} changes, in the notification and in every covered project, and project_ids: absent leaves the projects, null covers every project, a list covers exactly those. A project that gains the notification starts at its current event (nothing earlier is sent); one that loses it has the notification deleted.

Each covered project gets notification.updated, and the change is recorded in the organization's audit log.

A change that makes the notification cover a project it does not cover now is gated like a create of the notification as it will be (its channel, rules and glass conditions, on the organization's plan); covering fewer projects is never gated, and switching a list to every project always covers more. If-Match guards the revision.

Deletes the notification from every project it covers, with notification.deleted in each, and records it in the organization's audit log. Pending notices are failed with webhook_deleted.

Webhook notifications only (any other channel is invalid_request). Replaces the signing secret in every covered project at once, so one receiver keeps verifying one secret, and returns the notification with the new one in secret.

As on POST /api/notifications/{id}/rotate-secret, at most one attempt per project already in flight may still arrive signed with the old secret. An exact retry with the same Idempotency-Key returns the same new secret for twenty-four hours.

Sends one notification.test through the first project the notification covers (by project id), as POST /api/notifications/{id}/test sends one through its project: one delivery, whose outcome the deliveries list shows, attempted once.

Every covered project has the same receiver, destination and secret, so one test proves the channel; the email of a test goes to the recipients of that project. A notification that covers no project is invalid_request.

The delivery logs of every project the notification covers, as one list, newest first by when each row was queued. Each row names its project (project_id), and its id opens GET .../deliveries/{delivery_id}/attempts. Pass next_cursor back as before for the next page.

One delivery's attempts, newest first, the most recent 20. A delivery that is not one of this notification's is not_found.

Mails an email notification's person again after they stopped it with the unsubscribe link in its mail, in every project the notification covers (the link stops them in all of them). Idempotent: a person who is not stopped changes nothing, and the answer is the notification as it is.

A change bumps the revision and appends notification.updated with details change resubscribed, user_id and via api to each covered project.

Lists the report kinds GET /api/reports/{kind} builds, with the filters each takes, and the formats a report is written in. Needs the reports capability.

Lists the project's scheduled reports, oldest first (at most 50), each with its next run and the outcome of its last. Requires the project capability.

Schedules a report to be emailed, as a PDF, XLSX or CSV attachment, daily, weekly or monthly at an hour in a time zone.

Each run covers the period before it in UTC days: yesterday, the seven days before, or last month. recipients are members of the project, named by user_id or by the email address of the member; anyone else is refused, so a subscription is never a way to mail an outsider, and a member who leaves stops receiving it.

A failed run is retried and shows as last_status failed with last_error. At most 50 per organization across its projects (report_subscription_limit_reached).

Requires a designated admin of a live organization, exact same-origin cookie authentication and JWT CSRF. Actor and return URL are server-owned. Response is private and no-store. Open to an organization delegated to a reseller too, for its card and past invoices.

Requires a designated admin of a live organization, exact same-origin cookie authentication and JWT CSRF. The actor is server-owned. Disabling preserves saved amounts and monthly spend; amount fields are ignored when disabled. Response is private and no-store. Changing settings clears a recoverable pause only after any failed payable invoice is safely voided.

Enabling it for an organization delegated to a reseller answers 409 billed_by_reseller; disabling stays open.

Payment projections for a live organization. Requires its designated admin cookie; staff visibility alone grants no purchase access. Unconfigured payments return available false. Never grants credit from a browser return.

Start a prepaid purchase for a live organization designated admin. Requires same-origin cookie authentication and, for JWT sessions, a matching CSRF header. Organization, customer, actor and return URLs are server-owned. Credit applies only after the billing service confirms payment. Retry ambiguous responses with the same Idempotency-Key and amount.

An organization delegated to a reseller answers 409 billed_by_reseller.

The organization wallet. Requires a designated organization admin, an admin of the reseller the organization is delegated to, or a staff session. Grants no project membership.

Journal entries attributed to this organization at charge time, with project and payer identities. Moves do not transfer historical access. Entries predating recorded organization context remain in their project statements. Read by the same people as the balance (getOrganizationBillingBalance).

The organization's usage pool and each project's share for a UTC month. Covers usage paid by this organization; other payer costs are in the organization statement. Read by the same people as the balance (getOrganizationBillingBalance).

Visible organizations, including empty organizations for their admins. Names are not unique.

Designated admins and agents whose verified responsible person is an admin may rename an organization. No project permission or membership is granted.

Turns Require review for agent changes on or off. While on, every agent and service client on the project is held to Propose access on every request, whatever its credential carries. The project owner or an admin of the project's organization only (forbidden otherwise); staff shadow sessions cannot change it.

If-Match carries review_policy_revision (0 allowed) and is required; a stale value is revision_conflict. Turning it off requires proof, the fresh passkey or password proof agent connection approval uses; turning it on does not. Open reviews stay decidable either way. Appends project.review_policy_changed.

Returns current confirmation details, deletion blockers and archived devices that will be disconnected. allowed is false, with a reason, when the caller may not delete the project (only its owner or an administrator of its organization may; for an agent, its responsible person) or a blocker remains.

The owner transfers ownership to a verified existing project member; this grants no new membership. The new owner's membership leaves any screen_scope and upload_scope, so the new owner reaches the whole project.

Owner-authorized move transfers screen occupancy and new usage to the destination payer atomically; historical charges keep their payer.

Lists destinations the owner administers or whose verified domain matches their verified email.

Lists invitation lifecycle records for the current project, excluding sign-in resets. Recipient addresses are visible to the owning project, which supplied them. Tokens and credential URLs are never listed.

Creates member or ad-buyer invitations. Email delivery never returns a credential. Link delivery is member-only and returns one URL, including on exact idempotent replay within 24 hours. Email invitations expire after seven days; links expire after 24 hours. Outstanding email invitations of the same kind, address, and project are reused.

A member limited to screens does not invite people (outside_screen_scope).

A project_member email invitation to a person who would be an external guest of the project's organization (it is not their home organization) is subject to that organization's guest policy, and guest_not_allowed (403) answers when the policy (allow, domains or none) does not admit the address. Accepting the invitation checks again.

Staff and the organization's own admins are exempt. A screen_scope on the invitation is screen scope, which the Enterprise plan includes; a project whose plan lacks it is refused with feature_not_in_plan (402).

The calling project. Does not debit the 1-credit API meter, so a zero-remaining project can still read remaining and recover. After a successful project principal, authenticated /api JSON and problem responses include ScreenRig-Credits-Remaining, ScreenRig-Credits-Reset, and ScreenRig-Credits-Included as whole credits.

SSE, runtime, content, and unauthenticated responses omit them.

Renames the current project. Names contain 1–60 printable characters and no URL-looking text.

Only the project's owner or an administrator of its organization may delete it; any other caller is refused with forbidden. A person must also be a member of the project.

An agent needs the target membership project capability and deletes for its responsible person, who must be the owner or an organization administrator; an agent without a responsible person cannot delete, except the agent that enrolled the project while no person has accepted its enrollment.

Also requires the current name and revision, zero non-archived screens, no credit, reservations or debt in its own wallet and no live advertising. A negative balance run up under free or launch terms does not block; deletion writes it off with a project_delete_writeoff ledger entry. Queues member notices and uses the irreversible tombstone.

Lists applications newest first, at most 500 per page. Names are labels and need not be unique; address an application by id. 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.

Streams one CLI-produced tar.gz directly into bounded durable staging. Metadata is carried in headers so the archive is never base64-wrapped or materialized as JSON by the server.

The proxy in front of the API ends a request it has not answered within about 100 s, so a large archive on a slow uplink fails here; POST /api/applications/uploads sends the archive straight to the object store instead.

Declares a direct upload of one CLI-produced tar.gz that creates a new application. The answer is a signed authorization for exactly one object PUT of the archive, so the bytes go straight to the object store and never through the API, whose proxy ends a request it has not answered within about 100 s.

PUT the archive to upload_url, then commit with POST /api/applications/uploads/{id}/commit and wait on the operation. The application, its release and the receiving operation exist from this answer on, as after POST /api/applications. An upload not committed within 24 hours fails, and an application that never published a release is removed.

The same Idempotency-Key and body answer the same upload with a freshly signed URL. GET /api/capabilities sets features.application_direct_uploads where these routes are served.

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 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.

Default list returns pairing_pending and active screens. Pass state=archived to list archived screens only. Pass tag to list only screens whose tags contain that exact tag; untagged screens are omitted when the filter is present.

Pass field, once per field, as NAME:VALUE to list only screens whose fields hold every value, and near as LAT,LON,KM to list only screens located within KM kilometres of the point; screens with no location are omitted, and every filter combines with state and tag.

Pass folder as a screen folder ID to list only the screens directly inside it (not those of its subfolders), or root for the screens outside every folder.

Screens are newest first, at most 500 per page. 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. A caller limited to screens (docs/screen-scope.md) lists only the screens in its scope.

A request that names no project leaves out each project where the caller is limited to screens; name the project to list it.

Lists every screen folder in the project, at most 1000, ordered by name.

Folders organize screens and target them: a campaign audience leaf {"folder": ID} matches the screens in that folder and every folder inside it, a fleet action selector by:folder acts on the same screens, and a folder's default_playlist_id is what its screens without a playlist of their own show. parent_id is null at the project root; build the tree from parent_id. screens counts the live screens directly inside each folder.

A screen's folder is Screen.folder_id. A caller limited to screens (docs/screen-scope.md) lists the folders inside its scope and the folders above them, which are read-only so its tree has a root; folders above carry no screens count and sibling folders are hidden. A request that names no project leaves out each project where the caller is limited to screens.

Creates one screen folder at the project root (parent_id null or absent) or inside parent_id. Names are trimmed, hold 1 to 100 Unicode characters with no controls, are not "." or "..", and are unique among their siblings (resource_conflict).

An organization holds at most 1000 folders across its projects (quota_exceeded) nested at most 10 deep (invalid_request). default_playlist_id, when set, must name an approved playlist (playlist_not_approved). Emits screen.folder_created.

A caller limited to screens (docs/screen-scope.md) creates a folder only inside a folder of its scope; the project root or any other parent is outside_screen_scope. Creating a folder inside a protected folder is a protected_change review (202 pending_review) decided by a second approver.

Moves screens (screen_ids) and folders (folder_ids) into one folder (folder_id), or to the project root when folder_id is null, in one all-or-nothing request of at most 1000 ids. Every id must exist (not_found). A folder cannot move into itself or a folder inside it, and the move must keep every folder within 10 levels (invalid_request).

Items already in the destination are left as they are; each moved screen and folder advances its revision. Moved screens re-resolve their playlist within about 15 seconds: levels names the campaigns whose folder audience they enter or leave and the folder default playlists they gain or lose. Emits screen.moved.

A caller limited to screens (docs/screen-scope.md) moves screens and folders inside its scope into a folder of its scope; any id or destination outside it, and the project root, refuse the whole move (outside_screen_scope), also when a screen leaves the scope between the check and the write.

A move into or out of a protected folder is a protected_change review (202 pending_review) decided by a second approver.

Answers what a subject's screens play over [from, to) and why, for the dashboard's Schedule calendar: exactly one of screen_id, folder_id (the screens in the folder and every folder inside it), tag, or campaign_id (the screens in its audience).

Screens whose stacks have identical inputs (the same levels, default, timezone and display count) share one group with one timeline, so a large subject costs tens of timelines; a group lists up to 500 of its screens and an answer at most 200 groups (truncated).

Each group carries its stack, highest first (takeover, campaigns that reach the screens, their own schedule entries, then the default playlist or the nearest folder's), each level's spans (plays on every display it targets, partial with the displays it plays on, outranked, or conditional while it waits on interaction or a data condition only a Player observes), what each display shows (on_screen; the main region of a full page), and conflicts (two campaigns of one priority holding at once; a level that holds yet never plays). from and to are RFC 3339 instants, to after from, at most 93 days apart; they are truncated to the minute.

Rules are read in each group's timezone as the sweep and every Player read them; every level is judged playable. A caller limited to screens (docs/screen-scope.md) must send a screen_id or a folder_id inside its scope; a tag, a campaign_id or no subject is outside_screen_scope.

Answers a sheet with the columns a schedule import reads and three example rows (a screen code, a screen folder and a tag), as CSV or, with format=xlsx, an XLSX workbook.

Reads a sheet of schedule rows against the project and answers what committing it would do, writing nothing.

Each row names a target (a screen by id, by the value of a screen field such as a room code, or by name; folder:NAME; tag:NAME; several separated by ; or |), content (a media file name, or playlist:NAME or a playlist id), a start and an end (a date alone as the end closes that day), and optionally timezone, days (Mon-Fri), a daily window (daily_start, daily_end), priority 0 to 100, a name and display numbers.

Times are read on each screen's own clock; a timezone column converts them from another zone.

Every row is checked and reports its errors by column: unknown or ambiguous screen, folder or tag, missing or ambiguous file, a file that cannot fill a screen, invalid or reversed times, an end in the past, no timing at all, a screen without a time zone or a default playlist, two rows holding at once on a screen at the same priority, and more levels than a screen holds (32), or more campaigns than its organization holds across its projects (100; each shared level is one).

Rows that agree on content, times, priority and name become one level: one screen is an entry of that screen's own schedule; several screens, a folder or a tag are one shared level (a campaign), which outranks a screen's own levels.

The answer lists the levels with what a commit does to each (create, update, unchanged), the levels an earlier run of the same import made that the sheet no longer has (removals), the stacks of the screens as they would be (calendar), and a fingerprint to send to the commit. The sheet is JSON rows, CSV or XLSX, at most 5,000 rows.

Not available to a caller limited to screens (outside_screen_scope). Schedule import is part of the Enterprise plan; a project whose plan lacks it is refused with feature_not_in_plan (402). The template is open on every plan.

Commits a previewed import: the same sheet and the fingerprint its preview answered. Every level is created, updated or removed, the screens' schedules and the shared levels written in one transaction, and the import event schedule.imported appended: all rows apply or none does.

The one-file playlists the sheet's files need are made first (they change nothing on any screen). A sheet whose rows have errors is refused (schedule_import_invalid); a project that changed since the preview, or rows that read differently, is refused (schedule_import_stale), and the client previews again.

Importing the same sheet again under the same name changes nothing; a changed row updates its level and a removed row removes its level. Needs a person who can approve in the dashboard and a credential with write access for an agent.

A commit that would update or delete a reserved campaign answers reserved_item (403) and writes nothing, unless a person who can approve commits it.

A commit that reaches a protected screen is refused whole with protected_target, also when the import has no levels but removes import entries of a protected screen or deletes an import campaign whose audience reaches one.

In a project with protected screen folders a commit whose preview fails on a service, not on the sheet, answers dependency_unavailable and writes nothing: send the same request again after a short wait. A sheet, campaign or screen validation error answers as the commit would (invalid_request and the other problems above).

Not available to a caller limited to screens. Schedule import is part of the Enterprise plan; a project whose plan lacks it is refused with feature_not_in_plan (402). The template is open on every plan.

Claims one browser-link code for the authenticated project and atomically creates exactly one first pairing_pending screen plus its existing browser provisioning grant. Enrollment remains project-only. The response is safe metadata only and never contains a provisioning token, fragment URL, cookie, or proof.

Claims one fleet-global six-character Player pairing session. Exact Idempotency-Key retries return the durable original result without consuming quota again.

The dashboard session claims into its current project with the same body, Idempotency-Key, budgets and problems, except that its not_found for an unknown or already-claimed code names no CLI command; it is a state change, so it follows the dashboard mutation rules, a shadow session without staff write mode is refused, and the events the claim appends name the dashboard user. folder_id names the folder the screen lands in.

A caller limited to screens (docs/screen-scope.md) must send a folder inside its scope and pairs only as a person who can approve (outside_screen_scope, approver_required).

Optional browser-only new-screen provisioning. Always creates one new pairing_pending screen; at most five wait to pair at once (quota_exceeded). Exact retries redeliver the same fragment token for ten minutes. Six-character pairing remains the default and only recovery flow. folder_id names the folder the screen lands in.

A caller limited to screens (docs/screen-scope.md) must send a folder inside its scope (outside_screen_scope otherwise).

Applies one action to a selected fleet with no screen-count cap. Select unique screen_ids or a tag matching active screens in creation order. The resolved selection is pinned before any mutation, stored in bounded chunks, and kept for twenty-four hours under Idempotency-Key.

Each step uses its single-screen mutation path, preserving revisions, events, runtime signals and per-screen limits. A response contains one bounded page of results; matched, succeeded and failed describe that page. HTTP 202 includes total, offset and next_cursor. Continue with the same selector, action and Idempotency-Key, passing next_cursor as after.

Honor Retry-After when present, including a page with zero results. The response echoes Idempotency-Key, including a generated key when the caller omitted it; retain this key for continuations. HTTP 200 finishes the selection. Answered pages replay exactly, including per-screen failures; interrupted steps replay without repeating their effects.

Large actions are paced against the existing 600-per-minute organization budgets for reload, toast, takeover, playlist schedules, reboot, display and display schedules; organization exhaustion pauses the action instead of refusing the fleet. Per-screen exhaustion fails that screen alone.

An assign, takeover or set_playlist_schedule step that binds a playlist with a format to a screen whose wall has another shape fails that screen alone with 409 playlist_format_mismatch. Assign and tag changes have no message budget.

An assign whose playlist has an iframe src or application params that read a screen token some screen of the page lacks adds a screen_fact_missing warning to that page (warnings, PlaylistWarning). Partial failure is a normal result. All pages and retries under one key are one metered action.

Requests use a bounded byte payload; use a tag for a selection larger than the transport payload. A malformed selector or action is refused before any screen is touched. selector or action is refused before any screen is touched.

A caller limited to screens (docs/screen-scope.md) selects by screen_ids or by folder, every screen inside its scope; a tag selector, a screen outside the scope or an unknown one refuses the whole action (outside_screen_scope) before anything is pinned or proposed.

Assign, takeover, takeover_clear, set_playlist_schedule and clear_playlist_schedule that reach a protected screen become a review decided by a second approver (202 pending_review) at every access level; set_tags, add_tags and remove_tags on a protected screen are protected_target (409).

A set_playlist_schedule action with a paused entry (a draft) is schedule change control, which the Enterprise plan includes; a project whose plan lacks it is refused with feature_not_in_plan (402).

Shows browser tabs on screens in the named project; the request, answer, access and limits are those of POST /api/tab-shares.

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.

createCampaign for the project named in the path. 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).

Lists the project's connections, newest first, at most 200 a page; pass next_cursor back as after for the next. A secret, a key or a refresh token is never returned: secret shows whether one is held and a hint that is not secret. A read never carries a consent link.

Creates a connection to Microsoft or Google in this project: mode own_app with the customer's own credentials, or mode screenrig_app, which answers consent_url, a one-time link for the person who completes it (see createConnection). Appends connection.created. An exact retry with the same Idempotency-Key returns the same connection.

Lists the project's BI connections, oldest first, 200 to a page; pass next_cursor back as cursor for the next. A secret is never returned: secret shows whether it is set and its last 4 characters.

Adds a connection to a BI system the project owns. For Grafana: its address (http or https on a public host, with an optional path prefix) and a service-account token with the Viewer role. The token is sealed and never returned.

Grafana renders dashboards for screens through its Image Renderer plugin or remote rendering service, so the customer installs one; run POST /api/bi-connections/{id}/test to check. For Power BI (kind powerbi): config.tenant_id and config.client_id of a Microsoft Entra app registration and its client secret value as secret.

A Power BI admin must turn on the Developer settings Embed content in apps and Service principals can call Fabric public APIs for the app (admin portal, Tenant settings), the app must be a Member or Admin of each workspace it shows, and reports need an Embedded, Fabric or Premium capacity for production use.

For Tableau (kind tableau): config.url (the https address of Tableau Server, or of your Tableau Cloud pod such as https://10ay.online.tableau.com), config.site (the site content URL, empty for the default site), config.client_id and config.secret_id of a connected app with direct trust, config.username (the Tableau user the screens views are shown as) and the secret value as secret.

Add the answer embed_origin to the connected app domain allowlist and enable the secret. Anyone holding a screen ticket can embed any view that user can see, so use a user that sees only screen dashboards. Tableau Cloud, or Tableau Server 2023.3 or later.

For a signed-in web page (kind web): the service account of a site that shows its dashboard behind a sign-in. config.login_mode is auto (config.login_url, config.username and the password as secret: the renderer opens the sign-in page and fills the form), steps (config.login_url and config.steps, a script of goto, fill, click, press, wait_for and wait_ms steps whose values may hold {{username}}, {{password}} and {{otp}}) or none (no sign-in: the connection shows pages with the cookies you give it). totp_secret is the base32 key, or the otpauth:// address, of the account's authenticator app: the server computes the one-time code (RFC 6238) and sends the renderer only the code. cookies is a cookie jar exported from a signed-in browser, for a site whose sign-in cannot be scripted (single sign-on that approves on a phone, a device check); the server keeps the jar and renews it from the cookies each capture returns, so a sign-in is rare.

The password, the seed and the cookies are sealed and never returned. Use a read-only service account. The password is typed only into config.login_url and the goto steps, so moving those to another origin needs secret again. After five refused sign-ins in a row the connection stops signing in until its credentials change.

A server with no page renderer answers bi_web_unavailable. Appends bi_connection.created. An exact retry with the same Idempotency-Key returns this same answer.

Lists the project's BI views, oldest first, 200 to a page; pass next_cursor back as cursor for the next. Each carries embed_url, the address an iframe primitive shows (content_fit fill); it is null where this server has no embed host.

Adds a view of a connection's Grafana dashboard or one panel of it (url: a /d/{uid}/... address on the connection's host, or target), or of a Grafana public dashboard link (kind grafana and target.public_url, no connection).

Put the answer's embed_url in an iframe primitive: the server renders the dashboard as a PNG through Grafana's /render API, refreshed every refresh_s (30 to 86400, default 300) and shared by every screen of the same size; the screen never talks to Grafana. A public dashboard plays live from Grafana, which must allow embedding.

The embed page shows only a ticket the screen's manifest carries, so a view plays only on the screens of its own project.

For Power BI (kind powerbi): a report of a workspace the connection's app is a member of (url: an app.powerbi.com /groups/{workspace}/reports/{report} address, or target with workspace_id and report_id), with pages to show and rotate_s to rotate through them (pages listing two or more, or rotate_all_pages, need rotate_s of 10 to 3600; one report page needs none), and refresh_s of 0 (no refresh) or 60 to 86400 (default 300).

The page asks the server for a short-lived view-only embed token (GenerateToken, App owns data) and renews it before it expires; the screen never holds the client secret. A Power BI Publish to web link is a view without a connection (kind powerbi, target.public_url https://app.powerbi.com/view?r=...), framed as it is.

For Tableau (kind tableau): a view of the connection site (url: an address copied from Tableau, such as https://HOST/t/SITE/views/WORKBOOK/VIEW or Tableau Cloud https://HOST/#/site/SITE/views/WORKBOOK/VIEW, or Workbook/View; or target.view), optionally with target.rotate_sheets and rotate_s of 10 to 3600 to turn the workbook published sheets (rotate_s and rotate_sheets go together; rotate_sheets may be given as the whole target beside url), and refresh_s of 0 (no refresh) or 60 to 86400 (default 300).

The page asks the server for a five minute JWT with only the embed scope, signed with the connected app secret, and builds the Embedding API v3 tableau-viz from the Tableau host; the screen never holds the secret.

A Tableau Public viz is a view without a connection (kind tableau, target.public_url, rebuilt as https://public.tableau.com/views/WORKBOOK/VIEW) and takes rotate_sheets too. For a web page (kind web): a page of the web connection's site (url: an https address on a public host, with no target).

The browser on the edge opens it signed in, waits for the element wait_for when set and wait_ms milliseconds (up to 10000), and draws clip, a CSS selector, when set, else the whole page.

The image is drawn every refresh_s (60 to 86400, default 300) and shared by every screen of the same size, and only while a screen shows the view; when a capture fails the last image stays on glass. Set wait_for to an element that exists only when the page is signed in, so a sign-in page is never shown. Appends bi_view.created.

Lists the project's CAP alert triggers, oldest first (at most 20), each with its ingest url, username and latest alert. The password is never returned here.

Creates a CAP alert trigger: one inbound URL an emergency notification system (Everbridge, Rave, Alertus, IPAWS relays and other CAP 1.2 senders) posts alerts to, with HTTP Basic credentials.

The answer is the only place the password appears (with the rotate answer): store it in the sending system at once. target is a tag (every active screen with it when the alert arrives) or up to 500 screen_ids.

An alert takes every target screen with a default playlist over until the alert's <expires>, else for default_for_seconds (60 to 604800, default 3600); see POST /api/triggers/{id}/cap. An organization has at most 20 triggers across its projects (trigger_limit_reached). Appends trigger.created.

An exact retry with the same Idempotency-Key returns this same answer, password included, for twenty-four hours. A trigger whose selector reaches a protected screen is protected_target (409), and a failed read of screen protection is dependency_unavailable (500, retry the same request); a trigger is not available to a caller limited to screens.

Lists durable project events ascending by sequence.

Paging is contiguous: pass the returned next_cursor as after to continue exactly where the page stopped. next_cursor is the cursor of the last returned event while newer events already exist, and null at the end of the history. limit defaults to 50 and accepts 1-200; a value outside that range is refused with invalid_request and an errors[] member naming limit.

Offset paging is not supported. source=log lists the Player log instead: the condition reports Players send (runtime.reported) ascending by receipt time, filtered by screen_id and severity over a window from to (default the last 24 hours, at most 31 days).

Its cursors are opaque: lg1_ or ev1_ by where the server keeps the Player log, so pass back the one a page returned; a cursor of the other kind is refused with invalid_request naming the field. Player log records have no sequence, are not on GET /stream/project and are not delivered to webhooks.

A record is acknowledged when the Player log queue accepts it and is kept for the project's event retention. A poll with the last cursor and the default window follows the log. Player log records are not in the default (source=project) list. from and to are refused with invalid_request unless source is log.

The project list takes screen_id, playlist_id and application_id to read the events of one screen, playlist or application, all scoped to the project of the credential (an id names which events to read, never whose): screen_id keeps the events whose resource is that screen; playlist_id the events whose resource is that playlist plus the events that name it as details.playlist_id (a screen taking it); application_id the events whose resource is that application plus those whose resource carries it as application_id (its releases and key/value entries).

A value that is not an id of its kind is refused with invalid_request naming the field; playlist_id and application_id are refused with source=log, whose records belong to a screen only.

Both sources take resource_id, type and severity (a minimum), combined with each other, with the id filters and with paging; a Player log record is a runtime.reported record whose resource is its screen, so a resource_id that is not that screen or a type that excludes runtime.reported answers an empty page. before (or order=desc) pages newest first: next_cursor is then the cursor of the oldest returned item and passed back as before continues to older items.

Without from, a newest-first source=log page reaches past the default 24 hours to the oldest record the project's event retention keeps, at most 31 days below the page's upper edge per request. A newest-first source=log page may hold fewer than limit records, even none, with a next_cursor; null still ends it, at the end of the retained log.

A caller limited to screens (docs/screen-scope.md) reads a filtered feed: events of screens inside its scope, of the screen folders it can see (its own, the folders above and inside; screen.moved only when the destination is inside its scope), of campaigns, playlists, media, applications and cards, and playlist_change reviews.

Every other event is left out, so a page can hold fewer events than limit, even none, with a next_cursor; keep paging with it. source=log needs a screen_id inside its scope. Events about the project itself are not sent.

The calling project's plan, independent advertiser/screens flags with their revision, the derived effective capability set, the plan features it has (plan_features) and its limits (limits). Never reflects a client claim; an unknown plan fails closed as forbidden.

The calling project's source-aware balance snapshot. All millicredit amounts are canonical decimal strings. It is a snapshot, not authority to pay; rails_available is false while card, tax and cash-out rail are unavailable.

Stable cursor pagination over immutable posted journal entries for the calling project. Holds are not posted entries. Corrections link to the original event instead of rewriting it. There is no arbitrary grant or payout mutation on this surface.

The calling project's use for one UTC month, with the bytes served and received (never charged), the storage charged above the free storage of the payer's plan (allowance.storage_bytes), and the API requests, billed project stream events and webhook delivery attempts counted against the free 10,000 a month. A project paying for itself reads its own pool.

A project another payer pays for shares that payer's pool with the payer's other projects; it reads its own share, and payer names the payer. The payer's pool total stays on the payer's billing reads.

The calling seller's one network, including its resolved ScreenRig serving fee. Sellers cannot change that fee.

Creates the calling seller's one network if absent. Requires screens=true. Idempotent; repeating returns the same network.

Sets the seller's project default rate per 15 seconds of completed playback. A change that alters an accepted campaign's effective rate pauses that whole campaign with price_change_pending; a masked or no-op change does not. If-Match carries the network revision.

The calling seller's opted-in inventory.

Creates a reusable seller slot. Images are 5-30 seconds and videos at most the platform ceiling of 120 seconds. Ads are always muted.

Networks the calling advertiser currently belongs to, with the scope and review policy it was granted. Screen count is not a guaranteed impression count.

Binds one ready owned media revision to an immutable creative. Does not copy bytes, re-upload, or re-charge generation. Unknown or non-ready media is rejected.

Creates a draft campaign. Drafts hold no money, reserve nothing, and authorize no delivery. Activation requires an explicitly accepted quote.

Creative versions submitted to the calling seller for review. A seller sees only exact submitted creative, never the buyer's library.

Buyer-scoped spend and delivery counts for one campaign. Amounts are decimal mcr strings. It never exposes the seller's income, bank status, or project-wide usage.

Seller-scoped gross, serving fee and net for one window, with its own delivery evidence. It never exposes the buyer's wallet or other networks. Only authorized completed-play evidence establishes billable delivery. The window is at most 92 days; a wider window is invalid_request.

When it holds more than 5000 settlements the response sets truncated, totals and counts still cover all of them and rows lists only the earliest 5000.

Daily playback aggregates.

JSON returns at most 200 rows and is not rate limited. format=csv (or Accept text/csv without application/json) streams every matching row inside day_from to day_to (inclusive UTC days; defaults day_to today and day_from 30 days earlier; at most 366 days, else invalid_request) as CSV with a fixed header row (PlaybackAggregateCsv); only the CSV form spends the playback-export-org (30 per minute) and playback-export-ip (60 per minute) budgets.

Either form is one metered API request. Responses carry Vary Accept. A caller limited to screens (docs/screen-scope.md) must send screen_id and it must be a screen inside its scope (outside_screen_scope otherwise); the CSV forms follow the same rule.

Per-play records: one row per accepted playback.media_started (or legacy playback.video_started) and one row per accepted playback.application_started (release_id set, media fields empty) of the calling project, oldest first by received_at, ties by insertion. from (inclusive) and to (exclusive) bound received_at; to defaults to now, from to 24 hours before to, and the range is at most 31 days (invalid_request otherwise).

The newest 5 seconds are not returned yet: the effective to is at most now minus 5 seconds (settle lag), so a live tail never skips a row that commits behind its cursor. screen_id, media_id, playlist_id (the playlist the start was shown from), and tag (a screen tag the screen carried when the play was received) filter.

A playlist_id page may hold fewer than limit rows, even none, with a next_cursor when a long stretch of plays of other playlists was scanned; null still ends the range.

JSON is a page of at most limit rows (default 200, at most 1000) with next_cursor, null at the end of the range; pass it back as cursor with the same filters. order=desc (or before) pages newest first within the same range: next_cursor is then the cursor of the oldest returned row, null at the start of the range, and is passed back as before (exclusive) with the same filters; order=asc with before is refused with invalid_request naming order, and cursor with a newest-first page naming cursor.

A newest-first page may hold fewer than limit rows, even none, with a next_cursor; null still ends it.

A later page never skips a row that existed when the earlier page was read and does not repeat one, except that a start the Player re-sent after an unacknowledged report (the same play_id, received a moment later) can appear again on a later page; the CSV stream lists it once. format=csv (or Accept text/csv without application/json) streams every play from cursor to the end of the range as CSV (PlaybackPlayCsv), newest first below before with order=desc; limit is refused with CSV.

Metering is per request: every JSON page costs one API request credit, while one CSV stream of the whole range costs one. Every plays request (page or stream) spends the playback-export-org (30 per minute) and playback-export-ip (60 per minute) budgets.

A stream bounds each write (15 seconds) and ends when the client disconnects; if it fails after the 200 header the connection is aborted, so an export that reads to a clean end is complete. Responses carry Vary Accept. Plays are kept for the plan's event retention (30 days is the shipped floor; plan-based retention uses the plan's own 7- or 90-day window).

A caller limited to screens (docs/screen-scope.md) must send screen_id and it must be a screen inside its scope (outside_screen_scope otherwise); the CSV forms follow the same rule.

Play totals of the calling project over inclusive UTC days, read from the daily rollups: by=day returns one row per day with plays (screen_id or media_id narrows it to one screen or media), by=screen and by=media rank the busiest screens or media (top, at most 100), and by=screen_day returns the day series of the top screens (top at most 10). day_to defaults to today (UTC) and day_from to 29 days before it.

A day series spans at most 366 days (92 when narrowed to a screen or media); a ranking at most 92. Counts include every start the project has recorded, including those stored before play rollups existed.

Rollups follow ingestion by up to about 21 minutes. truncated is true when a ranking was built from slices of a window too large for one read: it covers the best keys of each slice. Not rate limited. One metered API request.

A caller limited to screens (docs/screen-scope.md) must send screen_id and it must be a screen inside its scope (outside_screen_scope otherwise); the CSV forms follow the same rule.