API reference

Choose the right service

The endpoint determines both the base URL and the credential. The request templates below use the declared service URL.

What you are doing	Service	Authentication
Managing screens and content	`api.screenrig.ai`	Agent bearer token
Running a Player	`play.screenrig.ai`	Browser cookies or native Player credentials
Managing a login and projects	`screenrig.ai/dashboard`	Dashboard cookies
Loading an application release	Its exact host under `apps.screenrig.ai`	Launch ticket or release cookie

Native Players use ScreenRig-Pairing during setup and ScreenRig-Session afterward. These requests must not include cookies. Browser endpoints use their own cookies.

Authentication names used below

projectBearer: The active agent token used by the bundled CLI, bound to exactly one project.
capability areas: Each agent credential carries a fixed set of areas: screens, content, playlists, advertising, reports, and project. A credential calls only routes in its areas; reports also reads any area. A request naming a missing area returns 403 forbidden with detail "This agent credential lacks the <name> capability." Connect a new agent installation with the needed capabilities to recover.
pendingAgentBearer: A newly collected token that can activate its agent installation.
revocableAgentBearer: The calling agent token, accepted for retrying its own disconnection.
agentConnectionAuthorization: A temporary ScreenRig-Agent-Connect credential for connection status and credential collection. It is never part of the browser approval URL.
pairing, device, and runtime cookies: Browser Player credentials. Each endpoint specifies which cookie it accepts.
dashboard session cookie: The signed-in person's session and selected project. The separate __Host-screenrig-signup cookie binds link-invitation signup, email verification, credential options, and acceptance. Neither cookie is an agent credential. The dashboard does not author playlists.
primitiveCapability: Short-lived access to one application's key/value storage from a playlist primitive.
demoSession: A private website demo session, separate from project and dashboard credentials. The website sets it after intake or a private invitation; flow identifiers never authorize access.
operatorBearer: Service operator access.

People, projects, and invitations

A person has one login and can belong to many projects. Enrollment always creates a new project and emails a project-member invitation to its contact address. The agent proposes a project name; each agent token remains bound to that project.

The dashboard lists the person's projects and switches the selected project for cookie-authenticated operations. Personal email and passkeys belong to the login, not the project.

Invitations share one create, list, revoke, and acceptance flow. Project members receive email by default; an explicitly requested member link is returned only to its creator. Ad-buyer invitations are email-only. Email invitations expire after seven days and member links after twenty-four hours. A new person creates a passkey; an existing person signs in before accepting. Link signup verifies the person's email before creating a login.

Sign-in reset is mailbox-only, expires after one hour, and replaces the person's sign-in credentials while revoking their other sessions. Request acknowledgment does not reveal whether an email has a login. Opening the dashboard is navigation, not a grant of authority.

Common request semantics

Idempotency: when an endpoint accepts Idempotency-Key, reuse that key and the identical request after a lost response; mismatch returns 409 idempotency_mismatch.
Revisions: when an endpoint requires If-Match, send the current resource revision; stale writes return 412 revision_conflict.
Cursors: list and SSE cursors are opaque.
Operations: uploads may begin in receiving, then use queued, running, succeeded, failed, or cancelled.
SSE: resume with the last cursor or Last-Event-ID. A stream.resync_required frame means refetch authoritative state and resume at its supplied head cursor.
Limits: capabilities publish active limits; rate limiting returns 429 rate_limited.

Credential persistence belongs to the plugin flow. The bundled CLI reads platform configuration outside the replaceable plugin directory.

Upload lifecycles

Applications

Submit an already-built deterministic archive and wait for validation, extraction, and immutable publication. screenRIG handles packaged static output.

Media

Declare exact type, size, and hash; follow the signed raw PUT method and headers verbatim; commit and wait. Treat signed URLs and headers as credentials.

Runtime and protected content

Pairing, device/runtime sessions, manifests, reports, events, launch tickets, and runtime K/V live on the trusted Player origin. Manifest media supports contract-defined ranges; release assets use exact isolated hosts. Authorized native Player sessions receive normalized immutable webapp packages through the manifest-and-release-bound protected route.

Content follows current screen authority. Release, media, package, and K/V access derives from current screen-manifest grants. Native package authority binds the current screen, manifest revision, release identity, package hash, size, type, and device session; storage remains private and delivery remains server-mediated.

Complete endpoint inventory

386 operations generated from api/openapi.yaml. Filter by path, action, or authentication. Each endpoint lists its inputs; expand it for a request template and response codes. Templates need your own values and a schema-valid body.

Service metadata and capabilities

GET/.health¶

Get Health

Authentication: none
Request body: none
Operation ID: getHealth

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET 'https://api.screenrig.ai/.health'

Responses

Status	Meaning	Body and headers
200	Alive	HealthResponse (application/json)

GET/.ready¶

Get Readiness

Serving readiness. A draining host answers 421 server_draining with Retry-After: 1. A required dependency failure answers 500 not_ready with Retry-After. A live database schema that does not satisfy this release (a desired index missing or different for more than two minutes) answers 500 schema_incompatible without Retry-After: it does not clear by waiting.

Authentication: none
Request body: none
Operation ID: getReadiness

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET 'https://api.screenrig.ai/.ready'

Responses

Status	Meaning	Body and headers
200	Ready	ReadyResponse (application/json)
421	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
500	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

GET/.version¶

Get Version

Authentication: none
Request body: none
Operation ID: getVersion

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET 'https://api.screenrig.ai/.version'

Responses

Status	Meaning	Body and headers
200	Version	VersionResponse (application/json)

GET/api/capabilities¶

Get Capabilities

Authentication: none
Request body: none
Operation ID: getCapabilities

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET 'https://api.screenrig.ai/api/capabilities'

Responses

Status	Meaning	Body and headers
200	Capability and archive limits	Capabilities (application/json)

Projects, invitations, and sign-in

GET/api/project/deletion-preview¶

Preview Project Deletion Agent

Returns current confirmation details, deletion blockers and archived devices that will be disconnected.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: previewProjectDeletionAgent

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
project_id	query	optional	Expected project ID; a changed selection is refused.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/project/deletion-preview'

Responses

Status	Meaning	Body and headers
200	Project lifecycle result	ProjectDeletionPreview (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PUT/api/project/owner¶

Transfer Project Owner Agent

The owner transfers ownership to a verified existing project member; this grants no new membership.

Authentication: projectBearer OR dashboardSession
Request body: ProjectOwnerTransfer
Operation ID: transferProjectOwnerAgent

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request body fields

Field	Description
project_id (optional, string)	Expected project ID. The server refuses the action if the current credential or cookie session targets another project; browser clients send the page's project ID. minLength: 1 maxLength: 200
user_id (required, string)	minLength: 1 maxLength: 200

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/project/owner'

Responses

Status	Meaning	Body and headers
200	Project lifecycle result	ProjectContext (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/project/move¶

Move Project Agent

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

Authentication: projectBearer OR dashboardSession
Request body: ProjectMove
Operation ID: moveProjectAgent

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request body fields

Field	Description
project_id (optional, string)	Expected project ID. The server refuses the action if the current credential or cookie session targets another project; browser clients send the page's project ID. minLength: 1 maxLength: 200
organization_id (required, string)	minLength: 1 maxLength: 200

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/project/move'

Responses

Status	Meaning	Body and headers
200	Project lifecycle result	ProjectContext (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/project/moves¶

Allowed Project Moves Agent

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

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: allowedProjectMovesAgent

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
project_id	query	optional	Expected project ID; a changed selection is refused.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/project/moves'

Responses

Status	Meaning	Body and headers
200	Project lifecycle result	ProjectMoveDestinations (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/projects¶

List Agent Projects

Lists only the identity’s active project memberships, with organization and owner context. Under an agent access JWT, only those its grant was approved for.

Authentication: agentIdentityBearer OR dashboardSession
Request body: none
Operation ID: listAgentProjects

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/projects'

Responses

Status	Meaning	Body and headers
200	Project lifecycle result	ProjectContextList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/projects¶

Create Agent Project

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. Projects inside an organization are not limited. 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.

Authentication: agentIdentityBearer OR dashboardSession
Request body: ProjectCreate
Operation ID: createAgentProject

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
Idempotency-Key	header	required

Request body fields

Field	Description
name (required, ProjectName)	Trimmed printable project name. Rejects controls, URL-looking text, @, www., and ://. minLength: 1 maxLength: 60
organization_id (optional, string)	minLength: 1 maxLength: 200
organization_name (optional, ProjectName)	Trimmed printable project name. Rejects controls, URL-looking text, @, www., and ://. minLength: 1 maxLength: 60

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/projects'

Responses

Status	Meaning	Body and headers
201	Project lifecycle result	CreatedProject (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/invitations¶

List Invitations

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.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listInvitations

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
kind	query	optional
status	query	optional
cursor	query	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/invitations'

Responses

Status	Meaning	Body and headers
200	Lists invitation lifecycle records for the current project, excluding sign-in resets.	InvitationList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/invitations¶

Create Invitations

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.

Authentication: projectBearer OR dashboardSession
Request body: InvitationCreate
Operation ID: createInvitations

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
Idempotency-Key	header	required

Request body fields

Field	Description
kind (required, string)	Allowed: "project_member", "ad_buyer"
delivery (optional, string)	Allowed: "email", "link" default: "email"
emails (optional, array)
advertising (optional, InvitationAdvertising)	Seller-owned scope: at least one screen or slot. Screens only, slots only, or both are accepted.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/invitations'

Responses

Status	Meaning	Body and headers
201	Creates member or ad-buyer invitations.	InvitationCreated (application/json); headers: RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit

POST/api/invitations/{id}/revoke¶

Revoke Invitation

Revokes an outstanding invitation. An accepted invitation returns invitation_consumed.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: revokeInvitation

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/invitations/RESOURCE_ID/revoke'

Responses

Status	Meaning	Body and headers
204	Revokes an outstanding invitation.	no body
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/sign-in-resets¶

Request Sign In Reset

Accepts a sign-in reset request without revealing whether a person holds the address. A live reset is superseded and expires after one hour. 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 zero members and a catalog plan gets its enrollment invitation back, even when it expired.

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.

Authentication: none
Request body: SignInResetRequest
Operation ID: requestSignInReset

Parameters

Name	Send in	Required?	Description
Idempotency-Key	header	required

Request body fields

Field	Description
email (required, string)	minLength: 3 maxLength: 254 format: "email"

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/sign-in-resets'

Responses

Status	Meaning	Body and headers
202	Accepts a sign-in reset request without revealing whether a person holds the address.	SignInResetAccepted (application/json); headers: RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit

POST/api/enrollments¶

Enroll CLI

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.

Authentication: none
Request body: CLIEnrollmentRequest
Operation ID: enrollCLI

Parameters

Name	Send in	Required?	Description
Idempotency-Key	header	required

Request body fields

Field	Description
credential_format (optional, string)	Must be oauth, which answers the agent JWT pair (CLIEnrollmentOAuth). legacy, or omitting it, answers 410 client_update_required, because the legacy permanent bearers are retired. A server that is not issuing agent JWTs answers not_ready. Allowed: "oauth", "legacy"
intent (optional, string)	Optional enrollment purpose. Omit or signage keeps screens=true, advertiser=false. advertising sets advertiser=true, screens=false, and never changes the billing-plan assignment. Allowed: "signage", "advertising"
client_id (required, string)	Stable anonymous installation identity generated from 32 CSPRNG bytes and persisted before the first request. It is rate-limit material, not a project credential. pattern: "^cli_[A-Za-z0-9_-]{43}$"
email (optional, string)	Unverified project contact address. Exactly one of email or agentid_claim is required. Enrollment always creates a new project and queues its invitation; an address alone grants no authority. minLength: 3 maxLength: 254 format: "email"
agentid_claim (optional, string)	Single-use AgentID claim code from the AgentID sign-in page. Exactly one of email or agentid_claim is required. The verified AgentID owner address becomes the project contact and invitation recipient. pattern: "^agid_[A-Za-z0-9_-]{43}$"
beta_key (optional, string)	Required when the server has a configured enrollment beta key. Omit when the server does not gate enrollment.
name (optional, string)	default: "Agent" minLength: 1 maxLength: 80
agent_type (optional, string)	default: "cli" pattern: "^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$"
platform (optional, string)	maxLength: 80
version (optional, string)	maxLength: 40
project_name (optional, ProjectName)	Trimmed printable project name. Rejects controls, URL-looking text, @, www., and ://. minLength: 1 maxLength: 60
organization (optional, ProjectName)	Trimmed printable project name. Rejects controls, URL-looking text, @, www., and ://. minLength: 1 maxLength: 60

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/enrollments'

Responses

Status	Meaning	Body and headers
201	New project and permanent bearer credential. The project carries the unverified contact address in its trimmed supplied form. Persist and verify the token before reporting enrollment success. The credential has no scheduled expiry but its encrypted exact-retry delivery envelope exists only until issuance_expires_at.	CLIEnrollmentOAuth (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
410	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/agentid/start¶

Start Agent IDSign In

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.

Authentication: none
Request body: none
Operation ID: startAgentIDSignIn

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET 'https://api.screenrig.ai/agentid/start'

Responses

Status	Meaning	Body and headers
302	Redirect to the AgentID authorization endpoint.	no body
503	AgentID sign-in is unavailable.	string (text/html)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/agentid/callback¶

Complete Agent IDSign In

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.

Authentication: none
Request body: none
Operation ID: completeAgentIDSignIn

Parameters

Name	Send in	Required?
code	query	optional
state	query	optional
iss	query	optional
error	query	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET 'https://api.screenrig.ai/agentid/callback'

Responses

Status	Meaning	Body and headers
200	Single-use AgentID claim-code page with plugin install steps.	string (text/html)
409	The AgentID subject is already enrolled.	string (text/html)
503	AgentID sign-in is unavailable.	string (text/html)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/project¶

Get Project

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.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getProject

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/project'

Responses

Status	Meaning	Body and headers
200	Project	Project (application/json); headers: ScreenRig-Credits-Remaining, ScreenRig-Credits-Reset, ScreenRig-Credits-Included, ScreenRig-Credits-Low
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PATCH/api/project¶

Update Project

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

Authentication: projectBearer OR dashboardSession
Request body: ProjectPatch
Operation ID: updateProject

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request body fields

Field	Description
project_id (optional, string)	Expected project ID. The server refuses the action if the current credential or cookie session targets another project; browser clients send the page's project ID. minLength: 1 maxLength: 200
name (required, ProjectName)	Trimmed printable project name. Rejects controls, URL-looking text, @, www., and ://. minLength: 1 maxLength: 60

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/project'

Responses

Status	Meaning	Body and headers
200	Renames the current project.	Project (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/project¶

Delete Project Agent

Requires the target membership project capability, 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.

Authentication: projectBearer OR dashboardSession
Request body: ProjectDeleteConfirmation
Operation ID: deleteProjectAgent

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request body fields

Field	Description
project_id (optional, string)	Expected project ID. The server refuses the action if the current credential or cookie session targets another project; browser clients send the page's project ID. minLength: 1 maxLength: 200
empty_only (optional, boolean)	Require an empty Screens project in the deletion transaction, including content, other agents or members, work and correspondence. The CLI additionally requires its saved enrollment provenance before using this cleanup guard. Omission keeps explicit member deletion.
name (required, ProjectName)	Trimmed printable project name. Rejects controls, URL-looking text, @, www., and ://. minLength: 1 maxLength: 60
revision (required, integer)	minimum: 1

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/project'

Responses

Status	Meaning	Body and headers
200	Project lifecycle result	DeletedProject (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/project/capabilities¶

Get Project Capabilities

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

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getProjectCapabilities

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/project/capabilities'

Responses

Status	Meaning	Body and headers
200	Project capabilities.	ProjectCapabilities (application/json); headers: Cache-Control
403	forbidden - the project plan is not in the catalog.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/organizations/{org_id}/billing/balance¶

Get Organization Billing Balance

The organization wallet. Requires a designated organization admin or staff session. Does not expose a reseller wallet or grant project membership.

Authentication: dashboardSession
Request body: none
Operation ID: getOrganizationBillingBalance

Parameters

Name	Send in	Required?	Description
org_id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/billing/balance'

Responses

Status	Meaning	Body and headers
200	Organization billing balance.	BillingBalance (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/organizations/{org_id}/billing/statement¶

Get Organization Billing Statement

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.

Authentication: dashboardSession
Request body: none
Operation ID: getOrganizationBillingStatement

Parameters

Name	Send in	Required?
org_id	path	required
cursor	query	optional
limit	query	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/billing/statement'

Responses

Status	Meaning	Body and headers
200	Organization billing statement.	BillingStatement (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/organizations/{org_id}/billing/usage¶

Get Organization Billing Usage

The organization allowance pool and each project share for a UTC month. Covers usage paid by this organization; other payer costs are in the organization statement.

Authentication: dashboardSession
Request body: none
Operation ID: getOrganizationBillingUsage

Parameters

Name	Send in	Required?	Description
org_id	path	required
cursor	query	optional
limit	query	optional
period	query	optional	UTC month in YYYY-MM form; defaults to the current month.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/billing/usage'

Responses

Status	Meaning	Body and headers
200	Organization billing usage.	OrganizationBillingUsage (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/organizations¶

Agent Organizations List

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

Authentication: agentIdentityBearer OR dashboardSession
Request body: none
Operation ID: agentOrganizationsList

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/organizations'

Responses

Status	Meaning	Body and headers
200	Organization result.	OrganizationList (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PATCH/api/organizations/{org_id}¶

Agent Organizations Rename

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

Authentication: agentIdentityBearer OR dashboardSession
Request body: OrganizationRename
Operation ID: agentOrganizationsRename

Parameters

Name	Send in	Required?	Description
org_id	path	required

Request body fields

Field	Description
name (required, ProjectName)	Trimmed printable project name. Rejects controls, URL-looking text, @, www., and ://. minLength: 1 maxLength: 60

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PATCH --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/organizations/ORG_ID'

Responses

Status	Meaning	Body and headers
200	Organization result.	OrganizationView (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PUT/api/project/review-policy¶

Set Project Review Policy

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.

Authentication: dashboardSession
Request body: ReviewPolicyUpdate
Operation ID: setProjectReviewPolicy

Parameters

Name	Send in	Required?	Description
If-Match	header	required

Request body fields

Field	Description
agent_changes_require_review (required, boolean)
proof (optional, DashboardProof)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'If-Match: "REVISION"' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/project/review-policy'

Responses

Status	Meaning	Body and headers
200	The policy now in force.	ReviewPolicy (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Credit balances and statements

GET/api/billing/balance¶

Get Billing Balance

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.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getBillingBalance

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/billing/balance'

Responses

Status	Meaning	Body and headers
200	Balance snapshot.	BillingBalance (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/billing/statement¶

Get Billing Statement

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.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getBillingStatement

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
cursor	query	optional
limit	query	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/billing/statement'

Responses

Status	Meaning	Body and headers
200	Statement page.	BillingStatement (application/json)
400	invalid_request - limit is out of range.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/billing/usage¶

Get Billing Usage

The calling project's use of its monthly allowance (10 GB bandwidth, 1 GB-month storage, and 10,000 API requests, billed project stream events and webhook delivery attempts) for one UTC 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.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getBillingUsage

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
period	query	optional	UTC month in YYYY-MM form; defaults to the current month.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/billing/usage'

Responses

Status	Meaning	Body and headers
200	Project allowance usage.	ProjectBillingUsage (application/json); headers: Cache-Control
400	invalid_request - period is not a UTC month in YYYY-MM form.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Agent installations and connections

POST/api/agent-identity/exchange¶

Exchange Agent Identity

Retired with the legacy agent credentials (project tokens and identity credentials). Always answers 401 credential_retired with next screenrig login; an installation signs in with the device grant (POST /oauth/device_authorization).

Authentication: projectBearer
Request body: none
Operation ID: exchangeAgentIdentity

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/agent-identity/exchange'

Responses

Status	Meaning	Body and headers
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/agent-identity/revoke¶

Revoke Agent Identity

Revokes the global identity, all its identity credentials and project tokens, and its pending connections. An exact replay with a revoked identity credential succeeds without another transition. Project ownership and content remain. No cookie, Origin, query or body is accepted. This route does not debit the API meter.

An agent access JWT carrying the identity scope, whose grant holds identity access (Read only, Propose or Manage, whatever the access level of the token's project), revokes the same and every OAuth grant of the identity; its tokens are refused within seconds. A retry with the same JWT after the revocation is a no-op success.

Authentication: agentIdentityBearer
Request body: none
Operation ID: revokeAgentIdentity

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST 'https://api.screenrig.ai/api/agent-identity/revoke'

Responses

Status	Meaning	Body and headers
204	Identity revoked.	no body; headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/agent-connections¶

Start Agent Connection

Retired with the legacy agent credentials. Always answers 410 client_update_required; an agent signs in with the device grant (POST /oauth/device_authorization, screenrig login).

Authentication: none OR agentIdentityBearer
Request body: none
Operation ID: startAgentConnection

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST 'https://api.screenrig.ai/api/agent-connections'

Responses

Status	Meaning	Body and headers
410	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/stream/agent-connections/{id}¶

Stream Agent Connection Events

Retired with the legacy agent connection. Always answers 410 client_update_required.

Authentication: agentConnectionAuthorization
Request body: none
Operation ID: streamAgentConnectionEvents

Parameters

Name	Send in	Required?	Description
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: ScreenRig-Agent-Connect [SCREENRIG_AGENT_CONNECTION_TOKEN]' 'https://api.screenrig.ai/stream/agent-connections/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
410	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/agent-connections/{id}/credential¶

Collect Agent Credential

Retired with the legacy agent connection. Always answers 410 client_update_required.

Authentication: agentConnectionAuthorization
Request body: none
Operation ID: collectAgentCredential

Parameters

Name	Send in	Required?	Description
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: ScreenRig-Agent-Connect [SCREENRIG_AGENT_CONNECTION_TOKEN]' 'https://api.screenrig.ai/api/agent-connections/RESOURCE_ID/credential'

Responses

Status	Meaning	Body and headers
410	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/agent-connections/{id}/cancel¶

Cancel Agent Connection

Retired with the legacy agent connection. Always answers 410 client_update_required.

Authentication: agentConnectionAuthorization
Request body: none
Operation ID: cancelAgentConnection

Parameters

Name	Send in	Required?	Description
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: ScreenRig-Agent-Connect [SCREENRIG_AGENT_CONNECTION_TOKEN]' 'https://api.screenrig.ai/api/agent-connections/RESOURCE_ID/cancel'

Responses

Status	Meaning	Body and headers
410	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/agents/self/activate¶

Activate Current Agent

Retired with the legacy project tokens, so no pending bearer is issued any more. Always answers 401 credential_retired with next screenrig login.

Authentication: pendingAgentBearer
Request body: none
Operation ID: activateCurrentAgent

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/agents/self/activate'

Responses

Status	Meaning	Body and headers
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/agents/self¶

Get Current Agent

Returns the agent installation linked to the calling project bearer plus connection_ready. A project is ready when at least one member has a passkey or password. Identity status is diagnostic and does not debit the API meter.

Authentication: projectBearer
Request body: none
Operation ID: getCurrentAgent

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/agents/self'

Responses

Status	Meaning	Body and headers
200	Current agent and project connection readiness.	AgentSelfStatus (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/agents/self/disconnect¶

Disconnect Current Agent

Revokes only the calling project membership and its project token, preserving the global identity, other memberships, project and content. Repeating with the same cryptographically valid revoked bearer is a no-op success. Disconnecting the last active agent returns agent_lockout_risk unless allow_last_agent is explicit. Does not debit the API meter.

An agent access JWT, Read only included, disconnects the agent from its token's project; the membership ends, the project's consent leaves the agent's grants and every access token of the agent is refused within seconds (refresh for the projects that remain). A retry with the same JWT after the disconnect is a no-op success.

Authentication: revocableAgentBearer
Request body: AgentDisconnectRequest
Operation ID: disconnectCurrentAgent

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request body fields

Field	Description
allow_last_agent (optional, boolean)	Explicitly accept loss of the last active agent bearer. A registered dashboard passkey remains independent administrative authority. default: false

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/agents/self/disconnect'

Responses

Status	Meaning	Body and headers
204	Agent disconnected.	no body; headers: Cache-Control
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

OAuth sign-in, tokens and revocation

POST/oauth/token¶

Oauth Token

OAuth 2.0 token endpoint (RFC 6749 §3.2) for agent JWTs. grant_type refresh_token rotates a refresh JWT (RFC 9700): every use returns a new pair; a request_id (16 to 200 characters) makes a retry within 60 seconds return the same response, and any other reuse of a superseded refresh token revokes the whole family (invalid_grant). grant_type urn:ietf:params:oauth:grant-type:token-exchange (RFC 8693) with subject_token_type urn:screenrig:token-type:identity-credential or urn:screenrig:token-type:project-token answers unsupported_token_type: legacy credentials are retired, and the installation signs in again with screenrig login. resource (RFC 8707) is https://api.<domain>/api or absent; project_id selects the project of a multi-project grant.

A connected app's grant has the single resource https://api.<domain>/mcp, which a refresh may omit.

Clients are public (client_id only), or a connected app whose metadata declares private_key_jwt authenticates with client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-bearer and a client_assertion (iss and sub its client_id, aud the issuer or this endpoint as one string, exp within 5 minutes of iat, a jti used once, kid naming one of its keys; EdDSA, ES256 or RS256). grant_type authorization_code redeems a connected app's code within 60 seconds with the exact redirect_uri and the PKCE code_verifier; resource must be absent or the one authorized; a second redemption revokes the grant the code created. grant_type client_credentials is a service client's: it authenticates with a client assertion (one of its registered keys) or its secret by HTTP Basic (client_secret_basic; a secret in the body is refused) and receives a 15-minute service token for its project, audience api or (resource https://api.<domain>/mcp) mcp, scope within its capabilities and access level, and no refresh token; 600 per client per hour.

Errors are RFC 6749 JSON {error, error_description} with Cache-Control no-store; while the server does not issue it answers temporarily_unavailable (503).

Rate limits answer 429 rate_limited with Retry-After: 1200 requests per client address per hour on this and the revocation endpoint, 60 refreshes per grant per hour, 30 exchanges per legacy credential per hour. grant_type urn:ietf:params:oauth:grant-type:device_code (RFC 8628 §3.4) polls a device sign-in: authorization_pending until a person approves it, slow_down when polled sooner than the interval (which then grows by 5 seconds), access_denied when denied, expired_token after 10 minutes, then the token response.

A new installation receives a token pair; a sign-in started with an existing installation's access token adds the approved project to that grant and receives an access token only, without rotating the refresh token. Polling the same device_code again returns the same response until the grant first rotates or 10 minutes pass, then invalid_grant.

POST only, form-encoded, no query string.

Authentication: none
Request body: object
Operation ID: oauthToken

Request body fields

Field	Description
grant_type (required, string)	Allowed: "authorization_code", "client_credentials", "refresh_token", "urn:ietf:params:oauth:grant-type:token-exchange", "urn:ietf:params:oauth:grant-type:device_code"
client_id (optional, string)
client_assertion_type (optional, string)	Allowed: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
client_assertion (optional, string)
code (optional, string)
redirect_uri (optional, string)
code_verifier (optional, string)	minLength: 43 maxLength: 128
refresh_token (optional, string)
device_code (optional, string)
request_id (optional, string)	minLength: 16 maxLength: 200
subject_token (optional, string)
subject_token_type (optional, string)	Allowed: "urn:screenrig:token-type:identity-credential", "urn:screenrig:token-type:project-token"
scope (optional, string)
resource (optional, string)	format: "uri"
project_id (optional, string)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Content-Type: application/x-www-form-urlencoded' --data-binary '@request.bin' 'https://api.screenrig.ai/oauth/token'

Responses

Status	Meaning	Body and headers
200	The token response (RFC 6749 §5.1).	OAuthTokenResponse (application/json)
default	An RFC 6749 §5.2 error.	OAuthError (application/json)

POST/oauth/device_authorization¶

Oauth Device Authorization

RFC 8628 §3.1 device authorization for `screenrig login`. scope is access:manage (the default), access:propose or access:read; project_id suggests the project the person approves; name, agent_type, platform and version describe the installation and are shown to the approver as reported by the device. Without Authorization it starts a new installation.

With Authorization: Bearer and an agent access token carrying identity scope it asks to add a project to that installation's grant, or to raise a Read only project to Manage.

The person enters user_code at verification_uri (or follows verification_uri_complete) and approves it in the dashboard; the device polls the token endpoint with the device_code every interval seconds.

Rate limits answer 429 rate_limited with Retry-After: 10 per client address per hour and 600 per hour fleet-wide, behind the endpoints' 1200 per address per hour. Errors are RFC 6749 JSON with Cache-Control no-store; while the server does not issue it answers temporarily_unavailable (503). POST only, form-encoded, no query string.

Authentication: none
Request body: object
Operation ID: oauthDeviceAuthorization

Request body fields

Field	Description
client_id (required, string)
scope (optional, string)	Allowed: "access:manage", "access:propose", "access:read"
project_id (optional, string)	maxLength: 200
name (optional, string)	maxLength: 80
agent_type (optional, string)	maxLength: 32
platform (optional, string)	maxLength: 80
version (optional, string)	maxLength: 40

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Content-Type: application/x-www-form-urlencoded' --data-binary '@request.bin' 'https://api.screenrig.ai/oauth/device_authorization'

Responses

Status	Meaning	Body and headers
200	The device authorization response (RFC 8628 §3.2).	object (application/json)
default	An RFC 6749 §5.2 error.	OAuthError (application/json)

GET/oauth/authorize¶

Oauth Authorize

OAuth 2.0 authorization endpoint for connected apps (MCP clients). client_id is a client ID metadata document URL (https, port 443, fetched with no redirects, 64 KiB and 5 seconds at most, public addresses only) or a registered client id.

The request is validated in order: the client, the exact redirect_uri (an http loopback redirect of 127.0.0.1, [::1] or localhost matches on any port), response_type code, code_challenge with code_challenge_method S256, resource (https://api.<domain>/mcp, or absent), then scope (access:read, the default, access:propose, access:manage and capability names).

An unknown client or redirect_uri answers an HTML error page and never redirects; any later error redirects to the redirect_uri with error, error_description, state and iss (RFC 9207).

Success answers 303 to the dashboard consent page, where a person chooses the project, the access level (Read only by default, Propose or Manage) and the capabilities; approval redirects with code, state and iss. 30 requests per client address per minute.

Authentication: none
Request body: none
Operation ID: oauthAuthorize

Parameters

Name	Send in	Required?
client_id	query	required
redirect_uri	query	required
response_type	query	required
code_challenge	query	required
code_challenge_method	query	required
state	query	optional
resource	query	optional
scope	query	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET 'https://api.screenrig.ai/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=RESPONSE_TYPE&code_challenge=CODE_CHALLENGE&code_challenge_method=CODE_CHALLENGE_METHOD'

Responses

Status	Meaning	Body and headers
303	To the consent page, or back to the client's redirect_uri with error, state and iss.	no body
400	An HTML error page for an unknown client or redirect_uri; never a redirect.	string (text/html)
429	Too many authorization requests from this address.	no body

POST/oauth/revoke¶

Oauth Revoke

RFC 7009 revocation. A refresh JWT, or an agent access JWT, issued to the client revokes its grant; the grant's access tokens are refused within seconds. An unknown, expired or foreign token also answers 200. POST only, form-encoded.

Authentication: none
Request body: object
Operation ID: oauthRevoke

Request body fields

Field	Description
client_id (optional, string)
client_assertion_type (optional, string)	Allowed: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
client_assertion (optional, string)
token (required, string)
token_type_hint (optional, string)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Content-Type: application/x-www-form-urlencoded' --data-binary '@request.bin' 'https://api.screenrig.ai/oauth/revoke'

Responses

Status	Meaning	Body and headers
200	Revoked, or nothing to revoke.	no body
default	An RFC 6749 §5.2 error.	OAuthError (application/json)

GET/.well-known/oauth-authorization-server¶

Oauth Authorization Server Metadata

RFC 8414 authorization server metadata for the agent authorization server.

Authentication: none
Request body: none
Operation ID: oauthAuthorizationServerMetadata

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET 'https://api.screenrig.ai/.well-known/oauth-authorization-server'

Responses

Status	Meaning	Body and headers
200	The metadata document.	object (application/json)

GET/.well-known/oauth-protected-resource/mcp¶

Oauth Protected Resource MCP

RFC 9728 protected resource metadata for /mcp, named by the resource_metadata of every /mcp 401.

Authentication: none
Request body: none
Operation ID: oauthProtectedResourceMCP

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET 'https://api.screenrig.ai/.well-known/oauth-protected-resource/mcp'

Responses

Status	Meaning	Body and headers
200	The metadata document.	object (application/json)

GET/.well-known/oauth-protected-resource/api¶

Oauth Protected Resource API

RFC 9728 protected resource metadata for /api.

Authentication: none
Request body: none
Operation ID: oauthProtectedResourceAPI

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET 'https://api.screenrig.ai/.well-known/oauth-protected-resource/api'

Responses

Status	Meaning	Body and headers
200	The metadata document.	object (application/json)

GET/api/oauth/authorizations/{id}¶

Get Dashboard OAuth Authorization

A pending connected-app authorization for the consent page: the client's name and domain as its metadata declares them (no logo is ever fetched), whether it is a registered client, the redirect host, and the access level and capabilities it asked for. Unknown, expired or settled authorizations are not_found.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardOAuthAuthorization

Parameters

Name	Send in	Required?	Description
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/oauth/authorizations/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	The authorization.	OAuthAuthorization (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/oauth/authorizations/{id}/approve¶

Approve Dashboard OAuth Authorization

Approves a connected app for one of the person's projects after a fresh proof (kind oauth_authorization_approval, subject the authorization id): it creates the app's agent identity (agent type mcp_client, the person responsible), its membership and its grant with the chosen access (read or manage; omitted keeps the requested level, which defaults to read) and capabilities (a subset of the requested), and answers the redirect_uri, carrying code, state and iss, that the page navigates to.

The code is valid for 60 seconds.

Authentication: dashboardSession
Request body: DashboardAgentAction
Operation ID: approveDashboardOAuthAuthorization

Parameters

Name	Send in	Required?	Description
id	path	required

Request body fields

Field	Description
project_id (required, string)	minLength: 1
proof (required, DashboardProof)
capabilities (optional, array)	Optional on agent connection and connected-app approval only. Omitted approves the full requested set; a non-empty subset of the connection's capabilities narrows the granted credential; anything else is invalid_request.
user_code (optional, string)	Required when approving a device sign-in (flow device): the code the person confirms matches the terminal. A mismatch is agent_connection_code_mismatch; the fifth expires the sign-in (agent_connection_expired). Ignored otherwise. maxLength: 32
access (optional, string)	The access level a device sign-in or a connected app is approved with (Read only, Propose or Manage); omitted keeps the level asked for. Ignored for other connections. A person who cannot approve reviews may not approve Manage (403 approver_required). Allowed: "read", "propose", "manage"

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/oauth/authorizations/RESOURCE_ID/approve'

Responses

Status	Meaning	Body and headers
200	The redirect back to the application.	OAuthAuthorizationRedirect (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/oauth/authorizations/{id}/deny¶

Deny Dashboard OAuth Authorization

Denies a connected app after a fresh proof (kind oauth_authorization_denial) and answers the redirect_uri, carrying error=access_denied, state and iss, that the page navigates to.

Authentication: dashboardSession
Request body: DashboardAgentAction
Operation ID: denyDashboardOAuthAuthorization

Parameters

Name	Send in	Required?	Description
id	path	required

Request body fields

Field	Description
project_id (required, string)	minLength: 1
proof (required, DashboardProof)
capabilities (optional, array)	Optional on agent connection and connected-app approval only. Omitted approves the full requested set; a non-empty subset of the connection's capabilities narrows the granted credential; anything else is invalid_request.
user_code (optional, string)	Required when approving a device sign-in (flow device): the code the person confirms matches the terminal. A mismatch is agent_connection_code_mismatch; the fifth expires the sign-in (agent_connection_expired). Ignored otherwise. maxLength: 32
access (optional, string)	The access level a device sign-in or a connected app is approved with (Read only, Propose or Manage); omitted keeps the level asked for. Ignored for other connections. A person who cannot approve reviews may not approve Manage (403 approver_required). Allowed: "read", "propose", "manage"

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/oauth/authorizations/RESOURCE_ID/deny'

Responses

Status	Meaning	Body and headers
200	The redirect back to the application.	OAuthAuthorizationRedirect (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Service clients

GET/api/service-clients¶

List Service Clients

The project's service clients (spec: a customer's server, script or CI job owned by the project), newest first, live and revoked, with their public keys, secret ids and usage; never a secret or its digest. Needs the project capability.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listServiceClients

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/service-clients'

Responses

Status	Meaning	Body and headers
200	The service client.	ServiceClientList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/service-clients¶

Create Service Client

Creates a service client owned by the project with a name, capabilities (omitted means all six; each must be one the manager holds, else 403), access (read, the default, or manage), and a public JWK key (OKP Ed25519, EC P-256 or RSA of at least 2048 bits) and/or secret true. The secret is returned once, here only. At most 50 live clients per project.

Agents need the project capability and Manage; a person uses the dashboard session with project_id and a fresh proof (kind service_client_change, subject the client id, or the project id when creating) in the body. A service token is refused 403.

Authentication: projectBearer OR dashboardSession
Request body: ServiceClientChange
Operation ID: createServiceClient

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request body fields

Field	Description
project_id (optional, string)	Dashboard session only.
proof (optional, DashboardProof)
name (optional, string)	minLength: 1 maxLength: 80
capabilities (optional, array)
access (optional, string)	Manage needs a person who can approve reviews (403 approver_required). Allowed: "read", "propose", "manage"
key (optional, object)	A public JWK: OKP Ed25519, EC P-256 or RSA of at least 2048 bits.
secret (optional, boolean)	Generate a secret (creation only).

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients'

Responses

Status	Meaning	Body and headers
201	The service client.	ServiceClientResult (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/service-clients/{id}¶

Get Service Client

One of the project's service clients. Needs the project capability.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getServiceClient

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/service-clients/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	The service client.	ServiceClient (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PATCH/api/service-clients/{id}¶

Update Service Client

Renames a service client or changes its capabilities (within the manager's) or access. Narrowing either ends the client's current tokens within seconds.

Authentication: projectBearer OR dashboardSession
Request body: ServiceClientChange
Operation ID: updateServiceClient

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request body fields

Field	Description
project_id (optional, string)	Dashboard session only.
proof (optional, DashboardProof)
name (optional, string)	minLength: 1 maxLength: 80
capabilities (optional, array)
access (optional, string)	Manage needs a person who can approve reviews (403 approver_required). Allowed: "read", "propose", "manage"
key (optional, object)	A public JWK: OKP Ed25519, EC P-256 or RSA of at least 2048 bits.
secret (optional, boolean)	Generate a secret (creation only).

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	The service client.	ServiceClientResult (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/service-clients/{id}/keys¶

Add Service Client Key

Registers a second public JWK (key in the body) for a zero-downtime rotation; a client holds at most two. Agents need the project capability and Manage; a person uses the dashboard session with project_id and a fresh proof (kind service_client_change, subject the client id, or the project id when creating) in the body. A service token is refused 403.

Authentication: projectBearer OR dashboardSession
Request body: ServiceClientChange
Operation ID: addServiceClientKey

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request body fields

Field	Description
project_id (optional, string)	Dashboard session only.
proof (optional, DashboardProof)
name (optional, string)	minLength: 1 maxLength: 80
capabilities (optional, array)
access (optional, string)	Manage needs a person who can approve reviews (403 approver_required). Allowed: "read", "propose", "manage"
key (optional, object)	A public JWK: OKP Ed25519, EC P-256 or RSA of at least 2048 bits.
secret (optional, boolean)	Generate a secret (creation only).

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients/RESOURCE_ID/keys'

Responses

Status	Meaning	Body and headers
200	The service client.	ServiceClientResult (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/service-clients/{id}/keys/{kid}/remove¶

Remove Service Client Key

Removes a key; the client's current tokens end within seconds. A client keeps at least one key or secret. Agents need the project capability and Manage; a person uses the dashboard session with project_id and a fresh proof (kind service_client_change, subject the client id, or the project id when creating) in the body. A service token is refused 403.

Authentication: projectBearer OR dashboardSession
Request body: ServiceClientChange
Operation ID: removeServiceClientKey

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
kid	path	required

Request body fields

Field	Description
project_id (optional, string)	Dashboard session only.
proof (optional, DashboardProof)
name (optional, string)	minLength: 1 maxLength: 80
capabilities (optional, array)
access (optional, string)	Manage needs a person who can approve reviews (403 approver_required). Allowed: "read", "propose", "manage"
key (optional, object)	A public JWK: OKP Ed25519, EC P-256 or RSA of at least 2048 bits.
secret (optional, boolean)	Generate a secret (creation only).

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients/RESOURCE_ID/keys/KID/remove'

Responses

Status	Meaning	Body and headers
200	The service client.	ServiceClientResult (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/service-clients/{id}/secrets¶

Add Service Client Secret

Generates a second secret, returned once, for a zero-downtime rotation; a client holds at most two. Agents need the project capability and Manage; a person uses the dashboard session with project_id and a fresh proof (kind service_client_change, subject the client id, or the project id when creating) in the body. A service token is refused 403.

Authentication: projectBearer OR dashboardSession
Request body: ServiceClientChange
Operation ID: addServiceClientSecret

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request body fields

Field	Description
project_id (optional, string)	Dashboard session only.
proof (optional, DashboardProof)
name (optional, string)	minLength: 1 maxLength: 80
capabilities (optional, array)
access (optional, string)	Manage needs a person who can approve reviews (403 approver_required). Allowed: "read", "propose", "manage"
key (optional, object)	A public JWK: OKP Ed25519, EC P-256 or RSA of at least 2048 bits.
secret (optional, boolean)	Generate a secret (creation only).

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients/RESOURCE_ID/secrets'

Responses

Status	Meaning	Body and headers
200	The service client.	ServiceClientResult (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/service-clients/{id}/secrets/{secret_id}/remove¶

Remove Service Client Secret

Removes a secret; the client's current tokens end within seconds. Agents need the project capability and Manage; a person uses the dashboard session with project_id and a fresh proof (kind service_client_change, subject the client id, or the project id when creating) in the body. A service token is refused 403.

Authentication: projectBearer OR dashboardSession
Request body: ServiceClientChange
Operation ID: removeServiceClientSecret

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
secret_id	path	required

Request body fields

Field	Description
project_id (optional, string)	Dashboard session only.
proof (optional, DashboardProof)
name (optional, string)	minLength: 1 maxLength: 80
capabilities (optional, array)
access (optional, string)	Manage needs a person who can approve reviews (403 approver_required). Allowed: "read", "propose", "manage"
key (optional, object)	A public JWK: OKP Ed25519, EC P-256 or RSA of at least 2048 bits.
secret (optional, boolean)	Generate a secret (creation only).

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients/RESOURCE_ID/secrets/SECRET_ID/remove'

Responses

Status	Meaning	Body and headers
200	The service client.	ServiceClientResult (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/service-clients/{id}/revoke¶

Revoke Service Client

Revokes a service client permanently: its keys and secret digests are deleted, the record stays for audit, and its tokens end within seconds (propagation applied or pending).

Authentication: projectBearer OR dashboardSession
Request body: ServiceClientChange
Operation ID: revokeServiceClient

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request body fields

Field	Description
project_id (optional, string)	Dashboard session only.
proof (optional, DashboardProof)
name (optional, string)	minLength: 1 maxLength: 80
capabilities (optional, array)
access (optional, string)	Manage needs a person who can approve reviews (403 approver_required). Allowed: "read", "propose", "manage"
key (optional, object)	A public JWK: OKP Ed25519, EC P-256 or RSA of at least 2048 bits.
secret (optional, boolean)	Generate a secret (creation only).

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients/RESOURCE_ID/revoke'

Responses

Status	Meaning	Body and headers
200	The service client.	ServiceClientResult (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Applications and operations

GET/api/applications¶

List Applications

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.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listApplications

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
after	query	optional	next_cursor of the previous page of the same list, with the same filters. Omitted starts at the newest row. A value that is not such a cursor is invalid_request.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/applications'

Responses

Status	Meaning	Body and headers
200	Applications	ApplicationList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/applications¶

Upload Application

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.

Authentication: projectBearer
Request body: string
Operation ID: uploadApplication

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
Idempotency-Key	header	required
ScreenRig-Archive-SHA256	header	required
ScreenRig-Expanded-Bytes	header	required
ScreenRig-File-Count	header	required
ScreenRig-SDK-Version	header	optional
ScreenRig-Application-Name	header	optional	ASCII application name; mutually exclusive with ScreenRig-Application-Name*. Leading and trailing whitespace is trimmed. Controls and duplicate header values are rejected. The decoded name is limited to 120 Unicode scalar values.
ScreenRig-Application-Name*	header	optional	Unicode application name encoded as RFC 8187 UTF-8'' followed by percent-encoded UTF-8 bytes (empty language, exact UTF-8 charset). Mutually exclusive with ScreenRig-Application-Name. Invalid escapes, invalid UTF-8, controls, and duplicate header values are rejected. Leading and trailing whitespace is trimmed; the decoded name is limited to 120 Unicode scalar values. Neither name header may rename a release update. This avoids raw Unicode in HTTP header values.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Idempotency-Key: REQUEST_ID' --header 'ScreenRig-Archive-SHA256: VALUE' --header 'ScreenRig-Expanded-Bytes: VALUE' --header 'ScreenRig-File-Count: VALUE' --header 'Content-Type: application/gzip' --data-binary '@request.bin' 'https://screenrig.ai/api/applications'

Responses

Status	Meaning	Body and headers
202	Upload accepted	OperationAccepted (application/json); headers: RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/applications/{id}/releases¶

Upload Application Release

Publishes an immutable new release of an owned application using the same bounded tar.gz upload pipeline. If-Match guards the application revision; acceptance increments it, and successful publication increments it again when latest_ready_release changes. Name and application identity are preserved. Existing playlist release pins are not changed.

An identical idempotent retry returns the original operation even after revision changes.

Authentication: projectBearer
Request body: string
Operation ID: uploadApplicationRelease

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	required
ScreenRig-Archive-SHA256	header	required
ScreenRig-Expanded-Bytes	header	required
ScreenRig-File-Count	header	required
ScreenRig-SDK-Version	header	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Idempotency-Key: REQUEST_ID' --header 'ScreenRig-Archive-SHA256: VALUE' --header 'ScreenRig-Expanded-Bytes: VALUE' --header 'ScreenRig-File-Count: VALUE' --header 'Content-Type: application/gzip' --data-binary '@request.bin' 'https://api.screenrig.ai/api/applications/RESOURCE_ID/releases'

Responses

Status	Meaning	Body and headers
202	Upload accepted	OperationAccepted (application/json); headers: RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/applications/{id}¶

Get Application

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getApplication

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/applications/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Application	Application (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PATCH/api/applications/{id}¶

Rename Application

Changes the display name of an application owned by the authenticated project. Names are trimmed, contain 1 to 120 Unicode characters with no controls, and may repeat within a project. Application identity, releases, K/V data, and playlist release pins are preserved.

A changed name advances the application revision and emits application.updated; the same name is a no-op. If-Match optionally guards the revision. An identical idempotent retry returns the original response after subsequent metadata changes.

Authentication: projectBearer
Request body: ApplicationRename
Operation ID: renameApplication

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
name (required, string)	Display name after trimming; controls and empty names are rejected. minLength: 1 maxLength: 120

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/applications/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Renamed application.	Application (application/json); headers: ETag
412	revision_conflict — If-Match is stale; the error's current_revision carries the current revision.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/applications/{id}¶

Delete Application

Tombstones one application owned by the authenticated project and all of its releases. The project bearer is authoritative; an unknown or other-project id is not_found. If-Match guards the application revision. A live manifest reference blocks deletion with application_in_use; there is no force-delete path.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: deleteApplication

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/applications/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
204	Application and releases tombstoned.	no body
409	application_in_use — a live manifest still references one of the application's releases.	Problem (application/problem+json)
412	revision_conflict — If-Match is stale; the error's current_revision carries the current revision.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/operations/{id}¶

Get Operation

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getOperation

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/operations/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Operation	Operation (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/operations/{id}/cancel¶

Cancel Operation

Authentication: projectBearer
Request body: none
Operation ID: cancelOperation

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Idempotency-Key	header	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Idempotency-Key: REQUEST_ID' 'https://api.screenrig.ai/api/operations/RESOURCE_ID/cancel'

Responses

Status	Meaning	Body and headers
200	Cancelled durable operation. A current worker fence can no longer finalize it.	Operation (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Media uploads

GET/api/media¶

List Media

Lists ready media newest first, at most 1000 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.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listMedia

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
tag	query	optional	Exact media tag. Untagged objects are omitted when this filter is present.
primitive	query	optional
after	query	optional	next_cursor of the previous page of the same list, with the same filters. Omitted starts at the newest row. A value that is not such a cursor is invalid_request.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/media'

Responses

Status	Meaning	Body and headers
200	Media	MediaList (application/json)

POST/api/media/generations¶

Create Media Generation

Generate one still image from a prompt, store it as ready private project media, and return a MediaGeneration object on the original POST. The handler waits for the vendor still and does not return a pollable Operation. The response is MediaGeneration: the ready Media object plus usage (quality, credits, usd).

It never includes image bytes, b64_json, object keys, signed URLs, vendor URLs, vendor cost, vendor tokens, or the deployment model name. The prompt is customer bytes and is not echoed.

Before the prompt reaches the image vendor the server appends fixed framing requirements to it: the artwork must fill the frame edge to edge, and no television, monitor, screen, display, bezel, frame, border, mounting, stand, wall, room, device mockup, drop shadow, or photograph of an installed sign may be depicted, and any wording in the caller's prompt describing where the sign will hang or what device will show it is treated as placement metadata rather than subject matter.

Decorative rules and borders inside the design itself remain available. The caller's prompt is never rewritten or stripped and is stored unchanged. Idempotency-Key replays the same MediaGeneration. Clients do not PUT or commit generated bytes.

The stored rendition is lossy WebP (quality 90) at the exact aspect size with a 1080 px short edge (16:9 is 1920x1080, 9:16 1080x1920, 1:1 1080x1080, 4:3 1440x1080, 3:4 1080x1440, 3:2 1620x1080, 2:3 1080x1620); the vendor canvas is centre-cropped and resampled to that size.

The filename is distinctive per generation, generated-16x9-1a2b3c4d.webp, with the suffix taken from the media id. Fetch the bytes with GET /api/media/{id}/content. Own-gen-then-upload remains valid.

Remaining that cannot cover twice the vendor cost of the still, rounded up to whole credits, after the intro floor (negative 1,000,000 credits until 2027-01-01, then zero) returns payment_required, except SCREENRIG__ENVIRONMENT=development.

Admission before the vendor call requires remaining above that floor by the per-quality minimum: 200 credits for low, 800 for medium, 2000 for high. Empty selected-vendor configuration returns not_ready. Project bearer only. One in-flight generation per project; further parallelism is rate_limited.

Authentication: projectBearer OR dashboardSession
Request body: MediaGenerationRequest
Operation ID: createMediaGeneration

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
Idempotency-Key	header	required

Request body fields

Field	Description
prompt (required, string)	minLength: 1 maxLength: 4000
aspect_ratio (optional, string)	Allowed: "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3" default: "16:9"
quality (optional, string)	Allowed: "low", "medium", "high" default: "medium"
tag (optional, string)	pattern: "^[A-Za-z0-9]{1,32}$"
references (optional, array)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/media/generations'

Responses

Status	Meaning	Body and headers
201	Ready still stored as private project media, with billed usage (quality, credits, usd). Fetch original bytes with GET /api/media/{id}/content. GET /api/media/{id} remains Media-only. Never image bytes, b64_json, object keys, signed URLs, vendor URLs, vendor cost, or the prompt.	MediaGeneration (application/json); headers: RateLimit-Policy, RateLimit, ETag
402	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
500	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/media-folders¶

List Media Folders

Lists every media folder in the project, at most 1000, ordered by name. Folders organize the media library, and a playlist selector by:folder plays the files directly inside one folder. A folder's parent_id is null at the library root. Build the tree from parent_id; a file's folder is Media.folder_id.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listMediaFolders

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/media-folders'

Responses

Status	Meaning	Body and headers
200	Media folders	MediaFolderList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/media-folders¶

Create Media Folder

Creates one media folder at the library 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 may repeat. A project holds at most 1000 folders (quota_exceeded) nested at most 10 deep (invalid_request). Emits media.folder_created.

Authentication: projectBearer OR dashboardSession
Request body: MediaFolderCreate
Operation ID: createMediaFolder

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
name (required, string)	Trimmed; 1 to 100 Unicode characters, no controls, not . or .. minLength: 1 maxLength: 100
parent_id (optional, inline)	The folder to create it in; null or absent for the library root.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/media-folders'

Responses

Status	Meaning	Body and headers
201	Created folder.	MediaFolder (application/json); headers: ETag
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/media-folders/{id}¶

Get Media Folder

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getMediaFolder

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/media-folders/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	One media folder.	MediaFolder (application/json); headers: ETag
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PATCH/api/media-folders/{id}¶

Update Media Folder

Renames a folder (name) or moves it with everything inside (parent_id, null for the library root). A folder cannot move into itself or a folder inside it, and the move must keep every folder within 10 levels (invalid_request). A change advances the folder revision and emits media.folder_updated; the same values are a no-op.

If-Match optionally guards the revision.

Authentication: projectBearer OR dashboardSession
Request body: MediaFolderPatch
Operation ID: updateMediaFolder

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
name (optional, string)	Trimmed; 1 to 100 Unicode characters, no controls, not . or .. minLength: 1 maxLength: 100
parent_id (optional, inline)	Move the folder into this one; null for the library root.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/media-folders/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Updated folder.	MediaFolder (application/json); headers: ETag
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/media-folders/{id}¶

Delete Media Folder

Deletes one folder. Nothing inside is deleted - its files and folders move up into the deleted folder's parent (the library root when it had none), each moved file and folder advancing its revision. A playlist selector by:folder that names the deleted folder then matches nothing; playing screens drop that primitive at their next selector resolve.

Emits media.folder_deleted. If-Match optionally guards the revision.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: deleteMediaFolder

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/media-folders/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
204	Deleted; its contents now sit in its parent.	no body
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/media/move¶

Move Media

Moves files (media_ids) and folders (folder_ids) into one folder (folder_id), or to the library 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 file and folder advances its revision. Moving files changes what the by:folder selectors of their old and new folders play, from each screen's next selector resolve; moving a folder changes no folder's own files. Emits media.moved.

A Propose credential's move makes each moved file pending and queues its media review, and approved playlists' selectors resolve it by the folder it was approved with until a person approves the change (docs/reviews.md).

Authentication: projectBearer OR dashboardSession
Request body: MediaMove
Operation ID: moveMedia

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
folder_id (required, inline)	Destination folder; null for the library root.
media_ids (optional, array)
folder_ids (optional, array)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/media/move'

Responses

Status	Meaning	Body and headers
200	How many files and folders moved.	MediaMoveResult (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/media/uploads¶

Create Media Upload

Authentication: projectBearer OR dashboardSession
Request body: MediaUploadDeclaration
Operation ID: createMediaUpload

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
Idempotency-Key	header	required

Request body fields

Field	Description
filename (required, string)	Name of the bytes being uploaded, as they will be sent. minLength: 1 maxLength: 255
source_filename (optional, string)	Caller's original file name before any client-side transcode. Bare file name only. Stored verbatim on the ready media as source_filename and used to derive filename. minLength: 1 maxLength: 255
content_type (required, string)	Allowed: "image/png", "image/jpeg", "image/webp", "image/gif", "video/mp4", "video/webm", "audio/mpeg"
bytes (required, integer)	minimum: 1 maximum: 1073741824
sha256 (required, string)	pattern: "^[a-f0-9]{64}$"
tag (optional, string)	pattern: "^[A-Za-z0-9]{1,32}$"

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/media/uploads'

Responses

Status	Meaning	Body and headers
201	Short-lived signed authorization for exactly one private object PUT. Send the returned method and every returned header verbatim.	MediaUploadSession (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/media/uploads/{id}/commit¶

Commit Media Upload

Authentication: projectBearer OR dashboardSession
Request body: MediaCommit
Operation ID: commitMediaUpload

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Idempotency-Key	header	required

Request body fields

Field	Description
content_type (required, string)	Allowed: "image/png", "image/jpeg", "image/webp", "image/gif", "video/mp4", "video/webm", "audio/mpeg"
bytes (required, integer)	minimum: 1 maximum: 1073741824
sha256 (required, string)	pattern: "^[a-f0-9]{64}$"

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/media/uploads/RESOURCE_ID/commit'

Responses

Status	Meaning	Body and headers
202	Exact declaration persisted for asynchronous verification and immutable private publication.	Operation (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/selectors/preview¶

Preview Selector

Read-only preview of current project-owned ready image or video matches. Returns filename ordering and normalized policy; random playback shuffles on each new pass on the Player. Does not advance cursors, mint content grants, or alter manifests. More than 1024 matches returns invalid_request.

Authentication: projectBearer
Request body: SelectorPreviewInput
Operation ID: previewSelector

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request body fields

Field	Description
primitive (required, string)	Allowed: "image", "video"
selector (required, inline)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/selectors/preview'

Responses

Status	Meaning	Body and headers
200	Current selector matches.	SelectorPreview (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/media/{id}¶

Get Media

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getMedia

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/media/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Ready private media metadata. Original bytes are available to the owning project through the project export route and to a screen only through an exact runtime manifest grant.	Media (application/json); headers: ETag
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PATCH/api/media/{id}¶

Patch Media

Sets or clears the media item's tag or tags. A Propose credential's change of the tag set makes the item pending and queues its media review; approved playlists' selectors resolve it by the tags it was approved with until a person approves the change (docs/reviews.md). A patch that keeps the same tag set applies and the item stays approved.

Authentication: projectBearer
Request body: MediaTagPatch
Operation ID: patchMedia

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/media/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Ready media with the updated tag. Runtime tag selectors observe the change at their next playlist-loop refresh.	Media (application/json); headers: ETag
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/media/{id}¶

Delete Media

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: deleteMedia

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/media/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
204	Tombstoned. Referenced desired or active grants cannot be deleted.	no body
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/media/{id}/content¶

Export Media Content

Exports the original immutable rendition owned by the authenticated project. The project bearer is charged the normal authenticated API request credit, and completed response bytes are recorded as project_media_export egress. The media identifier is never authority: another project's identifier returns not_found.

The API streams from private storage and never publishes an object key, storage URL, or signed GET. The attachment filename is the media identifier plus the canonical extension for the verified content type.

Remaining at or below the intro floor (negative 1,000,000 credits until 2027-01-01, then zero) returns payment_required before the media is read or any byte is transferred.

A dashboard session views the same bytes inline: it is not prepaid-gated, completed bytes are recorded as dashboard_media egress, and the response is private, no-cache so the browser keeps one copy and revalidates it with If-None-Match. A project bearer response stays private, no-store.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: exportMediaContent

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Range	header	optional	V1 accepts one byte range only.
If-None-Match	header	optional	Exact strong media SHA-256 ETag returned by this route.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/media/RESOURCE_ID/content'

Responses

Status	Meaning	Body and headers
200	Complete original rendition.	string (image/png), string (image/jpeg), string (image/webp), string (image/gif), string (video/mp4), string (video/webm), string (audio/mpeg); headers: Accept-Ranges, Content-Length, Content-Type, Content-Disposition, ETag, Cache-Control, X-Content-Type-Options
206	One standards-correct byte range.	string (image/png), string (image/jpeg), string (image/webp), string (image/gif), string (video/mp4), string (video/webm), string (audio/mpeg); headers: Accept-Ranges, Content-Range, Content-Length, Content-Type, Content-Disposition, ETag, Cache-Control, X-Content-Type-Options
304	The exact immutable media ETag matches If-None-Match. No body or egress increment is produced.	no body; headers: ETag, Cache-Control
402	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
416	Unsatisfiable or malformed range.	Problem (application/problem+json); headers: Accept-Ranges, Content-Range
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

HEAD/api/media/{id}/content¶

Head Media Content

Applies the same prepaid, project ownership, conditional, range, and private-storage rules as exportMediaContent without opening or transferring the stored rendition.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: headMediaContent

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Range	header	optional	V1 accepts one byte range only.
If-None-Match	header	optional	Exact strong media SHA-256 ETag returned by this route.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request HEAD --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/media/RESOURCE_ID/content'

Responses

Status	Meaning	Body and headers
200	Complete-rendition metadata with no body.	no body; headers: Accept-Ranges, Content-Length, Content-Type, Content-Disposition, ETag, Cache-Control, X-Content-Type-Options
206	Byte-range metadata with no body.	no body; headers: Accept-Ranges, Content-Range, Content-Length, Content-Type, Content-Disposition, ETag, Cache-Control, X-Content-Type-Options
304	The exact immutable media ETag matches If-None-Match. No body is produced.	no body; headers: ETag, Cache-Control
402	Prepaid remaining is below the floor. A HEAD response carries no problem body.	no body
416	Unsatisfiable or malformed range.	Problem (application/problem+json); headers: Accept-Ranges, Content-Range
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Playlists

GET/api/playlists¶

List Playlists V2

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.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listPlaylistsV2

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
after	query	optional	next_cursor of the previous page of the same list, with the same filters. Omitted starts at the newest row. A value that is not such a cursor is invalid_request.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/playlists'

Responses

Status	Meaning	Body and headers
200	Playlists with the adslot page union.	PlaylistV2List (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/playlists¶

Create Playlist V2

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.

Authentication: projectBearer
Request body: PlaylistWriteV2
Operation ID: createPlaylistV2

Parameters

Name

Send in

Required?

Description

ScreenRig-Project

header

optional

Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Screenrig-Review-Note

header

optional

Optional proposer note on a review-class write, sent as percent-encoded UTF-8 (what JavaScript's encodeURIComponent writes). The server percent-decodes it (an invalid escape is 400 invalid_request); the decoded note is plain text, at most 280 characters after trimming, no control characters (else 400 invalid_request).

Stored on the review when the write becomes one; ignored when it applies live.

Idempotency-Key

header

optional

Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
name (required, string)	minLength: 1 maxLength: 120
pages (required, array)	The pages of one playlist may resolve to at most 1024 media references in total. A by:ids selector counts its length; a by:all, by:tag or by:folder definition reserves 32 references independently of catalog size. The actual loop snapshot is bounded at 1024 media references in total. Above either budget is 422 invalid at path pages.
audio (optional, PlaylistAudioWrite)	Optional playlist soundtrack: ordered ready audio (MP3) media that plays continuously while pages change (docs/playlist-audio.md). Page changes never stop or restart it. PUT replaces the whole playlist, so omitting audio removes the soundtrack.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/playlists'

Responses

Status	Meaning	Body and headers
202	The write became a review under Propose access and waits for a person's approval (docs/reviews.md). A person approves, rejects or requests changes in the dashboard at review.url. An Idempotency-Key replay answers the same body.	ReviewPending (application/json)
201	Playlist with its adslot pages.	PlaylistV2 (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/playlists/{id}¶

Get Playlist V2

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getPlaylistV2

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/playlists/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Playlist with its adslot pages.	PlaylistV2 (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PUT/api/playlists/{id}¶

Update Playlist V2

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

Authentication: projectBearer
Request body: PlaylistWriteV2
Operation ID: updatePlaylistV2

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
Screenrig-Review-Note	header	optional	Optional proposer note on a review-class write, sent as percent-encoded UTF-8 (what JavaScript's encodeURIComponent writes). The server percent-decodes it (an invalid escape is 400 invalid_request); the decoded note is plain text, at most 280 characters after trimming, no control characters (else 400 invalid_request). Stored on the review when the write becomes one; ignored when it applies live.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
name (required, string)	minLength: 1 maxLength: 120
pages (required, array)	The pages of one playlist may resolve to at most 1024 media references in total. A by:ids selector counts its length; a by:all, by:tag or by:folder definition reserves 32 references independently of catalog size. The actual loop snapshot is bounded at 1024 media references in total. Above either budget is 422 invalid at path pages.
audio (optional, PlaylistAudioWrite)	Optional playlist soundtrack: ordered ready audio (MP3) media that plays continuously while pages change (docs/playlist-audio.md). Page changes never stop or restart it. PUT replaces the whole playlist, so omitting audio removes the soundtrack.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/playlists/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
202	The write became a review under Propose access and waits for a person's approval (docs/reviews.md). A person approves, rejects or requests changes in the dashboard at review.url. An Idempotency-Key replay answers the same body.	ReviewPending (application/json)
200	Updated playlist.	PlaylistV2 (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/playlists/{id}¶

Delete Playlist V2

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. The dashboard session may delete as well; it never creates or edits a playlist.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: deletePlaylistV2

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/playlists/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
204	Playlist tombstoned.	no body
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Screens

GET/api/screens¶

List Screens

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.

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.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listScreens

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
state	query	optional	Omit for pairing_pending and active. Pass archived to list archived screens only.
tag	query	optional	Exact screen tag. Untagged screens are omitted when this filter is present.
after	query	optional	next_cursor of the previous page of the same list, with the same filters. Omitted starts at the newest row. A value that is not such a cursor is invalid_request.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens'

Responses

Status	Meaning	Body and headers
200	Screens	ScreenList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/screens/pair¶

Pair Screen

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.

Authentication: projectBearer OR dashboardSession
Request body: PairScreen
Operation ID: pairScreen

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
Idempotency-Key	header	required

Request body fields

Field	Description
code (required, string)	pattern: "^[23456789ABCDEFGHJKMNPQRSTUVWXYZ]{6}$"
label (optional, string)	minLength: 1 maxLength: 120

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/pair'

Responses

Status	Meaning	Body and headers
201	Durable pairing_pending screen claim.	PairingClaim (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
413	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/screens/provision¶

Provision Screen

Optional browser-only new-screen provisioning. Always creates one new quota-counted pairing_pending screen; exact retries redeliver the same fragment token for ten minutes. Six-character pairing remains the default and only recovery flow.

Authentication: projectBearer
Request body: ProvisionScreen
Operation ID: provisionScreen

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
Idempotency-Key	header	required

Request body fields

Field	Description
label (optional, string)	minLength: 1 maxLength: 120

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/provision'

Responses

Status	Meaning	Body and headers
201	New browser provisioning link.	ScreenProvisioning (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
410	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
413	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/screens/actions¶

Apply Screen Actions

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 project budgets for reload, toast, takeover, playlist schedules, reboot, display and display schedules; project exhaustion pauses the action instead of refusing the fleet. Per-screen exhaustion fails that screen alone. Assign and tag changes have no message budget. 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.

Authentication: projectBearer
Request body: ScreenActionRequest
Operation ID: applyScreenActions

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
Screenrig-Review-Note	header	optional	Optional proposer note on a review-class write, sent as percent-encoded UTF-8 (what JavaScript's encodeURIComponent writes). The server percent-decodes it (an invalid escape is 400 invalid_request); the decoded note is plain text, at most 280 characters after trimming, no control characters (else 400 invalid_request). Stored on the review when the write becomes one; ignored when it applies live.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.
after	query	optional	next_cursor from the preceding result page. Reuse the original Idempotency-Key and request body.

Request body fields

Field	Description
selector (required, ScreenActionSelector)
action (required, ScreenAction)	One fleet action, discriminated by type. Each member carries only its own parameters; a member of another type is an unknown field and invalid_request.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/actions'

Responses

Status	Meaning	Body and headers
200	Per-screen results. Partial success is a normal answer.	ScreenActionResult (application/json); headers: Idempotency-Key, Cache-Control, RateLimit-Policy, RateLimit
202	More screens remain (continue with next_cursor and the same Idempotency-Key and body, honoring Retry-After), or, with status pending_review, the action became a review under Propose access (docs/reviews.md). Only assign, takeover, takeover_clear, set_playlist_schedule and clear_playlist_schedule become reviews; every other action is insufficient_access for Propose.	inline (application/json); headers: Idempotency-Key, Retry-After, Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
402	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
403	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/screens/{id}¶

Get Screen

Returns pairing_pending, active, and archived screens. Deleted screens are not found.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getScreen

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Screen	Screen (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PATCH/api/screens/{id}¶

Update Screen

Updates the screen's name, playlist_id, timezone or tags. Under Propose access a patch of playlist_id alone becomes a review (202 pending_review); any other field is insufficient_access. A playlist with no approved version is playlist_not_approved.

Authentication: projectBearer
Request body: ScreenPatch
Operation ID: updateScreen

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Screenrig-Review-Note	header	optional	Optional proposer note on a review-class write, sent as percent-encoded UTF-8 (what JavaScript's encodeURIComponent writes). The server percent-decodes it (an invalid escape is 400 invalid_request); the decoded note is plain text, at most 280 characters after trimming, no control characters (else 400 invalid_request). Stored on the review when the write becomes one; ignored when it applies live.
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
name (optional, string)	minLength: 1 maxLength: 120
playlist_id (optional, string)
timezone (optional, string)	IANA time zone identifier, for example America/Los_Angeles. It is the zone every page visibility rule on this screen is evaluated in. Changing it remints the manifest revision. A screen assigned a playlist that uses page visibility must have one. minLength: 1 maxLength: 64
tags (optional, ScreenTags)	Fleet selector tags, 0 to 16 unique exact tags, each matching the media tag grammar. On ScreenPatch the array replaces the whole set and an empty array clears it; a duplicate or malformed tag is invalid_request. Changing tags bumps the screen revision (If-Match guards it) and appends screen.updated with details.tags; it never changes the manifest revision. Tags are never on the runtime manifest and never authorization.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
202	The write became a review under Propose access and waits for a person's approval (docs/reviews.md). A person approves, rejects or requests changes in the dashboard at review.url. An Idempotency-Key replay answers the same body.	ReviewPending (application/json)
200	Screen	Screen (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/screens/{id}¶

Delete Screen

Soft-deletes an eligible screen and immediately revokes its cookie credentials and runtime grants. Ordinary reads then return not_found; the tombstoned row is retained for at least 90 days before cleanup. If-Match guards the revision and Idempotency-Key replays the result.

A native identity-bound screen returns screen_archive_required: use archive to retain that binding; an identity-bound screen that is already archived stays archived (the same problem, saying so). This route does not grant administrative break-glass permission to release native enrollment.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: deleteScreen

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
204	Screen soft-deleted; its tombstone is retained for at least 90 days.	no body
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	screen_archive_required for a native identity-bound screen.	Problem (application/problem+json)
412	revision_conflict — If-Match is stale; the error's current_revision carries the current revision.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/screens/{id}/public-id/rotate¶

Rotate Screen Public Id

Authentication: projectBearer
Request body: none
Operation ID: rotateScreenPublicId

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/public-id/rotate'

Responses

Status	Meaning	Body and headers
200	Public URL credential rotated; player public-key enrollment preserved. Every runtime session is invalidated by the new content_access_generation and the live desired and active grants are reissued at that generation for their unchanged manifest revision, so a paired player that re-mints its session keeps authorizing the content it is already showing.	Screen (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/screens/{id}/recovery/confirm¶

Confirm Screen Recovery

Confirms a pending screen recovery. A native pairing start that presented a host duid or serial matching exactly one screen in exactly one project, under a different bound public key, records an offer on that screen (Screen.recovery_pending, project event screen.recovery_offered).

The host object is a hint, never a credential: nothing is rebound until the owning project calls this route. A DUID is readable by any application on the panel, so an offer is a phishing surface.

It is mitigated by liveness (no offer while the bound key showed life in the last ten minutes), a limit of three offers per screen per rolling hour, and this same-project confirmation; recovery_pending.host and the event carry the offering device's platform, model, firmware, and manufacturer so the operator can compare them with the display in front of them before confirming.

Confirmation completes the pending native pairing onto the EXISTING screen: the pairing device receives pairing.claimed as usual and proves possession with pairing.complete, the new key becomes the screen identity, and the previous key retires with a fifteen-minute grace window in which its runtime sessions keep working and it may still mint, after which it is refused.

Playlists, label, timezone, schedules, and history are preserved. Same project only; another project's screen is not_found. If-Match is optional. Emits screen.recovered. recovery_not_offered when nothing is pending, recovery_expired when the pairing session lapsed, recovery_ambiguous when the identifier is attached in more than one place.

Problem responses never echo device identifiers.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: confirmScreenRecovery

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to create or overwrite a key; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/recovery/confirm'

Responses

Status	Meaning	Body and headers
200	Screen recovered onto the pairing device's key; the response carries the current ETag.	Screen (application/json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
410	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
412	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/screens/{id}/archive¶

Archive Screen

Hides the screen from the default list and clears the live glass to the "Screen archived" status. Does not unbind the player public key. Releases screen_count quota.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: archiveScreen

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/archive'

Responses

Status	Meaning	Body and headers
200	Screen archived.	Screen (application/json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
412	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/screens/{id}/unarchive¶

Unarchive Screen

Restores an archived screen to the default list and remints a normal manifest. Must pass screen admission. Does not change the bound public key.

The manifest is issued again, so the screen's playlist is checked as an assignment is; a playlist that references missing or unready content answers resource_conflict naming the playlist, and the screen stays archived until the playlist is fixed.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: unarchiveScreen

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/unarchive'

Responses

Status	Meaning	Body and headers
200	Screen unarchived.	Screen (application/json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
412	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
413	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/screens/{id}/reload¶

Reload Screen

Asks the Player of the named active or archived screen to reload (docs/player-compatibility.md §6.3). Appends the durable per-screen player.reload event with details.reason project, a new reload_id, spread_s 0, and expires_at ten minutes later. The runtime SSE stream relays it to every runtime session.

A Player ignores a reload within ten minutes of the last one it acted on. A web Player reloads at its next page boundary; a native Player remints, refetches its manifest, and checks for an update. The screen revision does not change.

If-Match and Idempotency-Key are optional, as on archive; an exact Idempotency-Key retry returns the original reload_id and expires_at for twenty-four hours. A pairing_pending screen has no Player yet and answers resource_conflict. Screen messages are exempt from the 1-credit API meter.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: reloadScreen

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/reload'

Responses

Status	Meaning	Body and headers
202	Accepted. The reload is durable until expires_at. The ETag is the unchanged screen revision.	ScreenReloadAccepted (application/json); headers: Cache-Control, ETag, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
412	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/screens/{id}/playlist-schedule¶

Get Screen Playlist Schedule

Returns the screen's server-evaluated playlist schedule: entries in priority order (empty when the screen has none), updated_at, and the effective_playlist they currently produce. The ETag is the screen revision. pairing_pending, active, and archived screens are readable; another project's screen is not_found.

Authentication: projectBearer
Request body: none
Operation ID: getScreenPlaylistSchedule

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/playlist-schedule'

Responses

Status	Meaning	Body and headers
200	Playlist schedule.	ScreenPlaylistScheduleView (application/json); headers: ETag
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PUT/api/screens/{id}/playlist-schedule¶

Set Screen Playlist Schedule

Replaces the screen's playlist schedule. The server evaluates it, never the Player: the first entry whose rule matches the screen's civil time (screenrig.schedule/v1 windows and from/until, in the screen timezone, including daylight-saving transitions and windows that cross midnight) is the effective playlist; when none matches, the assigned playlist_id is.

A takeover still wins over every entry. The screen must have a timezone and an assigned default playlist_id (invalid_request otherwise), so there is always something to fall back to.

Every referenced playlist is validated against the screen exactly as an assignment is (owned, ready references, page visibility needs a timezone), so a playlist the screen would refuse is refused here; the check writes the playlist document, so a concurrent playlist delete conflicts instead of racing it.

If a scheduled playlist later cannot be shown (for example its content no longer resolves), its entries are skipped at evaluation and screen.playlist_unavailable (warning, details playlist_id, entry_ids, code) is appended.

When the effective playlist changes the manifest is re-minted from it and the Player is signalled with screen.manifest_changed, as for an assignment, and screen.playlist_switched is appended. The screen revision is bumped (If-Match guards it) and screen.updated is appended with details.playlist_schedule_entries.

An archived screen answers screen_archived; its schedule, takeover, and default stay referenced (they block playlist delete) and are re-resolved when it is unarchived. Rate limits: screen-control-project 600, screen-control-screen 20, and screen-control-ip 60 per minute, shared with DELETE and the takeover routes.

Authentication: projectBearer
Request body: ScreenPlaylistScheduleWrite
Operation ID: setScreenPlaylistSchedule

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Screenrig-Review-Note	header	optional	Optional proposer note on a review-class write, sent as percent-encoded UTF-8 (what JavaScript's encodeURIComponent writes). The server percent-decodes it (an invalid escape is 400 invalid_request); the decoded note is plain text, at most 280 characters after trimming, no control characters (else 400 invalid_request). Stored on the review when the write becomes one; ignored when it applies live.
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
entries (required, array)	Priority order: the first matching entry wins. DELETE clears the schedule.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/playlist-schedule'

Responses

Status	Meaning	Body and headers
202	The write became a review under Propose access and waits for a person's approval (docs/reviews.md). An Idempotency-Key replay answers the same body.	ReviewPending (application/json); headers: RateLimit-Policy, RateLimit
200	Screen with the stored schedule and its effective_playlist. The ETag is the new revision.	Screen (application/json); headers: ETag, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
412	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/screens/{id}/playlist-schedule¶

Clear Screen Playlist Schedule

Removes the screen's playlist schedule; the takeover, else the assigned playlist, becomes effective, with the same manifest signalling as PUT. A screen without a schedule answers 200 unchanged (no revision bump, no event).

Authentication: projectBearer
Request body: none
Operation ID: clearScreenPlaylistSchedule

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Screenrig-Review-Note	header	optional	Optional proposer note on a review-class write, sent as percent-encoded UTF-8 (what JavaScript's encodeURIComponent writes). The server percent-decodes it (an invalid escape is 400 invalid_request); the decoded note is plain text, at most 280 characters after trimming, no control characters (else 400 invalid_request). Stored on the review when the write becomes one; ignored when it applies live.
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/playlist-schedule'

Responses

Status	Meaning	Body and headers
202	The write became a review under Propose access and waits for a person's approval (docs/reviews.md). An Idempotency-Key replay answers the same body.	ReviewPending (application/json); headers: RateLimit-Policy, RateLimit
200	Screen without a playlist schedule.	Screen (application/json); headers: ETag, RateLimit-Policy, RateLimit
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
412	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/screens/{id}/takeover¶

Set Screen Takeover

Takes over the screen with one playlist ahead of its playlist schedule and assigned playlist, until until (RFC 3339, strictly in the future and at most 7 days ahead) or, when until is null or omitted, until the takeover is cleared. reason is optional, at most 120 characters. The screen must have an assigned default playlist_id (invalid_request otherwise).

A takeover replaces an earlier one (screen.takeover_ended with reason replaced, or expired when the earlier one had already ended). The playlist is validated as an assignment. A takeover whose playlist later cannot be shown ends (screen.takeover_ended with reason playlist_deleted or playlist_unavailable).

Appends screen.takeover_started and, when the effective playlist changes, screen.playlist_switched plus the Player's screen.manifest_changed. When until passes, the boundary worker ends the takeover within 60 seconds (screen.takeover_ended with reason expired). The screen revision is bumped (If-Match guards it).

An archived screen answers screen_archived; unarchive re-resolves first, so a takeover that ended while archived ends then. The same screen-control rate limits as the schedule routes apply.

Authentication: projectBearer
Request body: ScreenTakeoverWrite
Operation ID: setScreenTakeover

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Screenrig-Review-Note	header	optional	Optional proposer note on a review-class write, sent as percent-encoded UTF-8 (what JavaScript's encodeURIComponent writes). The server percent-decodes it (an invalid escape is 400 invalid_request); the decoded note is plain text, at most 280 characters after trimming, no control characters (else 400 invalid_request). Stored on the review when the write becomes one; ignored when it applies live.
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
playlist_id (required, string)	minLength: 1
until (optional, inline)	Strictly in the future and at most 7 days ahead. null or omitted holds the takeover until it is cleared.
reason (optional, string)	Operator note carried on the takeover and its events. No control characters. maxLength: 120

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/takeover'

Responses

Status	Meaning	Body and headers
202	The write became a review under Propose access and waits for a person's approval (docs/reviews.md). An Idempotency-Key replay answers the same body.	ReviewPending (application/json); headers: RateLimit-Policy, RateLimit
200	Screen with the takeover and its effective_playlist. The ETag is the new revision.	Screen (application/json); headers: ETag, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
412	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/screens/{id}/takeover¶

Clear Screen Takeover

Ends the takeover (screen.takeover_ended with reason cleared); the schedule, else the assigned playlist, becomes effective with the same manifest signalling. A screen without a takeover answers 200 unchanged (no revision bump, no event).

Authentication: projectBearer
Request body: none
Operation ID: clearScreenTakeover

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Screenrig-Review-Note	header	optional	Optional proposer note on a review-class write, sent as percent-encoded UTF-8 (what JavaScript's encodeURIComponent writes). The server percent-decodes it (an invalid escape is 400 invalid_request); the decoded note is plain text, at most 280 characters after trimming, no control characters (else 400 invalid_request). Stored on the review when the write becomes one; ignored when it applies live.
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/takeover'

Responses

Status	Meaning	Body and headers
202	The write became a review under Propose access and waits for a person's approval (docs/reviews.md). An Idempotency-Key replay answers the same body.	ReviewPending (application/json); headers: RateLimit-Policy, RateLimit
200	Screen without a takeover.	Screen (application/json); headers: ETag, RateLimit-Policy, RateLimit
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
412	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/screens/{id}/reboot¶

Reboot Screen

Asks the screen's Player to reboot the device (docs/player-compatibility.md §6.5). Appends the per-screen runtime command player.reboot (details reboot_id, reason project, at, expires_at ten minutes later; never delivered after expires_at) and the project-only screen.reboot_requested.

The screen must be active; an archived screen answers screen_archived and a pairing_pending one resource_conflict. The screen's host hint must declare the reboot capability, else 409 reboot_unsupported and nothing is sent. The screen revision does not change.

If-Match and Idempotency-Key are optional; an exact retry returns the same reboot_id for twenty-four hours. At most 2 per screen per 10 minutes; a refused request (reboot_unsupported, not_found, a conflict), a failed one, and an exact Idempotency-Key replay spend nothing.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: rebootScreen

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/reboot'

Responses

Status	Meaning	Body and headers
202	Accepted. The reboot is actionable until expires_at. The ETag is the unchanged screen revision.	ScreenRebootAccepted (application/json); headers: Cache-Control, ETag, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
412	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/screens/{id}/display¶

Set Screen Display

Turns the display on or off now: a manual override of the display schedule (docs/player-compatibility.md §6.5). power is on or off. until (RFC 3339, strictly future, at most 7 days ahead) ends it; without until it ends at the display schedule's next boundary when a schedule is enabled, else it holds until replaced.

Stores the override (Screen.display.override), re-mints the manifest (its display member carries the override so an offline Player keeps it), appends the runtime command player.display (details override_id, power, until, at, expires_at) and the project-only screen.display_changed, and bumps the screen revision (If-Match guards it). The screen must be active.

What the Player achieved is reported back in its health display.power (Screen.display.reported).

Without until and without a schedule boundary inside the next eight days (no enabled schedule, or none that changes), the override holds until DELETE /api/screens/{id}/display or a replacement; a later display-schedule PUT or DELETE, or a timezone change, re-bounds an until-less override to the new next boundary.

A refused or failed request, and an exact Idempotency-Key replay, spend no budget.

Authentication: projectBearer OR dashboardSession
Request body: ScreenDisplayWrite
Operation ID: setScreenDisplay

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
power (required, string)	Allowed: true, false
until (optional, inline)	Strictly future, at most 7 days ahead. Omitted or null: until the display schedule's next boundary, else until replaced.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID/display'

Responses

Status	Meaning	Body and headers
200	Screen with its display state.	Screen (application/json); headers: ETag, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
412	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/screens/{id}/display¶

Clear Screen Display

Ends the manual display override so the display schedule (else on) applies again. Re-mints the manifest (its display member drops the override; the Player follows screen.manifest_changed), appends screen.display_changed with change override_cleared, and bumps the revision. A screen without an active override answers 200 unchanged.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: clearScreenDisplay

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/display'

Responses

Status	Meaning	Body and headers
200	Screen with its display state.	Screen (application/json); headers: ETag, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
412	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/screens/{id}/display-schedule¶

Get Screen Display Schedule

Returns display_schedule (null when none) and the screen's display state. The ETag is the screen revision.

Authentication: projectBearer
Request body: none
Operation ID: getScreenDisplaySchedule

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/display-schedule'

Responses

Status	Meaning	Body and headers
200	Display schedule.	ScreenDisplayScheduleView (application/json); headers: ETag
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PUT/api/screens/{id}/display-schedule¶

Set Screen Display Schedule

Replaces the display schedule: enabled and 1 to 16 screenrig.schedule/v1 windows (days, start/end HH:MM, end <= start crosses midnight owned by the start day, whole day without edges) when the display is ON; outside every window the Player puts the display to standby.

Evaluated on the device in the screen timezone (required, invalid_request otherwise), so it keeps working offline: the manifest's display member carries it. enabled false keeps the windows and leaves the display on. Re-mints the manifest, appends screen.display_changed, bumps the revision (If-Match guards it). The screen must be pairing_pending or active.

A screen with no manifest yet (never minted, or no playlist) stores the schedule and its first manifest carries it; a screen without a playlist applies it once a playlist is assigned. An until-less override is re-bounded to the new schedule's next boundary.

Authentication: projectBearer
Request body: ScreenDisplayScheduleWrite
Operation ID: setScreenDisplaySchedule

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
enabled (required, boolean)
windows (required, array)	ON windows.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/display-schedule'

Responses

Status	Meaning	Body and headers
200	Screen with its display state.	Screen (application/json); headers: ETag, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
412	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/screens/{id}/display-schedule¶

Clear Screen Display Schedule

Removes the display schedule (the display stays on unless overridden). Clearing none answers 200 unchanged.

Authentication: projectBearer
Request body: none
Operation ID: clearScreenDisplaySchedule

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/display-schedule'

Responses

Status	Meaning	Body and headers
200	Screen with its display state.	Screen (application/json); headers: ETag, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
412	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/screens/{id}/toast¶

Post Screen Toast

Posts one transient stage-chrome toast to the named screen. A toast is not a primitive: it does not occupy a canvas slot, has no layer, and never participates in readiness or crossfade. The durable event type is screen.toast on the existing runtime SSE stream. Runtime scan never delivers a toast after expires_at, so a persisted cursor cannot replay it later.

Level colours are player chrome and are not API fields. Text is 1 to 120 characters, line feed is the only accepted line break, and at most three lines are accepted. Recognizable ScreenRig credential material and other control characters are rejected. duration_ms defaults to 10000 and must be between 2000 and 60000 inclusive.

An exact Idempotency-Key retry returns the original expires_at for twenty-four hours. Latest-wins: there is no queue and no cancel verb. Screen messages are exempt from the 1-credit API meter.

Authentication: projectBearer
Request body: ScreenToastWrite
Operation ID: postScreenToast

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Idempotency-Key	header	required

Request body fields

Field	Description
level (required, string)	Closed severity token. Player chrome chooses the fill; the API never carries a colour. Allowed: "error", "alert", "info"
text (required, string)	1 to 120 characters. Line feed is the only accepted line break. At most three lines. Other control characters and recognizable ScreenRig credential material are rejected. minLength: 1 maxLength: 120
duration_ms (optional, integer)	Visible duration in milliseconds. Omitted values default to 10000. default: 10000 minimum: 2000 maximum: 60000

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/toast'

Responses

Status	Meaning	Body and headers
202	Accepted. The toast is durable until expires_at. An exact idempotent retry returns this same expiry.	ScreenToastAccepted (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/screens/{id}/storage-forecast¶

Forecast Screen Storage

Pre-assignment fit dry run: answers whether one playlist would fit the named screen before it is assigned, with the same target selection as Screen.storage_forecast (the screen's last reported capacity, plan A.3 only, no transition prediction, nothing treated as local).

It writes nothing: no assignment, no screen revision, no event, and the screen's storage_forecast read model is untouched. The project bearer is authoritative; a screen or playlist of another project is not_found. fit is unknown when the screen has no storage report, or when the playlist's content references are not ready, and both byte counts are null then.

An optional playlist_revision refuses a playlist that changed since the caller read it with revision_conflict. A report older than 24 hours is stale but still forecast from, exactly like Screen.storage_forecast.

Authentication: projectBearer
Request body: ScreenStorageForecastRequest
Operation ID: forecastScreenStorage

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request body fields

Field	Description
playlist_id (required, string)	minLength: 1
playlist_revision (optional, integer)	Optional expected playlist revision. A different stored revision is revision_conflict and no forecast is returned. minimum: 1

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/storage-forecast'

Responses

Status	Meaning	Body and headers
200	Dry-run forecast. fit unknown means there is nothing to forecast from; the byte counts and received_at are null.	ScreenStorageForecastDryRun (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
412	revision_conflict — playlist_revision is not the playlist's current revision; no forecast is returned.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/screens/{id}/screenshot¶

Get Screen Screenshot

Returns the current ready still WebP for the named screen. Optional capture_id must match that ready slot. A named capture_id that expired with no upload is screenshot_unavailable. A named capture_id replaced by a later request is resource_conflict. Image bytes are never a signed URL or object key. Range is not accepted.

Screen messages are exempt from the 1-credit API meter. The ETag is the strong SHA-256 of the stored WebP. A dashboard session response is private, no-cache, and a dashboard If-None-Match that matches the current image, checked after the screen and capture resolve in the session's project, returns 304 without opening the stored bytes.

A project bearer response stays private, no-store.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getScreenScreenshot

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
capture_id	query	optional
If-None-Match	header	optional	Strong ETag of a screenshot this route returned. Honored for a dashboard session.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/screenshot'

Responses

Status	Meaning	Body and headers
200	Current ready still WebP.	string (image/webp); headers: Content-Type, Content-Length, ETag, X-ScreenRig-Capture-ID, X-ScreenRig-Captured-At, Cache-Control, Content-Disposition
304	Dashboard session only. The current image's ETag matches If-None-Match. No body is produced and object storage is not read. The capture headers name the current capture, which can differ from the stored response's when a later capture encoded to the same bytes.	no body; headers: ETag, Cache-Control, X-ScreenRig-Capture-ID, X-ScreenRig-Captured-At
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/screens/{id}/screenshot¶

Request Screen Screenshot

Requests one still screenshot of the named active screen. Latest-wins: a new request replaces any in-flight capture_id and does not 409. The current ready slot is kept until a later upload succeeds. capture_id is an optional environment prefix, then shot_ and a random suffix. expires_at is thirty seconds after accept.

The durable event type is screen.screenshot_requested on the existing runtime SSE stream; runtime scan never delivers it after expires_at. Event details name capture_id, expires_at, max_width_divisor 2, max_height_divisor 2, format image/webp, quality 80, and max_bytes 2097152. Image bytes never appear on SSE.

Prepaid remaining credit is not a gate, and this screen-message path is exempt from the 1-credit API meter. An exact Idempotency-Key retry returns the original capture_id and expires_at for twenty-four hours.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: requestScreenScreenshot

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Idempotency-Key	header	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Idempotency-Key: REQUEST_ID' 'https://screenrig.ai/api/screens/RESOURCE_ID/screenshot'

Responses

Status	Meaning	Body and headers
202	Accepted. The request is durable until expires_at. An exact idempotent retry returns this same capture_id and expiry.	ScreenScreenshotAccepted (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/screens/{id}/screenshot/status¶

Get Screen Screenshot Status

Returns the screenshot state machine for the named screen when it exists for this project. idle has no request and no ready slot. pending is the current capture_id before expires_at with no upload. ready means the last successful upload matches the current capture_id. timed_out means the current id reached expires_at with no upload.

Timeout is lazy: the first status GET or next POST after expiry records it and appends screen.screenshot_failed once with reason expired. A timed-out request does not delete an older ready slot. Screen messages are exempt from the 1-credit API meter.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getScreenScreenshotStatus

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/screenshot/status'

Responses

Status	Meaning	Body and headers
200	Screenshot status for this project's screen.	ScreenScreenshotStatus (application/json); headers: Cache-Control
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/screens/{id}/health/history¶

Get Screen Health History

The health a screen reported over time. resolution=raw (default) returns each accepted report in time order, shaped like Screen.health without stale; resolution=hour returns one summary per UTC hour (reports, peak and average temperature, peak load and memory ratio, weakest Wi-Fi signal, whether the display was disconnected, peak crash and renderer-restart counts). from (inclusive) and to (exclusive) default to the last 24 hours; the range is at most 31 days for raw and 93 days for hour.

A page holds at most limit rows (default 100, at most 500) with next_cursor, null at the end. History is kept for the plan's event retention. Raw reports reach this view within seconds, hourly summaries within about 5 minutes. A screen of another project is not_found. Screen.health, the latest report, is unchanged.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getScreenHealthHistory

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
from	query	optional	Inclusive lower bound on the report time. Defaults to 24 hours before to.
to	query	optional	Exclusive upper bound on the report time. Defaults to now.
resolution	query	optional	raw returns each report; hour returns one summary per UTC hour.
limit	query	optional	Page size.
cursor	query	optional	next_cursor of the previous page, with the same filters. Opaque.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/health/history'

Responses

Status	Meaning	Body and headers
200	A page of reports or hourly summaries.	ScreenHealthHistory (application/json); headers: Cache-Control
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/screens/{id}/uptime¶

Get Screen Uptime

Daily availability of one screen over inclusive UTC days (day_to defaults to today and day_from to 29 days before it, at most 366 days). Each row holds the online and offline seconds recorded that day, availability (online over recorded time, null when nothing was recorded) and coverage (the share of the day with a recorded state).

Time with no recorded state is never counted as downtime: it lowers coverage only. The screen's current open interval is included up to now and marks its days live. Days with nothing recorded have no row. Offline is recorded after the screen has been unreachable for 60 seconds. A screen of another project is not_found.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getScreenUptime

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
day_from	query	optional	First UTC day, inclusive. Defaults to 29 days before day_to. With day_to spans at most 366 days.
day_to	query	optional	Last UTC day, inclusive. Defaults to today (UTC).

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/uptime'

Responses

Status	Meaning	Body and headers
200	Daily uptime rows, oldest first.	ScreenUptime (application/json); headers: Cache-Control
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/screens/{id}/presence¶

Get Screen Presence

The screen's online and offline transitions, newest first, from its screen.online and screen.offline events whatever the log lane stores. since (inclusive) and until (exclusive) bound the event time; until defaults to now and since to 30 days before it, at most 366 days. Transitions are kept for the plan's event retention.

A page holds at most limit transitions (default 100, at most 500) with next_cursor, null at the end; pass it back as before. An offline transition the server noticed only when the screen reconnected carries detected_on_reconnect, and its at is when the presence lease ended. Offline is recorded after the screen has been unreachable for 60 seconds.

A screen of another project is not_found.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getScreenPresence

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
since	query	optional	Inclusive lower bound on the transition event time. Defaults to 30 days before until.
until	query	optional	Exclusive upper bound on the transition event time. Defaults to now. until - since is at most 366 days.
limit	query	optional	Page size. A value outside 1-500 is refused with invalid_request naming limit.
before	query	optional	next_cursor of the previous page, with the same since and until.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/presence'

Responses

Status	Meaning	Body and headers
200	Presence transitions, newest first.	ScreenPresenceHistory (application/json); headers: Cache-Control
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/health/trend¶

Get Health Trend

The project's fleet health by UTC hour: how many screens reported, and how many of them were hot (at or above 80 °C), had a disconnected display, or were crashing (3 or more crashes in 24 hours). from (inclusive) and to (exclusive) default to the last 24 hours, at most 93 days; a page holds at most limit rows (default 100, at most 500) with next_cursor, null at the end.

Hours follow reports by up to about 5 minutes.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getHealthTrend

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
from	query	optional	Inclusive lower bound on the report time. Defaults to 24 hours before to.
to	query	optional	Exclusive upper bound on the report time. Defaults to now.
limit	query	optional	Page size.
cursor	query	optional	next_cursor of the previous page, with the same filters. Opaque.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/health/trend'

Responses

Status	Meaning	Body and headers
200	A page of hourly fleet health.	HealthTrend (application/json); headers: Cache-Control
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/uptime/daily¶

Get Project Uptime

Daily availability of the project's screens over inclusive UTC days (defaults and range as GET /api/screens/{id}/uptime). Each row sums the online and offline seconds of the screens with a recorded state that day; coverage is the share of those screens' day with a recorded state.

Intervals count when they end, so today's row covers intervals that ended so far; the live online count is in the dashboard summary.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getProjectUptime

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
day_from	query	optional	First UTC day, inclusive. Defaults to 29 days before day_to. With day_to spans at most 366 days.
day_to	query	optional	Last UTC day, inclusive. Defaults to today (UTC).

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/uptime/daily'

Responses

Status	Meaning	Body and headers
200	Daily uptime rows, oldest first.	ProjectUptime (application/json); headers: Cache-Control
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/fleet-links¶

List Fleet Links

Lists the project's fleet links, oldest first (at most 50). For a Read only credential each url is empty and url_redacted is true, since the URL creates screens.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listFleetLinks

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/fleet-links'

Responses

Status	Meaning	Body and headers
200	The project's fleet links.	FleetLinkList (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/fleet-links¶

Create Fleet Link

Creates a fleet link: one Player URL (https://play.<domain>/player/#fleet=<secret>) that turns every device opening it into its own screen in this project, without a pairing code. Put it in a device manager, such as a Google Admin console kiosk app.

Each new screen gets the link's tags and playlist, and a label from the device (its administrator asset ID, then location), else the next default label. A Player that already holds a screen never makes another: its key stays the screen's identity across reloads and relaunches.

After a powerwash or reinstall, a device that reports the serial or DUID of a screen a fleet link of this project created recovers that screen (screen.recovered) instead of creating a new one, once the old key has been silent for ten minutes.

The secret travels in the URL fragment, which browsers never send to a server. max_screens caps the screens the link creates; the project's screen limit applies as for any screen. A project has at most 50 fleet links (fleet_link_limit_reached). Appends fleet_link.created.

An exact retry with the same Idempotency-Key returns this same answer for twenty-four hours.

Authentication: projectBearer OR dashboardSession
Request body: FleetLinkWrite
Operation ID: createFleetLink

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
label (required, string)	minLength: 1 maxLength: 80
enabled (optional, boolean)	Defaults to true.
tags (optional, ScreenTags)	Fleet selector tags, 0 to 16 unique exact tags, each matching the media tag grammar. On ScreenPatch the array replaces the whole set and an empty array clears it; a duplicate or malformed tag is invalid_request. Changing tags bumps the screen revision (If-Match guards it) and appends screen.updated with details.tags; it never changes the manifest revision. Tags are never on the runtime manifest and never authorization.
playlist_id (optional, string)
max_screens (optional, integer)	minimum: 1 maximum: 10000

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/fleet-links'

Responses

Status	Meaning	Body and headers
201	Created, with its url.	FleetLink (application/json); headers: Cache-Control
400	invalid_request, including an unknown playlist_id or a malformed tag.	Problem (application/problem+json)
409	fleet_link_limit_reached or idempotency_mismatch.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/fleet-links/{id}¶

Get Fleet Link

One fleet link. For a Read only credential url is empty and url_redacted is true.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getFleetLink

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/fleet-links/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	One fleet link.	FleetLink (application/json); headers: ETag, Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PATCH/api/fleet-links/{id}¶

Update Fleet Link

Changes any of label, enabled, tags, playlist_id and max_screens; null clears playlist_id or max_screens. A disabled link creates and recovers no screens; a device opening it shows its pairing code instead. Changes apply to screens the link creates from now on, never to screens it already created. Appends fleet_link.updated. If-Match guards the revision.

Authentication: projectBearer OR dashboardSession
Request body: FleetLinkPatch
Operation ID: updateFleetLink

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
label (optional, string)	minLength: 1 maxLength: 80
enabled (optional, boolean)
tags (optional, ScreenTags)	Fleet selector tags, 0 to 16 unique exact tags, each matching the media tag grammar. On ScreenPatch the array replaces the whole set and an empty array clears it; a duplicate or malformed tag is invalid_request. Changing tags bumps the screen revision (If-Match guards it) and appends screen.updated with details.tags; it never changes the manifest revision. Tags are never on the runtime manifest and never authorization.
playlist_id (optional, string)	null clears the playlist.
max_screens (optional, integer)	null removes the cap. minimum: 1 maximum: 10000

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/fleet-links/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Updated fleet link.	FleetLink (application/json); headers: ETag
400	invalid_request.	Problem (application/problem+json)
412	revision_conflict — If-Match is stale; the error's current_revision carries the current revision.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/fleet-links/{id}¶

Delete Fleet Link

Deletes the fleet link. Its URL stops working at once; screens it created stay, with their playlists and tags. Appends fleet_link.deleted. If-Match guards the revision.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: deleteFleetLink

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/fleet-links/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
204	Deleted.	no body
412	revision_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/fleet-links/{id}/rotate¶

Rotate Fleet Link

Replaces the link's secret and returns the new url. The old URL stops working at once; screens already created keep playing, since a paired Player never presents the link again. Appends fleet_link.updated with details.rotated true. If-Match guards the revision.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: rotateFleetLink

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/fleet-links/RESOURCE_ID/rotate'

Responses

Status	Meaning	Body and headers
200	The fleet link with its new url.	FleetLink (application/json); headers: ETag, Cache-Control
412	revision_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Reviews of agent changes

GET/api/reviews¶

List Reviews

The project's reviews (docs/reviews.md): playlist and screen changes proposed under Propose access, 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, 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.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listReviews

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
state	query	optional
kind	query	optional
limit	query	optional
cursor	query	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/reviews'

Responses

Status	Meaning	Body and headers
200	One page of reviews.	ReviewList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/reviews/{id}¶

Get Review

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.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getReview

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/reviews/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	The review.	Review (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/reviews/{id}/locate¶

Locate Review

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.

Authentication: dashboardSession
Request body: none
Operation ID: locateReview

Parameters

Name	Send in	Required?	Description
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/reviews/RESOURCE_ID/locate'

Responses

Status	Meaning	Body and headers
200	The review's project.	ReviewLocation (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/reviews/{id}/approve¶

Approve Review

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.

A decided review is review_not_pending; repeating the same decision replays.

Authentication: dashboardSession
Request body: ReviewApproveRequest
Operation ID: approveReview

Parameters

Name	Send in	Required?	Description
id	path	required
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
include_dependents (optional, boolean)	Also approve, in order, the screen changes waiting on this playlist review.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/reviews/RESOURCE_ID/approve'

Responses

Status	Meaning	Body and headers
200	The approved review, and the dependents' outcomes.	ReviewDecisionResult (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/reviews/{id}/reject¶

Reject Review

Rejects a pending review with a reason the proposer reads. Approver only, as approveReview. Nothing changes on glass; a rejected playlist create stays unapproved.

Authentication: dashboardSession
Request body: ReviewRejectRequest
Operation ID: rejectReview

Parameters

Name	Send in	Required?	Description
id	path	required
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
reason (required, string)	minLength: 1 maxLength: 500

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/reviews/RESOURCE_ID/reject'

Responses

Status	Meaning	Body and headers
200	The rejected review.	ReviewDecisionResult (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/reviews/{id}/request-changes¶

Request Review Changes

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.

Authentication: dashboardSession
Request body: ReviewChangesRequest
Operation ID: requestReviewChanges

Parameters

Name	Send in	Required?	Description
id	path	required
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
note (required, string)	minLength: 1 maxLength: 500

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/reviews/RESOURCE_ID/request-changes'

Responses

Status	Meaning	Body and headers
200	The review, state changes_requested.	ReviewDecisionResult (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/reviews/{id}/withdraw¶

Withdraw Review

Withdraws a pending playlist or screen 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 withdrawn playlist create stays unapproved.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: withdrawReview

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/reviews/RESOURCE_ID/withdraw'

Responses

Status	Meaning	Body and headers
200	The withdrawn review.	ReviewDecisionResult (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Private advertising networks and campaigns

GET/api/advertising/network¶

Get Advertising Network

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

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getAdvertisingNetwork

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/network'

Responses

Status	Meaning	Body and headers
200	Network.	AdvertisingNetwork (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/network¶

Create Advertising Network

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

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingNetworkCreate
Operation ID: createAdvertisingNetwork

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request body fields

Field	Description
name (required, string)	maxLength: 120

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/network'

Responses

Status	Meaning	Body and headers
200	Network.	AdvertisingNetwork (application/json)
403	forbidden - the project lacks screen capability or has an unknown plan.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/network/rate¶

Set Advertising Default Rate

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.

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingRate
Operation ID: setAdvertisingDefaultRate

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.

Request body fields

Field	Description
rate_mcr_per_15s (required, McrString)	Exact integer millicredit amount as a canonical decimal string. 1 credit is 1000 mcr. pattern: "^-?[0-9]+$"

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/network/rate'

Responses

Status	Meaning	Body and headers
200	Updated network.	AdvertisingNetwork (application/json)
412	revision_conflict - If-Match is stale.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/inventory¶

List Advertising Inventory

The calling seller's opted-in inventory.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listAdvertisingInventory

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/inventory'

Responses

Status	Meaning	Body and headers
200	Inventory.	AdvertisingInventoryList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PUT/api/advertising/inventory/{screen_id}¶

Put Advertising Inventory

Upserts one owned screen's inventory. Verifies screen ownership. A rate override of null restores inheritance, not zero. A change that alters an accepted campaign's effective rate pauses that campaign.

Authentication: projectBearer
Request body: AdvertisingInventoryWrite
Operation ID: putAdvertisingInventory

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
screen_id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
ads_enabled (required, boolean)
site_name (optional, string)	maxLength: 120
city (optional, string)	maxLength: 120
region (optional, string)	maxLength: 120
venue_type (optional, string)	maxLength: 64
audience_tags (optional, array)
placement (optional, string)	maxLength: 120
public_description (optional, string)	maxLength: 500
rate_override_mcr_per_15s (optional, inline)	Null restores inheritance from the project default; it never means zero.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/inventory/SCREEN_ID'

Responses

Status	Meaning	Body and headers
200	Stored inventory.	AdvertisingInventory (application/json)
403	forbidden - the screen is not owned by this project.	Problem (application/problem+json)
412	revision_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/slots¶

List Advertising Slots

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listAdvertisingSlots

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/slots'

Responses

Status	Meaning	Body and headers
200	Slots.	AdvertisingSlotList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/slots¶

Create Advertising Slot

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

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingSlotWrite
Operation ID: createAdvertisingSlot

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request body fields

Field	Description
name (required, string)	minLength: 1 maxLength: 120
enabled (optional, boolean)
accepted_media (required, array)
max_image_duration_ms (required, integer)	minimum: 5000 maximum: 30000
max_video_duration_ms (required, integer)	minimum: 1000 maximum: 120000
rate_override_mcr_per_15s (optional, inline)
vast_tag_url (optional, inline)	The seller's own VAST 2-4 ad tag, tried when no invited campaign fills this slot on the seller's own screens. HTTPS on port 443 or 8443 to a public host only. The backend fetches it, follows up to five Wrappers, ingests the chosen progressive MP4 or WebM MediaFile into the project's media, and fires Impression, creativeView and start on an accepted start, complete on an accepted completion, and Error on failure. Quartile trackers are not fired. Macros [CACHEBUSTING], [TIMESTAMP], [SCREENRIG_SCREEN_ID], [SCREENRIG_SLOT_ID] and [SCREENRIG_PAGE_ID] are expanded. The slot must accept video. Null, absent, or empty clears the tag. Buyers never see it.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/slots'

Responses

Status	Meaning	Body and headers
201	Slotslot.	AdvertisingSlot (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/slots/{id}¶

Update Advertising Slot

Updates one seller slot. If-Match carries the slot revision. A rate override change re-runs the pricing fence.

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingSlotWrite
Operation ID: updateAdvertisingSlot

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.

Request body fields

Field	Description
name (required, string)	minLength: 1 maxLength: 120
enabled (optional, boolean)
accepted_media (required, array)
max_image_duration_ms (required, integer)	minimum: 5000 maximum: 30000
max_video_duration_ms (required, integer)	minimum: 1000 maximum: 120000
rate_override_mcr_per_15s (optional, inline)
vast_tag_url (optional, inline)	The seller's own VAST 2-4 ad tag, tried when no invited campaign fills this slot on the seller's own screens. HTTPS on port 443 or 8443 to a public host only. The backend fetches it, follows up to five Wrappers, ingests the chosen progressive MP4 or WebM MediaFile into the project's media, and fires Impression, creativeView and start on an accepted start, complete on an accepted completion, and Error on failure. Quartile trackers are not fired. Macros [CACHEBUSTING], [TIMESTAMP], [SCREENRIG_SCREEN_ID], [SCREENRIG_SLOT_ID] and [SCREENRIG_PAGE_ID] are expanded. The slot must accept video. Null, absent, or empty clears the tag. Buyers never see it.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/slots/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Updated slot.	AdvertisingSlot (application/json)
412	revision_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/memberships¶

List Advertising Memberships

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listAdvertisingMemberships

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/memberships'

Responses

Status	Meaning	Body and headers
200	Memberships.	AdvertisingMembershipList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/memberships/{id}¶

Update Advertising Membership

Explicit seller policy/scope edit. An active membership is changed here, never by sending a second invitation. Scope changes stop new selection; financial history is preserved.

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingMembershipScope
Operation ID: updateAdvertisingMembership

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.

Request body fields

Field	Description
policy (required, string)	Allowed: "trusted", "review_required"
screen_ids (required, array)
slot_ids (required, array)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/memberships/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Updated membership.	AdvertisingMembership (application/json)
412	revision_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/memberships/{id}/revoke¶

Revoke Advertising Membership

Revokes one membership. Stops new selection for that network; it does not clear the advertiser flag, other memberships, or settled history.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: revokeAdvertisingMembership

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/memberships/RESOURCE_ID/revoke'

Responses

Status	Meaning	Body and headers
200	Revoked membership.	AdvertisingMembership (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/networks¶

List Advertising Joined Networks

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

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listAdvertisingJoinedNetworks

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/networks'

Responses

Status	Meaning	Body and headers
200	Joined networks.	AdvertisingJoinedNetworkList (application/json)
403	forbidden - the project lacks the advertiser flag.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/networks/{seller_project_id}/inventory¶

List Advertising Joined Inventory

Opted-in inventory and reusable slots inside the caller's membership. Never exposes the seller's screenshots, playlists, or project-wide data.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listAdvertisingJoinedInventory

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
seller_project_id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/networks/SELLER_PROJECT_ID/inventory'

Responses

Status	Meaning	Body and headers
200	Permitted inventory and slots.	AdvertisingJoinedInventory (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/creatives¶

List Advertising Creatives

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listAdvertisingCreatives

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/creatives'

Responses

Status	Meaning	Body and headers
200	Creatives.	AdvertisingCreativeList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/creatives¶

Create Advertising Creative

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.

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingCreativeCreate
Operation ID: createAdvertisingCreative

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
media_id (required, string)
copy (optional, string)	maxLength: 500

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/creatives'

Responses

Status	Meaning	Body and headers
201	Creative.	AdvertisingCreative (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/creatives/{id}¶

Get Advertising Creative

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getAdvertisingCreative

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/creatives/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Creative.	AdvertisingCreative (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/campaigns¶

List Advertising Campaigns

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listAdvertisingCampaigns

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/campaigns'

Responses

Status	Meaning	Body and headers
200	Campaigns.	AdvertisingCampaignList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/campaigns¶

Create Advertising Campaign

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

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingCampaignDraft
Operation ID: createAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request body fields

Field	Description
name (required, string)	minLength: 1 maxLength: 120
daily_cap_mcr (required, McrString)	Exact integer millicredit amount as a canonical decimal string. 1 credit is 1000 mcr. pattern: "^-?[0-9]+$"
lifetime_cap_mcr (required, McrString)	Exact integer millicredit amount as a canonical decimal string. 1 credit is 1000 mcr. pattern: "^-?[0-9]+$"
image_duration_ms (optional, integer)	Campaign-wide image dwell time. Videos keep their server-verified duration. default: 10000 minimum: 5000 maximum: 30000
max_play_price_mcr (optional, inline)	Positive maximum completed-play price. Omit for no additional ceiling.
flight_start (required, string)	format: "date-time"
flight_end (required, string)	format: "date-time"
networks (required, array)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/campaigns'

Responses

Status	Meaning	Body and headers
201	Draft campaign.	AdvertisingCampaign (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/campaigns/{id}¶

Get Advertising Campaign

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Campaign.	AdvertisingCampaign (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/campaigns/{id}¶

Update Advertising Campaign

Updates a draft campaign. If-Match carries the campaign revision. A budget reduction below already spent plus committed reservations is rejected with the minimum permitted value.

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingCampaignDraft
Operation ID: updateAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.

Request body fields

Field	Description
name (required, string)	minLength: 1 maxLength: 120
daily_cap_mcr (required, McrString)	Exact integer millicredit amount as a canonical decimal string. 1 credit is 1000 mcr. pattern: "^-?[0-9]+$"
lifetime_cap_mcr (required, McrString)	Exact integer millicredit amount as a canonical decimal string. 1 credit is 1000 mcr. pattern: "^-?[0-9]+$"
image_duration_ms (optional, integer)	Campaign-wide image dwell time. Videos keep their server-verified duration. default: 10000 minimum: 5000 maximum: 30000
max_play_price_mcr (optional, inline)	Positive maximum completed-play price. Omit for no additional ceiling.
flight_start (required, string)	format: "date-time"
flight_end (required, string)	format: "date-time"
networks (required, array)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Updated campaign.	AdvertisingCampaign (application/json)
412	revision_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/campaigns/{id}/quote¶

Quote Advertising Campaign

Prices the campaign's current effective rates, formats, durations, flight and caps before activation. The quote is time-bounded and becomes stale when any pricing generation or effective rate changes.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: quoteAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID/quote'

Responses

Status	Meaning	Body and headers
201	Quote.	AdvertisingQuote (application/json)
412	revision_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/campaigns/{id}/activate¶

Activate Advertising Campaign

Explicitly accepts the named current quote and activates the campaign. Atomically checks ownership, membership, quote expiry, rate revisions, accepted scope and same-project denial, then records purchase terms. No wallet debit and no seller revenue occur from accepting terms. The same key with the same body replays; a changed body is a conflict.

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingQuoteAccept
Operation ID: activateAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
quote_id (required, string)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID/activate'

Responses

Status	Meaning	Body and headers
200	Active or pending-review campaign.	AdvertisingCampaign (application/json)
409	quote_stale or self_deal or resource_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/campaigns/{id}/pause¶

Pause Advertising Campaign

Pauses new reservations for this campaign. Already-started valid ads normally finish and are charged on completion.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: pauseAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID/pause'

Responses

Status	Meaning	Body and headers
200	Paused campaign.	AdvertisingCampaign (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/campaigns/{id}/resume¶

Resume Advertising Campaign

Resumes a manually paused campaign. It cannot clear a price_change_pending block; a top-up, schedule tick, or seller action cannot supply that consent.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: resumeAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID/resume'

Responses

Status	Meaning	Body and headers
200	Resumed campaign.	AdvertisingCampaign (application/json)
409	price_change_pending - accept current rates first.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/campaigns/{id}/accept-rates¶

Accept Advertising Rates

The buyer's explicit acceptance of changed effective rates, bound to quote ID, campaign revision and current pricing generations. It atomically replaces future delivery terms, records the actor and time, and clears the sticky price-change block. Another concurrent rate change leaves the campaign paused.

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingQuoteAccept
Operation ID: acceptAdvertisingRates

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.

Request body fields

Field	Description
quote_id (required, string)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID/accept-rates'

Responses

Status	Meaning	Body and headers
200	Reactivated campaign.	AdvertisingCampaign (application/json)
409	price_change_pending or quote_stale.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/reviews¶

List Advertising Reviews

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

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listAdvertisingReviews

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/reviews'

Responses

Status	Meaning	Body and headers
200	Reviews.	AdvertisingReviewList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/reviews/{id}/approve¶

Approve Advertising Review

Approves one exact submitted creative revision. Approval does not choose the buyer's budget or grant access to its media library. A person must be able to approve reviews (approver_required). The same review is also reachable as kind ad_creative under /api/reviews.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: approveAdvertisingReview

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/reviews/RESOURCE_ID/approve'

Responses

Status	Meaning	Body and headers
200	Approved review.	AdvertisingReview (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/reviews/{id}/reject¶

Reject Advertising Review

Rejects one exact submitted creative revision with a reason the buyer reads on the creative. A person must be able to approve reviews (approver_required).

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingReviewRejection
Operation ID: rejectAdvertisingReview

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request body fields

Field	Description
reason (required, string)	minLength: 1 maxLength: 500

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/reviews/RESOURCE_ID/reject'

Responses

Status	Meaning	Body and headers
200	Rejected review.	AdvertisingReview (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/reports/spend¶

Get Advertising Spend

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.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getAdvertisingSpend

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
campaign_id	query	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/reports/spend?campaign_id=CAMPAIGN_ID'

Responses

Status	Meaning	Body and headers
200	Spend report.	AdvertisingSpendReport (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/reports/delivery¶

Get Advertising Delivery

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.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getAdvertisingDelivery

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
from	query	required
to	query	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/reports/delivery?from=FROM&to=TO'

Responses

Status	Meaning	Body and headers
200	Delivery report.	AdvertisingDeliveryReport (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/reviews/{id}¶

Get Advertising Review

Seller detail for one review of its network. Returns the review and the exact submitted creative revision. It never exposes the buyer's other media.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getAdvertisingReview

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/reviews/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Review and its creative.	AdvertisingReviewDetail (application/json)
404	not_found - the review is unknown to this seller.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/reviews/{id}/content¶

Get Advertising Review Content

Streams only the exact creative revision this seller's own review refers to. Ownership stays with the buyer project; no object key or signed location is published, and no other buyer media is reachable. The ETag is the creative's strong SHA-256 and never changes for a review.

A dashboard session response is private, no-cache, so the browser keeps one copy and revalidates it; a project bearer response stays private, no-store.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getAdvertisingReviewContent

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Range	header	optional	V1 accepts one byte range only.
If-None-Match	header	optional	Strong creative SHA-256 ETag returned by this route.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/reviews/RESOURCE_ID/content'

Responses

Status	Meaning	Body and headers
200	The review's exact creative bytes.	no body; headers: Accept-Ranges, Content-Length, ETag, Cache-Control
206	One standards-correct byte range.	no body; headers: Content-Range, ETag, Cache-Control
304	The creative's ETag matches If-None-Match, checked after the review resolves in the seller project. No body or egress increment is produced.	no body; headers: ETag, Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

HEAD/api/advertising/reviews/{id}/content¶

Head Advertising Review Content

Authentication: projectBearer
Request body: none
Operation ID: headAdvertisingReviewContent

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Range	header	optional	V1 accepts one byte range only.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request HEAD --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://screenrig.ai/api/advertising/reviews/RESOURCE_ID/content'

Responses

Status	Meaning	Body and headers
200	Metadata only.	no body; headers: Content-Length, ETag
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/reviews/{id}/request-changes¶

Request Advertising Review Changes

The seller asks the buyer for changes to one submitted creative revision. The review becomes changes_requested with the note in reason; the buyer reads it on the creative, and the next review the campaign opens for this seller links previous_review_id. A person must be able to approve reviews (approver_required).

Authentication: projectBearer OR dashboardSession
Request body: ReviewChangesRequest
Operation ID: requestAdvertisingReviewChanges

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request body fields

Field	Description
note (required, string)	minLength: 1 maxLength: 500

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/reviews/RESOURCE_ID/request-changes'

Responses

Status	Meaning	Body and headers
200	The review, state changes_requested.	AdvertisingReview (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Comments

GET/api/comment/screen/{id}¶

Get Screen Comments

Opaque agent comments on the named screen. ScreenRig does not read or use them. They are not authorization and are not on the runtime manifest. A screen with no comments returns comments null. Archived screens remain addressable. Authenticated /api control-plane read; costs 1 credit.

Authentication: projectBearer
Request body: none
Operation ID: getScreenComments

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/comment/screen/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Comments	Comments (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PUT/api/comment/screen/{id}¶

Put Screen Comments

Replaces opaque agent comments on the named screen. The comments value must be a JSON object whose compact UTF-8 form is at most 1024 bytes. Last-write-wins on the comments field only; revision, updated_at, and the runtime manifest are unchanged.

Authentication: projectBearer
Request body: CommentsWrite
Operation ID: putScreenComments

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
comments (required, object)	Opaque agent JSON object. Compact UTF-8 serialization must be at most 1024 bytes. Nested objects, arrays, and strings are allowed. Arrays, strings, numbers, booleans, and null are rejected as the comments value itself.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/comment/screen/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Comments	Comments (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/comment/screen/{id}¶

Delete Screen Comments

Unsets screen comments. Idempotent if already unset. Does not bump revision or remint the runtime manifest.

Authentication: projectBearer
Request body: none
Operation ID: deleteScreenComments

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/comment/screen/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
204	Unset	no body
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/comment/playlist/{id}¶

Get Playlist Comments

Opaque agent comments on the named playlist. ScreenRig does not read or use them. A playlist with no comments returns comments null. Authenticated /api control-plane read; costs 1 credit.

Authentication: projectBearer
Request body: none
Operation ID: getPlaylistComments

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/comment/playlist/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Comments	Comments (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PUT/api/comment/playlist/{id}¶

Put Playlist Comments

Replaces opaque agent comments on the named playlist. Compact UTF-8 JSON of the comments object must be at most 1024 bytes. Last-write-wins on the comments field only; revision and the runtime manifest are unchanged.

Authentication: projectBearer
Request body: CommentsWrite
Operation ID: putPlaylistComments

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
comments (required, object)	Opaque agent JSON object. Compact UTF-8 serialization must be at most 1024 bytes. Nested objects, arrays, and strings are allowed. Arrays, strings, numbers, booleans, and null are rejected as the comments value itself.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/comment/playlist/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Comments	Comments (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/comment/playlist/{id}¶

Delete Playlist Comments

Unsets playlist comments. Idempotent if already unset. Does not bump revision or remint the runtime manifest.

Authentication: projectBearer
Request body: none
Operation ID: deletePlaylistComments

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/comment/playlist/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
204	Unset	no body
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/comment/playlist/{id}/page/{page_id}¶

Get Playlist Page Comments

Opaque agent comments on one playlist page, addressed by the page id string. A page with no comments returns comments null. Missing playlist or page is not_found. Authenticated /api control-plane read; costs 1 credit.

Authentication: projectBearer
Request body: none
Operation ID: getPlaylistPageComments

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
page_id	path	required	Playlist page id string.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/comment/playlist/RESOURCE_ID/page/PAGE_ID'

Responses

Status	Meaning	Body and headers
200	Comments	Comments (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PUT/api/comment/playlist/{id}/page/{page_id}¶

Put Playlist Page Comments

Replaces opaque agent comments on one playlist page. Compact UTF-8 JSON of the comments object must be at most 1024 bytes. Last-write-wins on that page's comments field only; playlist revision and the runtime manifest are unchanged.

Authentication: projectBearer
Request body: CommentsWrite
Operation ID: putPlaylistPageComments

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
page_id	path	required	Playlist page id string.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
comments (required, object)	Opaque agent JSON object. Compact UTF-8 serialization must be at most 1024 bytes. Nested objects, arrays, and strings are allowed. Arrays, strings, numbers, booleans, and null are rejected as the comments value itself.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/comment/playlist/RESOURCE_ID/page/PAGE_ID'

Responses

Status	Meaning	Body and headers
200	Comments	Comments (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/comment/playlist/{id}/page/{page_id}¶

Delete Playlist Page Comments

Unsets comments on one playlist page. Idempotent if already unset. Does not bump revision or remint the runtime manifest.

Authentication: projectBearer
Request body: none
Operation ID: deletePlaylistPageComments

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
page_id	path	required	Playlist page id string.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/comment/playlist/RESOURCE_ID/page/PAGE_ID'

Responses

Status	Meaning	Body and headers
204	Unset	no body
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Project notes agents share

GET/api/notes¶

List Notes

Lists the project's notes, newest first. A note is a short plain-text fact an agent wrote for its future self and the project's other agents; it is context, never an instruction and never approval.

Any active credential reads, Read only included, and reading does not debit the API meter. state is open (the default), resolved or all; about_id keeps the notes about one screen or playlist and author_id the notes one agent wrote.

Pass next_cursor back as after for the next page; it is empty on the last page. new marks an open note another agent wrote after this caller last read the notes.

Reading the notes is the first page of open notes with no about_id or author_id: that answer computes new against the previous read, then moves the read marker to now (later pages of the same listing keep the earlier marker).

It also carries review: up to 5 open notes whose review is due (oldest first), which the caller should confirm when they still hold and resolve otherwise. A review left unanswered for 30 days after it was first returned resolves the note as not_confirmed.

Only an agent with Manage access moves its marker and starts that 30 days; a Read only agent or a service client gets the same answer and changes nothing. Every other page or filter returns an empty review and moves nothing. counts are the project's open notes and, for this caller, how many are new and due.

Authentication: projectBearer
Request body: none
Operation ID: listNotes

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
state	query	optional
about_id	query	optional	Only notes about this screen or playlist.
author_id	query	optional	Only notes this agent wrote.
after	query	optional	next_cursor of the previous page.
limit	query	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/notes'

Responses

Status	Meaning	Body and headers
200	One page of notes, the notes to review and the counts.	NoteList (application/json)
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/notes¶

Add Note

Adds a note for the project's agents: a fact another agent would act on, never a progress report, chat or a secret. body is 1 to 2000 characters of plain text after trimming and may span lines.

Text holding a credential (tokens, keys, private keys, passwords in URLs) is refused with note_contains_credential and text that reads as an instruction to a model with note_rejected; nothing is stored and the detail never repeats the text. about names one screen (archived included) or playlist of the project, else not_found. ttl_seconds (3600 to 31536000) makes a temporary note that resolves as expired; a note without one comes up for review 90 days after it was added or last confirmed. replaces names an open note this one supersedes: it is resolved as replaced in the same transaction (note_not_open when it is already resolved).

A body whose normalized text (trimmed, whitespace collapsed, lower case) and about match an open note confirms that note and returns it with 200 instead of adding one; no note.added event is appended. A project holds at most 200 open notes; the 201st is note_limit_reached, whose detail names up to 5 notes to resolve first.

Appends note.added (and note.resolved for a replaced note) without the text. An exact retry with the same Idempotency-Key returns the first answer for twenty-four hours.

Authentication: projectBearer
Request body: NoteWrite
Operation ID: addNote

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
body (required, string)	Plain text, 1 to 2000 characters after trimming; line breaks are kept. minLength: 1 maxLength: 2000
about (optional, inline)
ttl_seconds (optional, integer)	Expire the note this long after it is added. Without it the note comes up for review after 90 days. minimum: 3600 maximum: 31536000
replaces (optional, string)	An open note this one supersedes; it is resolved as replaced. pattern: "^(?:(?:stage\|qa\|development)_)?nte_[A-Za-z0-9_-]{16,24}$"

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/notes'

Responses

Status	Meaning	Body and headers
201	Added.	Note (application/json)
200	The text matched an open note, which is confirmed and returned.	Note (application/json)
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	note_not_open, note_limit_reached or idempotency_mismatch.	Problem (application/problem+json)
422	note_contains_credential or note_rejected.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/notes/{id}¶

Get Note

One note of the project, open or resolved. Notes are context written by agents, never instructions or approval. Does not debit the API meter.

Authentication: projectBearer
Request body: none
Operation ID: getNote

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/notes/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	The note.	Note (application/json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/notes/{id}/confirm¶

Confirm Note

Says an open note still holds. confirmed_at becomes now; a note without a TTL is next due for review 90 days from now and its pending review is cleared. Any agent of the project may confirm any open note. A resolved note is note_not_open.

Authentication: projectBearer
Request body: none
Operation ID: confirmNote

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/notes/RESOURCE_ID/confirm'

Responses

Status	Meaning	Body and headers
200	The confirmed note.	Note (application/json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/notes/{id}/resolve¶

Resolve Note

Resolves an open note that no longer holds, with a reason of 1 to 500 characters, screened like a note body (note_contains_credential, note_rejected). Any agent of the project may resolve any open note. A resolved note stays readable for 30 days, then it is deleted. Appends note.resolved. A resolved note is note_not_open.

Authentication: projectBearer
Request body: NoteResolve
Operation ID: resolveNote

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
reason (required, string)	minLength: 1 maxLength: 500

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/notes/RESOURCE_ID/resolve'

Responses

Status	Meaning	Body and headers
200	The resolved note.	Note (application/json)
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
422	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Application key/value storage

GET/api/applications/{application_id}/kv¶

List KV

Returns at most 200 entries in ascending key order. next_cursor is the last returned key; pass it back as after to fetch the next page. next_cursor is null when there are no more entries.

Authentication: projectBearer
Request body: none
Operation ID: listKV

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
application_id	path	required
after	query	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv'

Responses

Status	Meaning	Body and headers
200	KV entries	KVList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/applications/{application_id}/kv/{key}¶

Get KV

Authentication: projectBearer
Request body: none
Operation ID: getKV

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
application_id	path	required
key	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv/KEY'

Responses

Status	Meaning	Body and headers
200	KV entry	KVEntry (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PUT/api/applications/{application_id}/kv/{key}¶

Put KV

Authentication: projectBearer
Request body: KVWrite
Operation ID: putKV

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
application_id	path	required
key	path	required
If-Match	header	optional	Optional positive resource revision. Omit to create or overwrite a key; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
value_base64 (required, string)	maxLength: 1398104
content_type (optional, string)	default: "application/octet-stream" minLength: 1 maxLength: 127

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv/KEY'

Responses

Status	Meaning	Body and headers
200	KV entry	KVEntry (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/applications/{application_id}/kv/{key}¶

Delete KV

Authentication: projectBearer
Request body: none
Operation ID: deleteKV

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
application_id	path	required
key	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv/KEY'

Responses

Status	Meaning	Body and headers
204	Deleted	no body
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/applications/{application_id}/kv-webhooks¶

List KVWebhooks

Lists the application's incoming key/value webhooks, oldest first (at most 20), each with the key it writes, its ingest url and last_used_at once it has written. The secret is never returned here.

Authentication: projectBearer
Request body: none
Operation ID: listKVWebhooks

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
application_id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv-webhooks'

Responses

Status	Meaning	Body and headers
200	The application's key/value webhooks.	KVWebhookList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/applications/{application_id}/kv-webhooks¶

Create KVWebhook

Creates an incoming key/value webhook: one URL that writes one key of this application, so an outside system (Zapier, Make, a point of sale, a cron job, curl) pushes data to screens with one HTTP POST; see POST /api/applications/{application_id}/kv-webhooks/{webhook_id}/write. The key need not exist yet.

The answer is the only place the secret appears (with the rotate answer): store it in the sending system at once; the server keeps a digest. An application has at most 20 webhooks (kv_webhook_limit_reached). Appends kv_webhook.created. An exact retry with the same Idempotency-Key returns this same answer, secret included, for twenty-four hours.

Authentication: projectBearer
Request body: KVWebhookCreate
Operation ID: createKVWebhook

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
application_id	path	required
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
key (required, string)	minLength: 1 maxLength: 256 pattern: "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$"
description (optional, string)	What sends to it, for the people reading the list. Trimmed; it must not hold a credential. maxLength: 200

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv-webhooks'

Responses

Status	Meaning	Body and headers
201	Created, with its url and secret.	KVWebhookWithSecret (application/json); headers: Cache-Control
400	invalid_request, including a malformed key or a description that holds a credential.	Problem (application/problem+json)
404	not_found — the application is not in this project.	Problem (application/problem+json)
409	kv_webhook_limit_reached or idempotency_mismatch.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/applications/{application_id}/kv-webhooks/{webhook_id}¶

Delete KVWebhook

Deletes the webhook. Its URL stops working at once; the key it wrote keeps its value. Appends kv_webhook.deleted.

Authentication: projectBearer
Request body: none
Operation ID: deleteKVWebhook

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
application_id	path	required
webhook_id	path	required	The id of one of the application's key/value webhooks.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv-webhooks/WEBHOOK_ID'

Responses

Status	Meaning	Body and headers
204	Deleted.	no body
404	not_found — the webhook is not on this application.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/applications/{application_id}/kv-webhooks/{webhook_id}/rotate-secret¶

Rotate KVWebhook Secret

Replaces the webhook's secret and returns the new one, once. The old secret stops working at once; update the sending system. Appends kv_webhook.secret_rotated. An exact retry with the same Idempotency-Key returns this same answer, secret included, for twenty-four hours.

Authentication: projectBearer
Request body: none
Operation ID: rotateKVWebhookSecret

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
application_id	path	required
webhook_id	path	required	The id of one of the application's key/value webhooks.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv-webhooks/WEBHOOK_ID/rotate-secret'

Responses

Status	Meaning	Body and headers
200	The webhook with its new secret.	KVWebhookWithSecret (application/json); headers: Cache-Control
404	not_found — the webhook is not on this application.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/applications/{application_id}/kv-webhooks/{webhook_id}/write¶

Receive KVWebhook

The URL an outside system posts one key's new value to. It authenticates with the webhook's own secret in the Authorization header only: Bearer <secret>, or HTTP Basic with the webhook id as the username and the secret as the password. A secret in the URL or query is never accepted.

An unknown webhook, one of another application and a wrong secret all answer the same 401. The raw body, at most 1 MiB, becomes the value of the webhook's key, and the Content-Type header its content_type (application/octet-stream when absent; a header that is not one media type is invalid_request).

The write is PUT /api/applications/{application_id}/kv/{key} without If-Match: it replaces the value, increments the revision, is metered and quota-checked like any K/V write, is one billed API request (payment_required when no credit is left), and appends kv.updated.

Idempotency-Key (8 to 200 characters) deduplicates a sender's retries of one write for twenty-four hours, and the same key with another body or content type is idempotency_mismatch; without it every post is a new write. The answer is the key's new metadata, never its value. At most 120 writes per minute per webhook.

Authentication: kvWebhookBearer OR kvWebhookBasic
Request body: string
Operation ID: receiveKVWebhook

Parameters

Name	Send in	Required?	Description
application_id	path	required
webhook_id	path	required	The id of one of the application's key/value webhooks.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Content-Type: */*' --data-binary '@request.bin' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv-webhooks/WEBHOOK_ID/write'

Responses

Status	Meaning	Body and headers
200	The key's new metadata.	KVWebhookWriteResult (application/json); headers: RateLimit-Policy, RateLimit, Cache-Control
400	invalid_request — the body is larger than 1 MiB, the Content-Type is not one media type, or the Idempotency-Key is malformed.	Problem (application/problem+json)
401	unauthorized — missing or wrong credentials, or an unknown webhook. WWW-Authenticate names the Bearer and Basic realms.	Problem (application/problem+json)
409	idempotency_mismatch — the Idempotency-Key was used for another body or content type.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Card data for built-in cards

GET/api/card-data¶

List Card Data

Lists the project's card data documents, at most 200 in ascending key order. next_cursor is the last returned key; pass it back as after for the next page, null when there are no more. Card data documents hold the dynamic properties of card placements (menu sections, ticker items, KPI tiles); the placement's data key names one.

Authentication: projectBearer
Request body: none
Operation ID: listCardData

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
after	query	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/card-data'

Responses

Status	Meaning	Body and headers
200	Card data documents	CardDataList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/card-data/{key}¶

Get Card Data

Returns the document and its revision. ETag is the revision, for If-Match on the next write.

Authentication: projectBearer
Request body: none
Operation ID: getCardData

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
key	path	required	Card data key. May not start with feed:.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/card-data/KEY'

Responses

Status	Meaning	Body and headers
200	Card data document	CardDataEntry (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PUT/api/card-data/{key}¶

Put Card Data

Creates or replaces a card data document. When card placements in the project's playlists bind the key, the document must hold only each bound card's dynamic properties and validate against them; otherwise the write is refused with card_data_invalid naming the card and the property path, and nothing changes. A key no placement binds accepts any JSON object.

Screens showing a placement that reads the key receive screen.card_data_changed and refetch it in place; the project log records kv.updated with a card_data_entry resource, which never reaches a Player. Limits, quota, metering, revisions and idempotency are the application K/V store's.

Authentication: projectBearer
Request body: CardDataWrite
Operation ID: putCardData

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
key	path	required	Card data key. May not start with feed:.
If-Match	header	optional	Optional positive resource revision. Omit to create or overwrite a key; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
document (required, object)	The card data document: a JSON object of at most 1 MiB. When a card placement binds the key it holds only that card's dynamic properties.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/card-data/KEY'

Responses

Status	Meaning	Body and headers
200	Card data document	CardDataEntry (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/card-data/{key}¶

Delete Card Data

Deletes a card data document. A card bound to the key is hidden on glass until a document is written again.

Authentication: projectBearer
Request body: none
Operation ID: deleteCardData

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
key	path	required	Card data key. May not start with feed:.
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/card-data/KEY'

Responses

Status	Meaning	Body and headers
204	Deleted	no body
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Durable project events

GET/api/events¶

List Events

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. screen_id, from and to are refused with invalid_request unless source is log.

Both sources take resource_id, type and severity (a minimum), combined with each other 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.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listEvents

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
after	query	optional	A cursor from a previous response: ev1_ for project events (and the event streams). The Player log (source=log) pages with lg1_ or ev1_ cursors by where the server keeps it; treat them as opaque and pass back the one a page returned. A cursor of another kind is refused with invalid_request.
before	query	optional	Pages newest first, strictly older than this cursor: a next_cursor of a newest-first page, or any item cursor (ev1_ for project events; for source=log the opaque cursor its items carry). Empty or absent with order=desc starts at the newest item.
order	query	optional	asc pages oldest first with after; desc pages newest first with before. before implies desc; order=asc with before is refused.
limit	query	optional	Page size. A value outside 1-200 is refused with invalid_request and an errors[] member whose field is limit.
source	query	optional	project lists the sequenced project events. log lists the Player log: Player condition reports (runtime.reported), ascending by receipt time.
resource_id	query	optional	Only items whose resource.id is this id (a screen, playlist, media, webhook, agent or application id). With source=log it is the screen of the record.
type	query	optional	An exact event type such as playlist.updated, or a family prefix ending in a dot such as playlist. for every playlist.* type.
screen_id	query	optional	With source=log, only records of this screen.
severity	query	optional	Minimum severity: info is every item, warning keeps warnings and errors, error keeps errors. Both sources.
from	query	optional	With source=log, the start of the window (inclusive). Defaults to 24 hours before to; a newest-first page without from reaches back to the project's event retention instead.
to	query	optional	With source=log, the end of the window (exclusive). Defaults to now. The window is at most 31 days.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/events'

Responses

Status	Meaning	Body and headers
200	Durable events (source=project) or Player log records (source=log)	EventList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/stream/project¶

Stream Events

Replayable project listen stream. Player log records (runtime.reported) are read with GET /api/events?source=log and are not on this stream. Opening this request costs 1 credit as the listen subscribe. Credit headers are omitted. Later billed events cost 1 credit each; screen.*, runtime.*, and application.event are exempt screen-conversation messages.

Heartbeats and the retry preamble never charge. stream.cursor and stream.resync_required are billed. Debit idempotency is sse-event:<project_id>:<sequence>, so reconnect replay is free. An unpaid billed event is not written and the stream closes.

A stream opened with a dashboard session bills nothing (neither the open nor its events), like the dashboard's API requests; it still takes one of the project's stream slots.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: streamEvents

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
after	query	optional	A cursor from a previous response: ev1_ for project events (and the event streams). The Player log (source=log) pages with lg1_ or ev1_ cursors by where the server keeps it; treat them as opaque and pass back the one a page returned. A cursor of another kind is refused with invalid_request.
Last-Event-ID	header	optional	Durable cursor used when after is absent.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/stream/project'

Responses

Status	Meaning	Body and headers
200	Replayable SSE stream. The query cursor takes precedence over Last-Event-ID. Invalid, future, or pre-retention cursors receive stream.resync_required at the current head and close. No ScreenRig-Credits-* headers.	string (text/event-stream)
402	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Webhooks: signed event delivery

GET/api/webhooks¶

List Webhooks

Lists the project's webhooks, oldest first (at most 10). The signing secret is never returned here. Requires the project capability; a reports-only credential is refused 403 forbidden, because the response includes receiver URLs.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listWebhooks

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks'

Responses

Status	Meaning	Body and headers
200	The project's webhooks.	WebhookList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/webhooks¶

Create Webhook

Creates a webhook that receives the project's own durable events as signed HTTPS POSTs. url must be https on a public Internet host: an IP literal or every current DNS answer of the name must be public (private, loopback, link-local, CGNAT, IPv6 outside 2000::/3, documentation, and other reserved ranges are refused with webhook_url_rejected).

The port must be 443 (the default) or 8443, else webhook_url_rejected. The host is resolved and checked again before every delivery and the connection is dialed to exactly the checked address, so a DNS answer that changes later cannot redirect deliveries. event_types lists exact event types (screen.online) or prefixes ending in .* (screen.*).

A project has at most 10 webhooks (webhook_limit_reached). The server generates the signing secret and returns it only in this answer and in rotate-secret; store it. An exact retry with the same Idempotency-Key returns this same answer, secret included, for twenty-four hours. Delivery starts with the first event after webhook.created.

Authentication: projectBearer
Request body: WebhookWrite
Operation ID: createWebhook

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
url (required, string)	https URL on a public Internet host, port 443 (the default) or 8443. No userinfo or fragment. maxLength: 2048 format: "uri"
event_types (required, WebhookEventTypes)	Exact event types such as screen.online, or prefixes ending in .* such as screen.* (every type starting with screen.). webhook.test is never fanned out by a subscription; it is sent only by POST /api/webhooks/{id}/test.
enabled (optional, boolean)	default: true
description (optional, string)	maxLength: 200

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/webhooks'

Responses

Status	Meaning	Body and headers
201	Created. secret is shown only here and on rotate-secret.	WebhookWithSecret (application/json); headers: Cache-Control
400	invalid_request or webhook_url_rejected.	Problem (application/problem+json)
409	webhook_limit_reached or idempotency_mismatch.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/webhooks/{id}¶

Get Webhook

Requires the project capability; a reports-only credential is refused 403 forbidden, because the response includes receiver URLs.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getWebhook

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	One webhook.	Webhook (application/json); headers: ETag
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PATCH/api/webhooks/{id}¶

Update Webhook

Changes any of url, event_types, enabled, and description (an empty description clears it). A new url is checked like create.

Setting enabled true on a disabled webhook clears its failure state and starts delivery at the event that records the change; events from while it was disabled are not replayed, and deliveries still pending from before the disable are failed with webhook_disabled. Setting enabled false fails its pending deliveries with webhook_disabled.

Appends webhook.updated. If-Match guards the revision.

Authentication: projectBearer
Request body: WebhookPatch
Operation ID: updateWebhook

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
url (optional, string)	maxLength: 2048 format: "uri"
event_types (optional, WebhookEventTypes)	Exact event types such as screen.online, or prefixes ending in .* such as screen.* (every type starting with screen.). webhook.test is never fanned out by a subscription; it is sent only by POST /api/webhooks/{id}/test.
enabled (optional, boolean)
description (optional, string)	An empty string clears the description. maxLength: 200

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/webhooks/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Updated webhook.	Webhook (application/json); headers: ETag
400	invalid_request or webhook_url_rejected.	Problem (application/problem+json)
412	revision_conflict — If-Match is stale; the error's current_revision carries the current revision.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/webhooks/{id}¶

Delete Webhook

Deletes the webhook and appends webhook.deleted. Its pending deliveries are failed with webhook_deleted; its delivery log is no longer addressable and expires with event retention.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: deleteWebhook

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
204	Deleted.	no body; headers: Cache-Control
412	revision_conflict — If-Match is stale; the error's current_revision carries the current revision.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/webhooks/{id}/rotate-secret¶

Rotate Webhook Secret

Replaces the signing secret and returns the new one; the old secret stops signing at once: every attempt that signs after this commits uses the new secret, and at most one attempt per webhook already in flight may still arrive signed with the old one, so accept both briefly. Appends webhook.updated with details.changed [secret].

An exact retry with the same Idempotency-Key returns the same new secret for twenty-four hours.

Authentication: projectBearer
Request body: none
Operation ID: rotateWebhookSecret

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/webhooks/RESOURCE_ID/rotate-secret'

Responses

Status	Meaning	Body and headers
200	The webhook and its new secret.	WebhookWithSecret (application/json); headers: Cache-Control
412	revision_conflict — If-Match is stale; the error's current_revision carries the current revision.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/webhooks/{id}/test¶

Test Webhook

Appends a webhook.test project event and queues one delivery of it to this webhook only (no other webhook receives webhook.test). It works on a disabled webhook, is attempted once without retries, is metered like any delivery, and never changes the webhook's failure state. Poll the deliveries log for its outcome.

Authentication: projectBearer
Request body: none
Operation ID: testWebhook

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/webhooks/RESOURCE_ID/test'

Responses

Status	Meaning	Body and headers
202	The queued test delivery.	WebhookDelivery (application/json); headers: RateLimit-Policy, RateLimit
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/webhooks/{id}/deliveries¶

List Webhook Deliveries

The webhook's delivery log, newest event first. One row per (webhook, event); retries update the row and GET .../deliveries/{delivery_id}/attempts lists its most recent attempts. Rows are retained like events (the plan's event retention, at least the 24-hour retry window). Pass next_cursor back as before for the next page.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listWebhookDeliveries

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
before	query	optional	next_cursor of the previous deliveries page.
limit	query	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks/RESOURCE_ID/deliveries'

Responses

Status	Meaning	Body and headers
200	One page of deliveries.	WebhookDeliveryList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/webhooks/{id}/deliveries/{delivery_id}/attempts¶

List Webhook Delivery Attempts

One delivery's attempts, newest first, the most recent 20, kept with the delivery row and for as long. Each has its attempt number, when it finished, the receiver's HTTP status (null when none answered), the error class (null on success) and its duration. Response bodies and headers are never kept. A delivery recorded before attempts were kept lists none.

A delivery that is not this webhook's, or a webhook of another project, is not_found.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listWebhookDeliveryAttempts

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
delivery_id	path	required	The id of one of the webhook's deliveries.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks/RESOURCE_ID/deliveries/DELIVERY_ID/attempts'

Responses

Status	Meaning	Body and headers
200	The delivery's kept attempts.	WebhookDeliveryAttemptList (application/json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

CAP alert triggers

GET/api/triggers¶

List Triggers

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.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listTriggers

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/triggers'

Responses

Status	Meaning	Body and headers
200	The project's triggers.	TriggerList (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/triggers¶

Create Trigger

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. A project has at most 20 triggers (trigger_limit_reached). Appends trigger.created.

An exact retry with the same Idempotency-Key returns this same answer, password included, for twenty-four hours.

Authentication: projectBearer OR dashboardSession
Request body: TriggerWrite
Operation ID: createTrigger

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
label (required, string)	minLength: 1 maxLength: 80
target (required, TriggerTarget)	Exactly one of tag and screen_ids.
default_for_seconds (optional, integer)	How long an alert without <expires> holds the screens. Defaults to 3600. minimum: 60 maximum: 604800

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/triggers'

Responses

Status	Meaning	Body and headers
201	Created, with its url, username and password.	TriggerWithPassword (application/json); headers: ETag, Cache-Control
400	invalid_request, including a malformed tag or both tag and screen_ids.	Problem (application/problem+json)
409	trigger_limit_reached or idempotency_mismatch.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/triggers/{id}¶

Get Trigger

One trigger with its latest alert. An alert past its until reads as ended with ended_reason expired.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getTrigger

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/triggers/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	One trigger.	Trigger (application/json); headers: ETag, Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/triggers/{id}¶

Delete Trigger

Deletes the trigger. Its URL stops working at once, and its alert playlist and stills are deleted. A trigger showing an alert, or still clearing one, is refused resource_conflict; clear it first. Appends trigger.deleted. If-Match guards the revision.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: deleteTrigger

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/triggers/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
204	Deleted.	no body
409	resource_conflict — the trigger is showing an alert.	Problem (application/problem+json)
412	revision_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/triggers/{id}/rotate-secret¶

Rotate Trigger Secret

Replaces the trigger's password and returns the new one, once. The old password stops working at once; update the sending system. Appends trigger.updated with details.rotated true. If-Match guards the revision.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: rotateTriggerSecret

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/triggers/RESOURCE_ID/rotate-secret'

Responses

Status	Meaning	Body and headers
200	The trigger with its new password.	TriggerWithPassword (application/json); headers: ETag, Cache-Control
412	revision_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/triggers/{id}/test¶

Test Trigger

Shows a one-minute Exercise alert (a blue card with a yellow EXERCISE banner) on the trigger's screens, exactly as a received alert would, so the targeting and the screens can be checked without the sending system. Refused resource_conflict while the trigger shows an alert, so a test never replaces a real one.

An exact retry with the same Idempotency-Key answers outcome duplicate.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: testTrigger

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/triggers/RESOURCE_ID/test'

Responses

Status	Meaning	Body and headers
200	What the test alert did.	TriggerReceipt (application/json)
409	resource_conflict — the trigger is showing an alert.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/triggers/{id}/clear¶

Clear Trigger

Ends the trigger's alert (ended_reason cleared) and clears the takeovers it set. A screen another takeover has replaced since is left alone. A trigger without an active alert answers unchanged. Appends trigger.alert_received with outcome ended.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: clearTrigger

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/triggers/RESOURCE_ID/clear'

Responses

Status	Meaning	Body and headers
200	The trigger. alert.screens.pending is true while the takeovers are being cleared.	Trigger (application/json); headers: ETag
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/triggers/{id}/cap¶

Receive Trigger CAP

The URL an emergency notification system posts one CAP 1.2 alert to (any XML content type, at most 256 KiB). It authenticates with the trigger's own HTTP Basic credentials: the username is the trigger id, the password the one create or rotate returned.

A message with status Actual or Exercise and msgType Alert shows a full-screen card (headline, event, description, instruction and sender, red for Extreme, Severe or no severity, amber for Moderate, blue for Minor; Exercise adds a yellow EXERCISE banner) on every target screen with a default playlist, until <expires>, else for default_for_seconds, at most 7 days.

An Update that references the shown alert redraws it in place and moves the takeovers when <expires> changed. A Cancel that references it, or any message with responseType AllClear, ends it and clears the takeovers it set. A trigger shows one alert: a new Alert replaces the shown one.

Test, System and Draft messages, Ack and Error, an alert already expired, and a Cancel of an alert not shown are ignored; the same sender and identifier twice is a duplicate. The answer is a receipt naming the outcome; the screens are written right after it (alert.screens.pending).

The takeovers bypass the screen-control rate limits and are never metered or refused for balance. Appends trigger.alert_received.

Authentication: triggerBasic
Request body: string
Operation ID: receiveTriggerCAP

Parameters

Name	Send in	Required?	Description
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Content-Type: application/xml' --data-binary '@request.bin' 'https://api.screenrig.ai/api/triggers/RESOURCE_ID/cap'

Responses

Status	Meaning	Body and headers
200	What the message did.	TriggerReceipt (application/json); headers: RateLimit-Policy, RateLimit, Cache-Control
400	invalid_request — the body is not a usable CAP 1.2 alert, or is larger than 256 KiB.	Problem (application/problem+json)
401	unauthorized — missing or wrong credentials, or an unknown trigger. WWW-Authenticate names the Basic realm.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Playback aggregates

GET/api/playback¶

List Playback Aggregates

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-project (30 per minute) and playback-export-ip (60 per minute) budgets.

Either form is one metered API request. Responses carry Vary Accept.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listPlaybackAggregates

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
screen_id	query	optional
media_id	query	optional
day	query	optional	UTC calendar day of the aggregate.
day_from	query	optional	First UTC day, inclusive. Excludes day. With day_to spans at most 366 days. CSV defaults it to 30 days before day_to.
day_to	query	optional	Last UTC day, inclusive. Excludes day. CSV defaults it to today (UTC).
format	query	optional	json (default) or csv. Omitted, an Accept header naming text/csv but not application/json selects csv.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/playback'

Responses

Status	Meaning	Body and headers
200	Daily playback aggregates for the calling project, images and videos alike. One row per screen, media, and UTC day. Newest days first. Identifiers filter the caller's own rows and are never a cross-project lookup.	PlaybackAggregateList (application/json), PlaybackAggregateCsv (text/csv); headers: Vary, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/playback/plays¶

List Playback Plays

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-project (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).

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listPlaybackPlays

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
from	query	optional	Inclusive lower bound on received_at. Defaults to 24 hours before to.
to	query	optional	Exclusive upper bound on received_at. Defaults to now. to - from is at most 31 days.
screen_id	query	optional
media_id	query	optional
playlist_id	query	optional	Only plays shown from this playlist.
tag	query	optional	A screen tag the screen carried when the play was received.
cursor	query	optional	next_cursor of the previous page, with the same filters. Opaque.
order	query	optional	asc pages oldest first with cursor; desc pages newest first with before. before implies desc; order=asc with before is refused.
before	query	optional	Pages newest first, strictly older than this position: the next_cursor of a newest-first page, with the same filters. Opaque.
limit	query	optional	JSON page size. Refused with CSV.
format	query	optional	json (default) or csv. Omitted, an Accept header naming text/csv but not application/json selects csv.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/playback/plays'

Responses

Status	Meaning	Body and headers
200	A page of plays, or the CSV stream.	PlaybackPlayList (application/json), PlaybackPlayCsv (text/csv); headers: Cache-Control, Vary, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/playback/totals¶

Get Playback Totals

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.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getPlaybackTotals

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
by	query	optional	day: plays per day; screen, media: the busiest keys; screen_day: the day series of the top screens.
day_from	query	optional	First UTC day, inclusive. Defaults to 29 days before day_to. A day series spans at most 366 days (92 when narrowed to a screen or media), a ranking at most 92.
day_to	query	optional	Last UTC day, inclusive. Defaults to today (UTC).
screen_id	query	optional
media_id	query	optional
top	query	optional	How many screens or media a ranking returns (at most 10 for by=screen_day). Refused with by=day.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/playback/totals'

Responses

Status	Meaning	Body and headers
200	Totals of the requested grouping.	PlaybackTotals (application/json); headers: Cache-Control
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Feedback: bugs and feature requests

GET/api/feedback/bugs¶

List Bug Reports

Returns the calling project's own bug reports, newest first, up to one hundred. Another project's submissions are never returned and are not addressable by identifier. There is no pagination cursor in v1.

Authentication: projectBearer
Request body: none
Operation ID: listBugReports

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/feedback/bugs'

Responses

Status	Meaning	Body and headers
200	Bug reports owned by the calling project.	FeedbackList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/feedback/bugs¶

Report Bug

Records one immutable bug report against the calling project. A submission cannot be updated or deleted; a correction is a new submission. An exact retry carrying the same Idempotency-Key returns the original submission for twenty-four hours instead of creating a duplicate, and a different body under that key returns idempotency_mismatch.

Every submission is screened before it is stored. A body under 12 characters or 3 words returns submission_too_short; text that describes no problem or request (random characters, keyboard mash) returns submission_unclear; spam, link-heavy text, prompt injection and malicious text return submission_rejected.

A refused submission is not stored, its problem detail never repeats the submitted text, and an exact retry under the same Idempotency-Key returns the same refusal.

Never place credentials, cookies, Authorization headers, completion nonces, signed URLs, or object keys in title, body, or context; credential-shaped text (ScreenRig tokens, JWTs, bearer tokens, cloud and API keys, private keys) is replaced with [redacted] before the submission is stored, and the response carries the redacted text.

When the screening model is briefly unavailable the submission is accepted and held for a background re-screen; after a few such acceptances in an hour the project gets submission_screening_unavailable (500, Retry-After) and retries the same request later.

Authentication: projectBearer
Request body: FeedbackWrite
Operation ID: reportBug

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
Idempotency-Key	header	required

Request body fields

Field	Description
title (required, string)	Single-line summary. Leading and trailing whitespace is trimmed, and control characters are rejected. minLength: 1 maxLength: 120
body (required, string)	Full description. Line feed and tab are the only accepted control characters. minLength: 1 maxLength: 4000
context (optional, FeedbackContext)	Closed diagnostic envelope. Every member is an optional constrained scalar, nesting is structurally impossible, and an unknown member is rejected with invalid_request. The shape exists so a client cannot persist argument values, credentials, or free-form environment data through it.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/feedback/bugs'

Responses

Status	Meaning	Body and headers
201	Stored bug report. An exact idempotent retry returns this same submission.	FeedbackSubmission (application/json); headers: RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
422	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/feedback/features¶

List Feature Requests

Returns the calling project's own feature requests, newest first, up to one hundred. Another project's submissions are never returned and are not addressable by identifier. There is no pagination cursor in v1.

Authentication: projectBearer
Request body: none
Operation ID: listFeatureRequests

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/feedback/features'

Responses

Status	Meaning	Body and headers
200	Feature requests owned by the calling project.	FeedbackList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/feedback/features¶

Request Feature

Records one immutable feature request against the calling project. A submission cannot be updated or deleted; a correction is a new submission. An exact retry carrying the same Idempotency-Key returns the original submission for twenty-four hours instead of creating a duplicate, and a different body under that key returns idempotency_mismatch.

A refused submission is not stored, its problem detail never repeats the submitted text, and an exact retry under the same Idempotency-Key returns the same refusal.

Authentication: projectBearer
Request body: FeedbackWrite
Operation ID: requestFeature

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
Idempotency-Key	header	required

Request body fields

Field	Description
title (required, string)	Single-line summary. Leading and trailing whitespace is trimmed, and control characters are rejected. minLength: 1 maxLength: 120
body (required, string)	Full description. Line feed and tab are the only accepted control characters. minLength: 1 maxLength: 4000
context (optional, FeedbackContext)	Closed diagnostic envelope. Every member is an optional constrained scalar, nesting is structurally impossible, and an unknown member is rejected with invalid_request. The shape exists so a client cannot persist argument values, credentials, or free-form environment data through it.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/feedback/features'

Responses

Status	Meaning	Body and headers
201	Stored feature request. An exact idempotent retry returns this same submission.	FeedbackSubmission (application/json); headers: RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
422	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Support conversations

GET/api/support/status¶

Support Status

Availability and hours for any active project. chat_allowed is true for every active project, including Standard.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: supportStatus

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/support/status'

Responses

Status	Meaning	Body and headers
200	Support result.	SupportStatus (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/support/conversations¶

List Support Conversations

Project conversations, newest first, at most 100. Staff unread counts are per authenticated person or agent.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listSupportConversations

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
before	query	optional	Conversation ID from the preceding page's next cursor.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/support/conversations'

Responses

Status	Meaning	Body and headers
200	Support result.	SupportConversationList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/support/conversations¶

Create Support Conversation

Available on every plan. Screened before storage or Slack. An opening message under 8 characters or 3 words returns submission_too_short; one that is not a question or problem returns submission_unclear; spam, link-heavy text, prompt injection and unsafe text return submission_rejected.

Rejected text is not retained or sent to Luna, and the problem detail never repeats it. Credential-shaped text other than ScreenRig credentials (bearer tokens, cloud and API keys, private keys) is replaced with [redacted] before storage; ScreenRig credential material returns invalid_request. A new conversation starts one Slack thread; follow-ups stay in it.

Requests with the same key replay for 24 hours, a refusal included.

Authentication: projectBearer OR dashboardSession
Request body: SupportWrite
Operation ID: createSupportConversation

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
Idempotency-Key	header	required

Request body fields

Field	Description
body (required, string)	minLength: 1 maxLength: 4000
human_requested (optional, boolean)	Pause Luna and wait for a human for this conversation. default: false

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/support/conversations'

Responses

Status	Meaning	Body and headers
201	Support result.	SupportSubmission (application/json)
422	The message was refused by screening: submission_too_short or submission_unclear (the opening message only) or submission_rejected. The detail never repeats the text.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/support/conversations/{id}/messages¶

List Support Messages

Messages in project conversation, ascending sequence, at most 100. Continue after the last message sequence for older conversation pagination. Reading does not acknowledge staff unread state.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listSupportMessages

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
after	query	optional	Project support message sequence; resumes strictly after this position.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/support/conversations/RESOURCE_ID/messages'

Responses

Status	Meaning	Body and headers
200	Support result.	SupportMessageList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/support/conversations/{id}/messages¶

Reply Support Conversation

Adds a customer message to an open conversation. A follow-up has no minimum length and is never refused as unclear on its own ("thanks", "yes"); it is screened for safety, prompt injection and link spam, refused with submission_rejected, and credential-shaped text is handled as for a new conversation.

Rejected text is not retained, and a refusal replays under the same key for 24 hours.

Authentication: projectBearer OR dashboardSession
Request body: SupportWrite
Operation ID: replySupportConversation

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required
Idempotency-Key	header	required

Request body fields

Field	Description
body (required, string)	minLength: 1 maxLength: 4000
human_requested (optional, boolean)	Pause Luna and wait for a human for this conversation. default: false

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/support/conversations/RESOURCE_ID/messages'

Responses

Status	Meaning	Body and headers
201	Support result.	SupportSubmission (application/json)
422	The message was refused by screening: submission_too_short or submission_unclear (the opening message only) or submission_rejected. The detail never repeats the text.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PUT/api/support/conversations/{id}/read¶

Read Support Conversation

Monotonically acknowledge messages through sequence for this reader. Cannot acknowledge beyond the conversation last_sequence.

Authentication: projectBearer OR dashboardSession
Request body: SupportRead
Operation ID: readSupportConversation

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request body fields

Field	Description
sequence (required, integer)	minimum: 0

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/support/conversations/RESOURCE_ID/read'

Responses

Status	Meaning	Body and headers
200	Support result.	SupportRead (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/support/conversations/{id}/close¶

Close Support Conversation

End this project conversation and cancel pending AI replies. Repeatable; preserves history. Staff can reopen it in Slack.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: closeSupportConversation

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/support/conversations/RESOURCE_ID/close'

Responses

Status	Meaning	Body and headers
200	Closed conversation.	SupportConversation (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/stream/support¶

Stream Support Messages

Project support messages on every plan as resumable SSE. event is support.message; id is the project support sequence, data is SupportMessage. after takes precedence over Last-Event-ID. Cursor 0 replays history. Staff, customer and AI messages are distinguished by role. Streams revalidate credentials and active project access.

No screenshot or credential data is sent.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: streamSupportMessages

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
after	query	optional	Project support message sequence; resumes strictly after this position.
Last-Event-ID	header	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/stream/support'

Responses

Status	Meaning	Body and headers
200	Support message SSE.	string (text/event-stream)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Website demo requests and bookings

POST/website/demo-requests¶

Submit Website Demo Request

Same-origin anonymous website intake. Saves the request and independent delivery jobs before classification. Idempotency-Key is an independently random private retry UUID, retained only in browser memory. It is not the public flow_id. Matching retries set the same HttpOnly screenrig_demo cookie and return the saved request without another submission.

Requests and responses are excluded from payload logging. Country does not select a timezone. No project or dashboard login is created.

Authentication: none
Request body: DemoRequestInput
Operation ID: submitWebsiteDemoRequest

Parameters

Name	Send in	Required?	Description
Origin	header	required	Same-origin browser request; configured stage origin is accepted on stage.
Idempotency-Key	header	required
f	query	optional	Nonsecret funnel attempt ID, identical to body flow_id.
src	query	optional	Allowlisted source, identical to body source.

Request body fields

Field	Description
email (required, string)	maxLength: 254 format: "email"
country (required, string)	ISO 3166-1 country code; retained separately from timezone. pattern: "^[A-Z]{2}$"
screen_range (required, string)	Allowed: "1_10", "11_100", "101_500", "501_plus", "unknown"
organization (required, string)	Allowed: "small_mid", "large_corporation", "agency_network"
budget (required, string)	Self-reported annual signage budget in USD. Allowed: "under_2995", "2995_19994", "19995_plus", "unknown"
timezone (required, string)	IANA timezone, or empty when browser detection is unavailable; scheduling requires explicit timezone. maxLength: 100
source (required, DemoSource)	Allowed: "home_hero", "home_paid_plans", "pricing_premium", "pricing_enterprise", "direct"
flow_id (required, string)	Random nonsecret analytics attempt ID, never authorization. pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie-jar cookies.txt --header 'Origin: https://screenrig.ai' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/website/demo-requests'

Responses

Status	Meaning	Body and headers
201	Request durably saved. Sets private demo session cookie.	DemoResult (application/json)
200	Matching idempotent replay of the saved request.	DemoResult (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/website/demo-request¶

Get Website Demo Request

Cookie-bound saved request. A request ID or public flow ID does not grant access. No-store.

Authentication: demoSession
Request body: none
Operation ID: getWebsiteDemoRequest

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/website/demo-request'

Responses

Status	Meaning	Body and headers
200	Saved demo request and booking state.	DemoResult (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/website/demo-calendar¶

Get Website Demo Calendar

Private calendar download for this browser's confirmed booking. Rechecks the saved event; no request ID or public flow ID grants access. No-store.

Authentication: demoSession
Request body: none
Operation ID: getWebsiteDemoCalendar

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/website/demo-calendar'

Responses

Status	Meaning	Body and headers
200	Importable calendar event with stable identity and confirmed times.	string (text/calendar)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/website/demo-slots¶

Get Website Demo Slots

Up to four real available 30-minute slots, varied across dates and times when possible, in the visitor's editable IANA timezone. Private slot IDs are returned in the JSON body and never sent in URL queries. Unconfigured calendar or no reasonable timezone overlap returns an empty list.

Authentication: demoSession
Request body: none
Operation ID: getWebsiteDemoSlots

Parameters

Name	Send in	Required?	Description
timezone	query	required
refresh	query	optional	Offer alternatives to the previous cookie-bound batch.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/website/demo-slots?timezone=TIMEZONE'

Responses

Status	Meaning	Body and headers
200	Real available slots or an empty list.	DemoSlots (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/website/demo-bookings¶

Book Website Demo

Rechecks a cookie-bound slot, atomically reserves host buffer cells and creates a stable event in the configured local or Google calendar. Confirmation requires the real event and saved booking. Ambiguous provider failures remain pending for durable reconciliation, without a second event or false booked page.

Authentication: demoSession
Request body: object
Operation ID: bookWebsiteDemo

Parameters

Name	Send in	Required?	Description
Origin	header	required	Same-origin browser request; configured stage origin is accepted on stage.
f	query	optional	Nonsecret funnel attempt ID, identical to the saved flow_id.
src	query	optional	Saved allowlisted source.

Request body fields

Field	Description
slot_id (required, string)	Empty only for replay of an already confirmed cookie-bound booking. pattern: "^([A-Za-z0-9_-]{20,128})?$"
timezone (required, string)	maxLength: 100

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Origin: https://screenrig.ai' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/website/demo-bookings'

Responses

Status	Meaning	Body and headers
201	Calendar event and booking confirmed and saved.	DemoResult (application/json)
200	Already confirmed booking replay.	DemoResult (application/json)
202	Booking pending provider reconciliation; excluded from confirmed booking analytics.	DemoResult (application/json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/website/demo-review¶

Request Website Demo Review

Flags the existing on-demand request for team review without another questionnaire. Late classifier replies cannot reverse this choice.

Authentication: demoSession
Request body: object
Operation ID: requestWebsiteDemoReview

Parameters

Name	Send in	Required?	Description
Origin	header	required	Same-origin browser request; configured stage origin is accepted on stage.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Origin: https://screenrig.ai' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/website/demo-review'

Responses

Status	Meaning	Body and headers
200	Current saved request with review requested.	DemoResult (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/website/demo-session¶

Exchange Website Demo Invitation

Exchanges an emailed seven-day booking invitation for a browser-only HttpOnly demo session. The website removes its invite fragment before any request and sends the token only in this private POST body, never in a URL, redirect, analytics marker or log. Multiple browser sessions may access the same invitation-bound request.

Authentication: none
Request body: object
Operation ID: exchangeWebsiteDemoInvitation

Parameters

Name	Send in	Required?	Description
Origin	header	required	Same-origin browser request; configured stage origin is accepted on stage.

Request body fields

Field	Description
token (required, string)	pattern: "^[A-Za-z0-9_-]{20,128}$"

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie-jar cookies.txt --header 'Origin: https://screenrig.ai' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/website/demo-session'

Responses

Status	Meaning	Body and headers
200	Cookie set and saved demo request returned.	DemoResult (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Homepage browser handoff

POST/api/project/browser-links/claim¶

Claim Browser Link

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.

Authentication: projectBearer
Request body: BrowserLinkClaimRequest
Operation ID: claimBrowserLink

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
Idempotency-Key	header	required

Request body fields

Field	Description
code (required, string)	pattern: "^[23456789ABCDEFGHJKMNPQRSTUVWXYZ]{3}-?[23456789ABCDEFGHJKMNPQRSTUVWXYZ]{3}$"

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/project/browser-links/claim'

Responses

Status	Meaning	Body and headers
201	Exact replay-safe fragment-free browser-link claim.	BrowserLinkClaim (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
403	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
410	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/screen/browser-links¶

Get Browser Link Status

Read-only polling fallback authenticated only by the owning apex browser-link cookie. It returns safe status metadata and the fixed continuation path, never a provisioning URL or token.

Authentication: browserLinkCookie
Request body: none
Operation ID: getBrowserLinkStatus

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/screen/browser-links'

Responses

Status	Meaning	Body and headers
200	Claimed safe status.	BrowserLinkStatus (application/json); headers: Cache-Control, Referrer-Policy
202	Browser link exists but is not claimed yet.	BrowserLinkStatus (application/json); headers: Cache-Control, Referrer-Policy
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
410	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/browser-links¶

Start Browser Link

Strict same-origin no-JavaScript-compatible POST that creates or reuses a 24-hour unclaimed browser-link session. Claiming within that window creates a fresh, independent ten-minute protected provisioning-delivery window; cookie Player pairing lasts 24 hours.

Native pairing is a separate seventy-two-hour unclaimed locator; claimed native delivery remains durable until signed completion or explicit on-player reset. It sets exactly the apex host-only Secure HttpOnly SameSite=Strict Path=/ __Host-screenrig-browser-link cookie with no Domain.

JSON clients receive 201; Accept text/html receives a bodyless 303 to /setup. No insecure localhost fallback exists; development requires the configured HTTPS loopback origin.

Authentication: none
Request body: none
Operation ID: startBrowserLink

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST 'https://screenrig.ai/screen/browser-links'

Responses

Status	Meaning	Body and headers
201	Safe browser-link code/status metadata.	BrowserLinkSession (application/json); headers: Cache-Control, Referrer-Policy, Set-Cookie, RateLimit-Policy, RateLimit
303	No-JavaScript form continuation to the read-only setup page.	no body; headers: Location, Cache-Control, Referrer-Policy, Set-Cookie
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
409	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

GET/stream/browser-links/events¶

Stream Browser Link Events

Owning-cookie-only replayable SSE with Last-Event-ID. Event data contains safe status fields only. It never contains a provisioning URL/token and does not use the project event stream.

Authentication: browserLinkCookie
Request body: none
Operation ID: streamBrowserLinkEvents

Parameters

Name	Send in	Required?	Description
Last-Event-ID	header	optional	Durable cursor used when after is absent.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/stream/browser-links/events'

Responses

Status	Meaning	Body and headers
200	Browser-link issued/claimed status SSE.	string (text/event-stream); headers: Cache-Control, Referrer-Policy, X-Accel-Buffering
400	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
410	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

GET/screen/browser-links/continue¶

Continue Browser Link

Navigation-only owning-cookie-authenticated GET. After claim it returns a bodyless 303 whose sensitive Location is the exact Player /s/<public_id>#provision=<token> URL. The Location is never exposed through CORS, JSON, SSE, polling, logs, traces, metrics, analytics, events, or errors and is idempotent only during the short delivery repair window.

Authentication: browserLinkCookie
Request body: none
Operation ID: continueBrowserLink

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/screen/browser-links/continue'

Responses

Status	Meaning	Body and headers
303	Bodyless redirect to the Player provisioning fragment.	no body; headers: Location, Cache-Control, Referrer-Policy
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
409	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
410	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

GET/setup¶

Get Browser Link Setup Page

Read-only no-JavaScript setup page authenticated by the owning browser-link cookie. It contains code/status instructions only and never a provisioning URL or token.

Authentication: browserLinkCookie
Request body: none
Operation ID: getBrowserLinkSetupPage

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/setup'

Responses

Status	Meaning	Body and headers
200	Safe noindex setup HTML.	string (text/html); headers: Cache-Control, Referrer-Policy, X-Robots-Tag
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
410	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/ABC-234¶

Get Dashed Browser Link Locator

Representative dashed public handoff-code locator. Production accepts every canonical ambiguity-safe XXX-XXX code. The route is side-effect-free and reveals only generic locator instructions. Accept text/markdown negotiates Markdown; Link metadata identifies canonical HTML, the explicit .md alternate, and /llms.txt.

Authentication: none
Request body: none
Operation ID: getDashedBrowserLinkLocator

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET 'https://screenrig.ai/ABC-234'

Responses

Status	Meaning	Body and headers
200	Public locator instructions.	string (text/html), string (text/markdown); headers: Cache-Control, Referrer-Policy, X-Robots-Tag, Vary, Link
404	Generic unknown-or-expired locator response with no existence oracle.	string (text/html), string (text/markdown); headers: Cache-Control, Referrer-Policy, X-Robots-Tag

GET/ABC234¶

Get Undashed Browser Link Locator

Representative undashed public handoff-code locator equivalent to /ABC-234. The route is side-effect-free and reveals only generic locator instructions.

Authentication: none
Request body: none
Operation ID: getUndashedBrowserLinkLocator

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET 'https://screenrig.ai/ABC234'

Responses

Status	Meaning	Body and headers
200	Public locator instructions.	string (text/html), string (text/markdown); headers: Cache-Control, Referrer-Policy, X-Robots-Tag, Vary, Link
404	Generic unknown-or-expired locator response with no existence oracle.	string (text/html), string (text/markdown); headers: Cache-Control, Referrer-Policy, X-Robots-Tag

GET/ABC-234.md¶

Get Dashed Browser Link Locator Markdown

Side-effect-free explicit Markdown alias for the representative dashed public handoff-code locator. Production also accepts the undashed .md form. It returns the same public-only instructions and generic no-oracle 404 policy as the canonical locator.

Authentication: none
Request body: none
Operation ID: getDashedBrowserLinkLocatorMarkdown

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET 'https://screenrig.ai/ABC-234.md'

Responses

Status	Meaning	Body and headers
200	Public locator Markdown instructions.	string (text/markdown); headers: Cache-Control, Referrer-Policy, X-Robots-Tag, Vary, Link
404	Generic unknown-or-expired locator response with no existence oracle.	string (text/markdown); headers: Cache-Control, Referrer-Policy, X-Robots-Tag

GET/ABC-234/index.md¶

Get Dashed Browser Link Locator Index Markdown

Side-effect-free directory-style Markdown alias for the representative dashed public handoff-code locator. Production also accepts the undashed /index.md form. Its canonical and alternate Link metadata point to /ABC-234 and /ABC-234.md.

Authentication: none
Request body: none
Operation ID: getDashedBrowserLinkLocatorIndexMarkdown

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET 'https://screenrig.ai/ABC-234/index.md'

Responses

Status	Meaning	Body and headers
200	Public locator Markdown instructions.	string (text/markdown); headers: Cache-Control, Referrer-Policy, X-Robots-Tag, Vary, Link
404	Generic unknown-or-expired locator response with no existence oracle.	string (text/markdown); headers: Cache-Control, Referrer-Policy, X-Robots-Tag

Player pairing and sessions

POST/screen/pairing-sessions¶

Start Pairing Session

Creates one fleet-global expiring pairing session and sets the temporary HttpOnly Secure SameSite=Strict pairing cookie. An untrusted Origin or cross-site browser request is rejected with forbidden before rate-limit or pairing state is created.

Authentication: none
Request body: none
Operation ID: startPairingSession

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST 'https://play.screenrig.ai/screen/pairing-sessions'

Responses

Status	Meaning	Body and headers
201	Exact six-character pairing code and expiry.	PairingSession (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

GET/stream/pairing-events¶

Stream Pairing Events

Authentication: pairingCookie
Request body: none
Operation ID: streamPairingEvents

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/stream/pairing-events'

Responses

Status	Meaning	Body and headers
200	Authenticated temporary pairing SSE. The terminal pairing.claimed data is PairingClaimedEvent and contains only a non-secret completion nonce.	string (text/event-stream); headers: Cache-Control, X-Accel-Buffering
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/pairing-sessions/complete¶

Complete Pairing Session

Authentication: pairingCookie
Request body: PairingComplete
Operation ID: completePairingSession

Request body fields

Field	Description
completion_nonce (required, string)	pattern: "^[A-Za-z0-9_-]{43}$"

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/pairing-sessions/complete'

Responses

Status	Meaning	Body and headers
200	Paired-device cookie issued; the Player next creates the ordinary paired runtime session.	PairingCompletion (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
404	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/sessions¶

Create Anonymous Runtime Session

Authentication: none
Request body: RuntimeSessionRequest
Operation ID: createAnonymousRuntimeSession

Request body fields

Field

Description

public_id (required, string)

playback (optional, PlaybackHandshake)

Optional playback handshake a Player declares at mint. It is a hint that selects behavior, never authorization: unknown members and entries of the wrong type are ignored, and a value that is not an object negotiates nothing. The mint response echoes the supported intersection as PlaybackGrant. adslot-v1 is granted only to paired sessions.

player (optional, PlayerIdentity)

Player self-identification, sent only on the three mint routes (docs/player-compatibility.md §3.1). It is a hint and never authorization, and it is not covered by the native proof. It is read tolerantly: unknown members are ignored, an invalid optional member is dropped on its own, and a player that is not an object or has no valid kind declares nothing.

It is never a 400. A paired mint stores it on the screen for the operator fleet histogram.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/sessions'

Responses

Status	Meaning	Body and headers
201	Read-only runtime session cookie	RuntimeSession (application/json); headers: RateLimit-Policy, RateLimit
404	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/device-sessions¶

Create Device Runtime Session

Authentication: pairedDeviceCookie
Request body: DeviceSessionRequest
Operation ID: createDeviceRuntimeSession

Request body fields

Field

Description

public_id (optional, string)

minLength: 1

playback (optional, PlaybackHandshake)

player (optional, PlayerIdentity)

It is never a 400. A paired mint stores it on the screen for the operator fleet histogram.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/device-sessions'

Responses

Status	Meaning	Body and headers
201	Paired runtime session	RuntimeSession (application/json)
409	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/native/pairing-sessions¶

Start Native Pairing Session

Creates a native-only pairing session from a player Ed25519 public key. Unclaimed native pairing lasts seventy-two hours. A successful claim reserves a screen and stores durable encrypted delivery independently of the locator expiry. It does not bind the public key to a project until signed completion for that exact pairing credential and nonce.

Cookies, query credentials, cross-site origins, and Authorization are rejected. Exact Idempotency-Key replay precedes new abuse admission. The response never sets a cookie. An already-bound or explicitly retired public key returns enrollment_bound.

Authentication: none
Request body: NativePairingStart
Operation ID: startNativePairingSession

Parameters

Name	Send in	Required?	Description
Idempotency-Key	header	required

Request body fields

Field	Description
kid (required, string)	pattern: "^[A-Za-z0-9_-]{43}$"
public_key (required, PlayerPublicKey)
signature (required, string)	minLength: 80 maxLength: 4096
host (optional, RuntimeHostHint)	The optional native host hint on pairing start, pairing completion, and identity session mint. It names a device and is never authorization. It is read tolerantly (docs/player-compatibility.md §1.1.1): unknown members are ignored, a malformed field or capabilities entry is dropped, at most 32 capabilities are kept, and a value that is not an object or a platform outside the pattern drops the whole hint. None of these refuses the request. A Player still sends only the registered platform values and the members below, because a pre-contract backend refuses anything else.
fleet_link (optional, string)	Optional fleet link secret from the Player URL fragment (#fleet=). A valid, enabled link claims this pairing session for its project at once, or recovers the device's earlier screen; the answer's fleet_link reports which. Like host, it is read tolerantly: a malformed or unknown value never refuses the start. pattern: "^srfl_[A-Za-z0-9_-]{43}$"

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/native/pairing-sessions'

Responses

Status	Meaning	Body and headers
201	Native pairing code plus temporary ScreenRig-Pairing credential; no Set-Cookie.	NativePairingSession (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
409	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

GET/stream/native/pairing-events¶

Stream Native Pairing Events

Native-only pairing SSE authenticated by exactly one ScreenRig-Pairing Authorization header. Cookies and query credentials are rejected. The terminal event contains only the non-secret completion nonce.

Authentication: nativePairingAuthorization
Request body: none
Operation ID: streamNativePairingEvents

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --header 'Authorization: ScreenRig-Pairing PAIRING' 'https://play.screenrig.ai/stream/native/pairing-events'

Responses

Status	Meaning	Body and headers
200	Authenticated native pairing SSE whose terminal data is PairingClaimedEvent.	string (text/event-stream); headers: Cache-Control, X-Accel-Buffering
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
404	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/native/pairing-sessions/complete¶

Complete Native Pairing Session

Completes native pairing with a completion nonce and an EdDSA compact JWS (op=pairing.complete) whose request_hash binds the exact pairing credential and completion nonce. No cookie is accepted or set. No ScreenRig-Device credential is issued. The player next mints ScreenRig-Session from a possession proof.

Authentication: nativePairingAuthorization
Request body: NativePairingComplete
Operation ID: completeNativePairingSession

Request body fields

Field	Description
kid (optional, string)	pattern: "^[A-Za-z0-9_-]{43}$"
completion_nonce (required, string)	pattern: "^[A-Za-z0-9_-]{43}$"
public_key (required, PlayerPublicKey)
signature (required, string)	Compact EdDSA JWS with op=pairing.complete and request_hash binding the exact pairing credential and completion nonce. minLength: 80 maxLength: 4096
host (optional, RuntimeHostHint)	The optional native host hint on pairing start, pairing completion, and identity session mint. It names a device and is never authorization. It is read tolerantly (docs/player-compatibility.md §1.1.1): unknown members are ignored, a malformed field or capabilities entry is dropped, at most 32 capabilities are kept, and a value that is not an object or a platform outside the pattern drops the whole hint. None of these refuses the request. A Player still sends only the registered platform values and the members below, because a pre-contract backend refuses anything else.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Authorization: ScreenRig-Pairing PAIRING' --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/native/pairing-sessions/complete'

Responses

Status	Meaning	Body and headers
200	Native pairing completion; no Set-Cookie and no device credential.	NativePairingCompletion (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
404	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
409	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/native/identity/challenges¶

Create Native Identity Challenge

Issues a short-lived nonce bound to one player public-key thumbprint. Cookies, query credentials, and Authorization are rejected.

Authentication: none
Request body: NativeIdentityChallengeRequest
Operation ID: createNativeIdentityChallenge

Request body fields

Field	Description
kid (required, string)	RFC 7638 SHA-256 JWK thumbprint. pattern: "^[A-Za-z0-9_-]{43}$"
public_key (optional, PlayerPublicKey)
op (required, string)	Allowed: "pairing.start", "pairing.complete", "session.mint", "identity.reset"
request_hash (required, string)	pattern: "^[0-9a-f]{64}$"

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/native/identity/challenges'

Responses

Status	Meaning	Body and headers
201	Challenge nonce for an EdDSA compact JWS proof; no Set-Cookie.	NativeIdentityChallenge (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
404	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/native/identity/sessions¶

Create Native Identity Runtime Session

Verifies an EdDSA compact JWS (op=session.mint) against the enrolled public key and returns a signed seven-day ScreenRig-Session. Paired Players renew after one day with jitter through this same signed mint; renewal replaces the credential without closing an existing runtime stream. Renewal metadata is optional to readers and does not require a Player update.

Cookies are neither accepted nor set. Exact Idempotency-Key replay precedes new abuse admission. An archived screen still mints a session so the player can show the archived glass. Session mint requires the exact durable project and screen binding established by signed completion; pending claim offers have no session authority.

Exact replay rechecks that binding and rejects retired identities.

Authentication: none
Request body: NativeIdentitySessionRequest
Operation ID: createNativeIdentityRuntimeSession

Parameters

Name	Send in	Required?	Description
Idempotency-Key	header	required

Request body fields

Field	Description
kid (required, string)	pattern: "^[A-Za-z0-9_-]{43}$"
public_key (required, PlayerPublicKey)
signature (required, string)	Compact EdDSA JWS with op=session.mint. minLength: 80 maxLength: 4096
host (optional, RuntimeHostHint)	The optional native host hint on pairing start, pairing completion, and identity session mint. It names a device and is never authorization. It is read tolerantly (docs/player-compatibility.md §1.1.1): unknown members are ignored, a malformed field or capabilities entry is dropped, at most 32 capabilities are kept, and a value that is not an object or a platform outside the pattern drops the whole hint. None of these refuses the request. A Player still sends only the registered platform values and the members below, because a pre-contract backend refuses anything else.
playback (optional, PlaybackHandshake)	Optional playback handshake a Player declares at mint. It is a hint that selects behavior, never authorization: unknown members and entries of the wrong type are ignored, and a value that is not an object negotiates nothing. The mint response echoes the supported intersection as PlaybackGrant. adslot-v1 is granted only to paired sessions.
player (optional, PlayerIdentity)	Player self-identification, sent only on the three mint routes (docs/player-compatibility.md §3.1). It is a hint and never authorization, and it is not covered by the native proof. It is read tolerantly: unknown members are ignored, an invalid optional member is dropped on its own, and a player that is not an object or has no valid kind declares nothing. It is never a 400. A paired mint stores it on the screen for the operator fleet histogram.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/native/identity/sessions'

Responses

Status	Meaning	Body and headers
201	Paired native runtime session; no Set-Cookie.	NativeRuntimeSession (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
404	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
409	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/native/identity/reset¶

Reset Native Identity

The on-player reset, invoked only by an explicit confirmed operator action on the device. Failed pairing, session minting, or network access never automatically invokes this operation or clears the Player's local key. The endpoint verifies an EdDSA compact JWS (op=identity.reset).

The screen bound to this key is archived with archive_reason device_reset (already archived: unchanged), and the key stays bound to it: a device that still holds the key mints an archived session (dark glass) and resumes on unarchive with no re-pairing, and the key cannot start a new pairing (enrollment_bound).

Pending native claim offers for the key are withdrawn. A key that never bound a screen, or a key already retired by screen recovery, becomes terminal instead: it cannot pair or mint sessions again, and resetting a retired key never touches the screen its successor owns.

If the enrolled project has been deleted, signed reset makes the orphaned key terminal without archiving another screen, so the device can pair anew. After a lost response, the Player keeps its local key and can retry with a new challenge and fresh signed proof.

A network error alone does not confirm a reset or authorize clearing that key (docs/player-compatibility.md §5.1). No project bearer. Cookies are neither accepted nor set.

Authentication: none
Request body: NativeIdentityProof
Operation ID: resetNativeIdentity

Request body fields

Field	Description
kid (required, string)	pattern: "^[A-Za-z0-9_-]{43}$"
public_key (required, PlayerPublicKey)
signature (required, string)	Compact EdDSA JWS. minLength: 80 maxLength: 4096

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/native/identity/reset'

Responses

Status	Meaning	Body and headers
204	Reset recorded: a live-project bound screen archived with the key kept; a deleted-project, unbound, or retired key made terminal; or an unknown key answered as an idempotent no-op that archives nothing. An authenticated retry of any of these also succeeds. No Set-Cookie.	no body; headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
404	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

Runtime manifest, reports, and events

GET/screen/keys¶

Get Runtime Session Keys

The public keys that verify runtime and dashboard session tokens, as a JWKS document (OKP/Ed25519, one entry per key id). It carries public material only and needs no credential. An empty keys array means no session keys are installed. Cache-Control is public, max-age=300, with an ETag for If-None-Match.

Authentication: none
Request body: none
Operation ID: getRuntimeSessionKeys

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET 'https://play.screenrig.ai/screen/keys'

Responses

Status	Meaning	Body and headers
200	Public session verification keys	SessionKeySet (application/json); headers: Cache-Control, ETag
304	Key set unchanged	no body
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/browser-provisioning/exchanges¶

Exchange Browser Provisioning

Browser-only same-origin exchange. Atomically binds the one-time token to exchange_id and sets only the normal host-only HttpOnly Secure SameSite=Strict paired-device cookie. Android and Qt never consume this grant.

Authentication: none
Request body: BrowserProvisioningExchange
Operation ID: exchangeBrowserProvisioning

Request body fields

Field	Description
provisioning_token (required, string)	pattern: "^[A-Za-z0-9_-]{43}$"
exchange_id (required, string)	pattern: "^xchg_[A-Za-z0-9_-]{43}$"

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/browser-provisioning/exchanges'

Responses

Status	Meaning	Body and headers
201	Paired-device cookie issued without a runtime cookie or credential in the body.	BrowserProvisioningCompletion (application/json); headers: Cache-Control, Referrer-Policy, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
404	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
409	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
410	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

GET/screen/chrome¶

Get Runtime Chrome

Stage-chrome for the current runtime session. Not part of the runtime manifest. Auth is the same runtime cookie or ScreenRig-Session as GET /screen/manifest. Cache-Control is private, no-store. banner is always null.

Authentication: runtimeCookie OR nativeSessionAuthorization
Request body: none
Operation ID: getRuntimeChrome

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/chrome'

Responses

Status	Meaning	Body and headers
200	Runtime chrome	RuntimeChrome (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

GET/screen/manifest¶

Get Runtime Manifest

The one runtime manifest route, for every session. schemaVersion is 3. Resolved player manifest; projection is fail-safe, and invalid pages and primitives are omitted and listed in diagnostics.

Adslot pages are included only for a paired session granted adslot-v1; every other session, including an anonymous public-screen viewer, receives house content with no adslot page. The root keys stay camelCase; adslot page keys stay id, type, adslot_id and optional snake_case visibility.

Compatibility rule 4 — 200 with pages [] and non-empty diagnostics is a degraded projection (player keeps last-known-good); 200 with pages [] and no diagnostics is an authored empty assignment (docs/player-compatibility.md §1.4). An archived screen returns problem screen_archived and must not refresh last-known-good.

Authentication: runtimeCookie OR nativeSessionAuthorization
Request body: none
Operation ID: getRuntimeManifest

Parameters

Name	Send in	Required?	Description
stream_transports	query	optional	Comma-separated supported stream transports (hls,udp-mpegts). Omission projects streams to fallback images. Rendering negotiation only, never authorization. Advertise udp-mpegts only when locally enabled.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/manifest'

Responses

Status	Meaning	Body and headers
200	Resolved player manifest.	RuntimeManifest (application/json)
304	Manifest unchanged	no body
409	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

GET/stream/events¶

Stream Runtime Events

Authentication: runtimeCookie OR nativeSessionAuthorization
Request body: none
Operation ID: streamRuntimeEvents

Parameters

Name	Send in	Required?	Description
after	query	optional	A cursor from a previous response: ev1_ for project events (and the event streams). The Player log (source=log) pages with lg1_ or ev1_ cursors by where the server keeps it; treat them as opaque and pass back the one a page returned. A cursor of another kind is refused with invalid_request.
Last-Event-ID	header	optional	Durable cursor used when after is absent.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/stream/events'

Responses

Status

Meaning

Body and headers

200

Screen-scoped durable SSE. The query cursor takes precedence over Last-Event-ID; each event carries an id cursor suitable for reconnect. Served by the stream sidecar from Valkey (stream-valkey/v1); the stream carries no stream.cursor frames, and a cursor advances only with delivered events.

Invalid, future, or pre-retention cursors receive stream.resync_required at the current head and close. screen.toast and screen.screenshot_requested are runtime audience events; scan never delivers either past details.expires_at.

Screenshot image bytes are never on this stream. screen.archived and screen.unarchived are runtime audience events; they do not wipe credentials. screen.deleted is a runtime audience event delivered when signed identity reset tombstones the screen. No runtime event authorizes clearing local identity.

Only successful signed reset initiated by a confirmed local player action permits local identity rotation. project.suspended and project.resumed are runtime audience hints when prepaid remaining hits zero or becomes positive.

The runtime audience is an allowlist (docs/player-compatibility.md §7.1): screen.content_changed, screen.manifest_changed, screen.toast, screen.screenshot_requested, screen.archived, screen.unarchived, screen.deleted, screen.device_credential_revoked, project.suspended, project.resumed, player.reload, which reaches every runtime session, the per-screen commands player.reboot and player.display (docs/player-compatibility.md §6.5), never delivered past details.expires_at, and screen.card_data_changed (resource {type: card_data, key}, details {revision} or {deleted: true}), addressed only to screens whose current content reads that card data or feed key.

Every other type is never published to the stream. Players ignore unknown event types, including the default message type, and unknown field names, and advance the cursor from every id.

The stream opens with its own retry, drawn per connection between 3000 and 15000 ms so that streams dropped together do not reconnect together; a draining host sends each stream its own retry between 1000 and 30000 ms.

The in-band problem frame (event: problem) has no id; its data is {code, detail, action?}, where action is present when the registry defines one, and the stream then closes (payment_required sets retry: 60000). The fleet player.reload control frame has no id and never moves the cursor. No frame carries more than 64 KiB of data.

string (text/event-stream); headers: X-Accel-Buffering

default

Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.

RuntimeProblem (application/problem+json)

POST/screen/reports¶

Create Runtime Report

Authentication: pairedRuntimeCookie OR nativeSessionAuthorization
Request body: inline
Operation ID: createRuntimeReport

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/reports'

Responses

Status

Meaning

Body and headers

202

Accepted after durable persistence. A telemetry batch is accepted or refused as a unit. It returns 202 only after its raw observations are durable and then its stream watermark has moved; it returns stream_id, sequence, accepted (report count), and duplicate.

A batch that changes the latest health or observation state or the page-failure slot, or appends project events, commits its watermark with that state in one screen write, and appends its events in the same transaction.

A batch that changes none of them, such as a steady batch of plays and condition reports, moves only its watermark, held in Valkey for 25 hours; while Valkey is unavailable or out of memory the screen write holds it instead.

A refused batch (conflicting replay, full stream capacity, retired authority) stores nothing, except a new stream that loses the screen's last stream place to a concurrent new stream, which is refused after its raw observations are stored.

A batch that was not acknowledged because of a server error or a lost connection can have stored some of its raw observations; replaying the same bytes stores each missing observation once, never stores one twice, and then acknowledges. A replay of an acknowledged batch returns 202 with duplicate true and changes nothing.

A watermark held in Valkey can be lost or fall behind in a failover, never move ahead, so a sequence past the stream's watermark is accepted as the stream's next without a gap refusal, and a replay whose watermark was lost is accepted again with duplicate false; its plays are still stored once and its Player log records collapse on their identities.

Individual reports retain their existing response.

A runtime condition report (any other report code, such as player.page_skipped) is recorded in the Player log (GET /api/events?source=log), not in the project's events, and is acknowledged when the Player log queue accepts it; it is not on the event stream and not delivered to webhooks. manifest.activated is committed before this response and is idempotent for the current active revision. playback.media_started, legacy playback.video_started, and playback.application_started durably append one authenticated screen observation (GET /api/playback/plays) before this response; reported item, page, and manifest identities do not require current content membership and do not authorize content access.

Daily counts, optional metadata, and project-owned resource last_used_at are updated by recoverable batches and can lag the raw observation.

Ordinary playback-start responses omit optional credit-balance headers. playback.page_failed replaces the screen's latest page-failure slot and appends a project-only durable event in the same transaction without changing screen or manifest revision. manifest.upgrade stores the screen's one latest-wins manifest-upgrade slot behind its revision fences and appends a project-only durable event in the same transaction only when the derived state changes; a stale, superseded, or post-activation pre-activation report is accepted with no change, and no report ever promotes a grant. application.event appends a durable project event before this response.

no body; headers: RateLimit-Policy, RateLimit

default

RuntimeProblem (application/problem+json)

PUT/screen/screenshot¶

Put Runtime Screenshot

Uploads the current pending still WebP for the session screen. Path does not name screen_id; the paired runtime session binds it. Header ScreenRig-Capture-Id must be the current pending capture_id. Content-Type is exactly image/webp. Body is raw WebP, not empty, at most 2097152 bytes.

The server validates RIFF/WEBP magic, decodes one still frame, and stores the uploaded bytes unchanged. Animated WebP is invalid_request. Missing, unknown, expired, or non-current capture_id is resource_conflict. Unpaired sessions are forbidden. Prepaid remaining credit is not a gate and these bytes are not counted in used_bytes.

One slot per screen is replaced. screen.screenshot_ready details name capture_id, bytes, width, height, and sha256; they never include pixels or an object key.

Authentication: pairedRuntimeCookie OR nativeSessionAuthorization
Request body: string
Operation ID: putRuntimeScreenshot

Parameters

Name

Send in

Required?

Description

ScreenRig-Capture-Id

header

required

ScreenRig-Capture-Failure

header

optional

Report unavailable capture with an empty body. Players send unsupported_surface or capture_failed. Any other non-empty value is recorded as capture_failed, never refused (docs/player-compatibility.md §1.1). Only the current pending capture may fail.

No pixels or partial image are stored; screen.screenshot_failed carries this reason and status becomes unavailable.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'ScreenRig-Capture-Id: VALUE' --header 'Content-Type: image/webp' --data-binary '@request.bin' 'https://play.screenrig.ai/screen/screenshot'

Responses

Status	Meaning	Body and headers
204	Still WebP stored as the current slot.	no body; headers: Cache-Control
400	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
409	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/adslots/resolve¶

Resolve Adslots

Resolves up to 16 server-verified page occurrences. A fresh candidate with a possible fill is atomically priced, budget-checked and reserved against the campaign-wide pricing fence. A fresh candidate with no possible fill returns empty without creating a decision or reservation.

No eligible or affordable campaign is a successful empty result with no content and no debit; it is never a payment challenge. Empty results may include a server-clock no-fill hint lasting at most 60 seconds and ending at an earlier known eligibility boundary.

Hints apply to the same screen, manifest, page, slot and eligibility context; they never authorize playback. A lease renewal reuses the same reservation and does not advance rotation, and is denied while the campaign requires price reacceptance.

Authentication: pairedRuntimeCookie OR nativeSessionAuthorization
Request body: RuntimeAdslotResolveRequest
Operation ID: resolveAdslots

Request body fields

Field	Description
manifest_revision (required, string)
candidates (required, array)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/adslots/resolve'

Responses

Status	Meaning	Body and headers
200	Per-candidate filled or empty results in request order.	RuntimeAdslotResolveResponse (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	invalid_request - batch size, duplicate keys, or forecast window is invalid.	RuntimeProblem (application/problem+json)
409	resource_conflict - a candidate was reused with a different request hash.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/adslots/events¶

Report Adslot Events

Authenticated playback evidence. Events dedupe on screen and event ID. A valid completion consumes its held reservation once at the reserved price and fee, credits the seller gross and debits the serving fee in one transaction. A confirmed non-play terminal event releases the hold once.

Completion received after release is unbillable and never debits fresh credits. Completion before start is held pending reconciliation.

Authentication: pairedRuntimeCookie OR nativeSessionAuthorization
Request body: RuntimeAdslotEventBatch
Operation ID: reportAdslotEvents

Request body fields

Field	Description
events (required, array)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/adslots/events'

Responses

Status	Meaning	Body and headers
200	Per-event outcomes.	RuntimeAdslotEventResponse (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

PUT/screen/observation¶

Put Runtime Observation

Reports the playback surface the paired player used for the last resolveLayout. Path does not name screen_id; the paired runtime session binds it. Body is JSON ScreenObservation: observed_at plus exactly one surface.

Numbers are device-independent pixels and the device pixel ratio next to that layout surface, not canvas author size and not encoded screenshot size. They are range-checked only and are never proven hardware or authorization. Last write wins and replaces the whole surfaces array.

An identical surfaces tuple (id, width, height, pixel_ratio, presentation, rotation) does not emit screen.surface_changed; a later observed_at on the same tuple is ignored. Unpaired and anonymous public sessions are forbidden. Native cookies are rejected; browser must not adopt header profiles. Prepaid remaining credit is not a gate.

Observation is absent from GET /api/screens until the first accepted report. ScreenPatch cannot write it. An archived screen answers 409 screen_archived. At most 12 reports per minute per paired session (runtime-observation): a 429 means retry no sooner than Retry-After.

Authentication: pairedRuntimeCookie OR nativeSessionAuthorization
Request body: RuntimeObservationWrite
Operation ID: putRuntimeObservation

Request body fields

Field	Description
observed_at (required, string)	format: "date-time"
surfaces (required, array)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/observation'

Responses

Status	Meaning	Body and headers
204	Observation stored as the current surfaces array.	no body; headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
409	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

PUT/screen/health¶

Put Runtime Health

Reports device health for the paired session's screen. Send one on session start and every fifteen minutes, and one at once when the display connection or power changes.

Every member is optional and the body is read tolerantly (docs/player-compatibility.md §1.1): unknown members are ignored, a value out of range is dropped, and an unknown display.power or network.kind reads as unknown; only a member of the wrong JSON type is 400 (a number beyond float64 range is out of range: that member is dropped).

The stored value is the sanitized ScreenHealth plus server reported_at, replacing the previous report. At most one report per screen per minute (runtime-health): a 429 means drop this report and send the next one on schedule, never retry sooner than Retry-After (at least 1 second).

A 400 or a server error does not spend the minute; all sessions of one screen share it. Requires a paired session holding health.write (a paired session minted before health.write existed is admitted by runtime.report); unpaired and anonymous sessions are forbidden and an archived screen answers 409 screen_archived.

A report from a session older than the screen's current content access generation is refused 401. Archive and screen recovery clear Screen.health. A backend without this route answers 404: keep playing and stop reporting health for that session. Transitions append the project-only screen.health_changed (never on GET /screen/events).

Health is never authorization.

Authentication: pairedRuntimeCookie OR nativeSessionAuthorization
Request body: RuntimeHealthWrite
Operation ID: putRuntimeHealth

Request body fields

Field	Description
uptime_s (optional, integer)	Seconds since the device (OS) booted. minimum: 0
app_uptime_s (optional, integer)	Seconds since the Player process started. minimum: 0
memory (optional, object)
cpu (optional, object)
temperature_c (optional, number)	SoC or panel temperature in degrees Celsius. minimum: -50 maximum: 150
display (optional, object)
network (optional, object)
crashes_24h (optional, integer)	Player crashes in the rolling last 24 hours. minimum: 0 maximum: 1000000
renderer_restarts_24h (optional, integer)	Renderer or web-view restarts in the rolling last 24 hours. minimum: 0 maximum: 1000000

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/health'

Responses

Status	Meaning	Body and headers
204	Health report stored.	no body; headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
409	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

PUT/screen/storage¶

Put Runtime Storage

Reports native player storage, the player's storage plan, and transferred-byte accounting. Path does not name screen_id; the paired runtime session binds it. Unpaired and anonymous sessions are forbidden. Native cookies are rejected; browser must not adopt header profiles. Unknown members are ignored (docs/player-compatibility.md §1.1).

The stored value is the sanitized project ScreenStorage plus server received_at, not the raw body. manifest_revision must be the screen's desired or active revision, or the response is 409 resource_conflict and nothing is stored. Excluded page ids must exist in that revision.

An identical fit class does not emit screen.storage_shortfall or screen.storage_shortfall_cleared. Those events are project-only and are not delivered on GET /screen/events. Storage is never authorization or admission. ScreenPatch cannot write it. A report older than 24 hours by received_at is stale to consumers.

Authentication: pairedRuntimeCookie OR nativeSessionAuthorization
Request body: RuntimeStorageWrite
Operation ID: putRuntimeStorage

Request body fields

Field	Description
observed_at (required, string)	format: "date-time"
volume (required, ScreenStorageVolume)
cache (required, ScreenStorageCache)
durability (required, string)	Allowed: "durable", "purgeable"
plan (required, ScreenStoragePlan)
transfer_24h (required, ScreenStorageTransfer)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/storage'

Responses

Status	Meaning	Body and headers
204	Storage report stored.	no body; headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
409	resource_conflict - manifest_revision is not the screen's desired or active revision. The report is not stored.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

PUT/screen/screen-label¶

Put Runtime Screen Label

Renames the screen bound to the paired runtime session. It is the same rename as PATCH /api/screens/{id} name: the server trims screen_label and requires 1 to 120 UTF-8 bytes without control characters, otherwise invalid_request.

The rename records the same screen events, and on an assigned screen it changes the manifest screen_label and emits screen.manifest_changed to the Player. Path and body do not name screen_id; the paired runtime session binds it. No If-Match or Idempotency-Key; last write wins. Auth is the runtime cookie or ScreenRig-Session, as GET /screen/chrome.

Anonymous and unpaired sessions are unauthorized. An archived screen is screen_archived. Prepaid remaining credit is not a gate. A Player that receives 404 treats the route as unsupported and keeps the name locally (docs/player-compatibility.md §2.5).

Authentication: pairedRuntimeCookie OR nativeSessionAuthorization
Request body: RuntimeScreenLabelWrite
Operation ID: putRuntimeScreenLabel

Request body fields

Field	Description
screen_label (required, string)	minLength: 1

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/screen-label'

Responses

Status	Meaning	Body and headers
200	Screen renamed. screen_label is the stored name.	RuntimeScreenLabel (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
409	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/unpair¶

Unpair Runtime

Cookie-only unpair. Archives a cookie-paired screen that has no player public-key enrollment, with archive_reason device_unpair. The device credential stays bound: a browser that still holds it mints an archived session (dark glass), and unarchive resumes it with no re-pairing (docs/player-compatibility.md §5.1).

A screen that is already archived, or already gone, is success. Identity-enrolled screens return screen_archive_required; those players reset only via POST /screen/native/identity/reset. Path and body do not name screen_id; the paired runtime session binds it. No If-Match or Idempotency-Key. Browser 204 expires the runtime, device, and pairing host cookies.

Native identity-bound calls never 204. Anonymous or unpaired sessions are forbidden. Prepaid remaining credit is not a gate.

Authentication: pairedRuntimeCookie OR nativeSessionAuthorization
Request body: none
Operation ID: unpairRuntime

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/unpair'

Responses

Status	Meaning	Body and headers
204	Cookie-paired screen archived with its credential kept. Browser pairing cookies expired.	no body; headers: Cache-Control, RateLimit-Policy, RateLimit
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
409	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/manifests/{manifest_revision}/releases/{release_id}/launch¶

Launch Application Release

Authentication: runtimeCookie OR nativeSessionAuthorization
Request body: none
Operation ID: launchApplicationRelease

Parameters

Name	Send in	Required?	Description
manifest_revision	path	required
release_id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/manifests/MANIFEST_REVISION/releases/RELEASE_ID/launch'

Responses

Status	Meaning	Body and headers
201	Single-use 30-second exact-release-host launch ticket	ReleaseLaunch (application/json); headers: Referrer-Policy, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/manifests/{manifest_revision}/selectors/resolve¶

Resolve all dynamic media selectors for one playlist loop

Uses the authenticated screen's assigned playlist and its manifest revision. Returns a fixed snapshot in filename order; Players retain cursor and shuffle state across loops. Uploads and tag changes never rewrite this manifest. Empty matches are valid.

Selected media are authorized by the screen's runtime grant independently of the immutable manifest definition.

Authentication: runtimeCookie OR nativeSessionAuthorization
Request body: none
Operation ID: resolveRuntimeSelectors

Parameters

Name	Send in	Required?	Description
manifest_revision	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/screen/manifests/MANIFEST_REVISION/selectors/resolve'

Responses

Status	Meaning	Body and headers
200	Resolved loop snapshot, including item metadata and media_end safety deadlines.	RuntimeSelectorSnapshot (application/json)
401	Runtime session invalid or expired	RuntimeProblem (application/problem+json)
403	Runtime capability denied	RuntimeProblem (application/problem+json)
503	Manifest projection pending or selector snapshot degraded; retain the current loop and retry	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

GET/screen/card-data/{key}¶

Get Runtime Card Data

Returns a card data or feed document, the card data or feed key of a card primitive in the screen's current manifest. A key is readable only while a desired, active, or transition-grace grant of the session's screen lists it; knowing a key is never enough.

Feed keys start with feed: and read the system feed namespace (screenrig.weather/v1 and the other feed schemas); every other key reads the card data of the screen's project. The body is the document itself.

ETag is the sha256 of its bytes and If-None-Match answers 304; keep the last good document for offline playback and refetch on screen.card_data_changed for the key. 404 means no document is stored yet; keep the card hidden.

Authentication: runtimeCookie OR nativeSessionAuthorization
Request body: none
Operation ID: getRuntimeCardData

Parameters

Name	Send in	Required?	Description
key	path	required
If-None-Match	header	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/card-data/KEY'

Responses

Status	Meaning	Body and headers
200	The document	object (application/json); headers: ETag
304	Not modified	no body
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

Runtime application K/V

GET/screen/apps/{application_id}/kv¶

List Runtime KV

Returns at most 200 entries in ascending key order and does not page; a namespace with more keys is only partly listed. Lists metadata for an application the screen's current content holds.

Runtime KV is authorized by the Player's runtime session (kv.read, and kv.write for writes) and the screen's current grant, which must hold a ready release of the application; a ScreenRig-Primitive-Capability header is ignored. Uploaded frames never call these routes and must use the validated parent SDK bridge.

Authentication: runtimeCookie OR nativeSessionAuthorization
Request body: none
Operation ID: listRuntimeKV

Parameters

Name	Send in	Required?	Description
application_id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/apps/APPLICATION_ID/kv'

Responses

Status	Meaning	Body and headers
200	Manifest-authorized application KV	RuntimeKVList (application/json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

GET/screen/apps/{application_id}/kv/{key}¶

Get Runtime KV

Authentication: runtimeCookie OR nativeSessionAuthorization
Request body: none
Operation ID: getRuntimeKV

Parameters

Name	Send in	Required?	Description
application_id	path	required
key	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/apps/APPLICATION_ID/kv/KEY'

Responses

Status	Meaning	Body and headers
200	Manifest-authorized application KV value	RuntimeKVEntry (application/json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

PUT/screen/apps/{application_id}/kv/{key}¶

Put Runtime KV

Authentication: pairedRuntimeCookie OR nativeSessionAuthorization
Request body: RuntimeKVWrite
Operation ID: putRuntimeKV

Parameters

Name	Send in	Required?	Description
application_id	path	required
key	path	required
If-Match	header	optional	Optional positive resource revision. Omit to create or overwrite a key; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
value_base64 (required, string)	maxLength: 1398104
content_type (optional, string)	default: "application/octet-stream" minLength: 1 maxLength: 127

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/apps/APPLICATION_ID/kv/KEY'

Responses

Status	Meaning	Body and headers
200	Paired-device KV mutation	RuntimeKVEntry (application/json); headers: RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

DELETE/screen/apps/{application_id}/kv/{key}¶

Delete Runtime KV

Authentication: pairedRuntimeCookie OR nativeSessionAuthorization
Request body: none
Operation ID: deleteRuntimeKV

Parameters

Name	Send in	Required?	Description
application_id	path	required
key	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/apps/APPLICATION_ID/kv/KEY'

Responses

Status	Meaning	Body and headers
204	Paired-device KV deletion	no body; headers: RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

Protected content and release assets

GET/screen/ad-decisions/{decision_id}¶

Get Ad Decision Content

Serves the one private object bound to an issued decision. Authority is the live paired identity plus the decision binding; the buyer project and media ID are resolved server-side, never from the caller, and no object key or signed URL is published. A zero-length probe returns metadata only.

Authentication: runtimeCookie OR nativeSessionAuthorization
Request body: none
Operation ID: getAdDecisionContent

Parameters

Name	Send in	Required?	Description
decision_id	path	required
Range	header	optional	V1 accepts one byte range only.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/ad-decisions/DECISION_ID'

Responses

Status	Meaning	Body and headers
200	Complete decision-bound private media.	no body; headers: Accept-Ranges, Content-Length, ETag
206	One standards-correct byte range.	no body; headers: Accept-Ranges, Content-Range, Content-Length, ETag
404	not_found - unknown decision.	RuntimeProblem (application/problem+json)
410	decision expired or otherwise not servable.	RuntimeProblem (application/problem+json)
416	invalid_range.	RuntimeProblem (application/problem+json); headers: Content-Range, Accept-Ranges
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

HEAD/screen/ad-decisions/{decision_id}¶

Head Ad Decision Content

Identical authority and metadata to the GET with no body.

Authentication: runtimeCookie OR nativeSessionAuthorization
Request body: none
Operation ID: headAdDecisionContent

Parameters

Name	Send in	Required?	Description
decision_id	path	required
Range	header	optional	V1 accepts one byte range only.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request HEAD --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/ad-decisions/DECISION_ID'

Responses

Status	Meaning	Body and headers
200	Metadata only.	no body; headers: Accept-Ranges, Content-Length, ETag
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

GET/media/{media_id}¶

Get Stable Protected Media

Stable immutable media URL shared across playlist revisions. The runtime session identifies the screen and project for authorization and bandwidth accounting. Every request requires membership in that screen's desired, active, or unexpired transition-grace grant in its current content-access generation. IDs alone grant no access.

Browser cookie and native session authentication remain on the trusted Player origin; redirects and public object-storage access are not used.

Authentication: runtimeCookie OR nativeSessionAuthorization
Request body: none
Operation ID: getStableProtectedMedia

Parameters

Name	Send in	Required?	Description
media_id	path	required
Range	header	optional	V1 accepts one byte range only.
Sec-Fetch-Site	header	optional
Sec-Fetch-Mode	header	optional
Sec-Fetch-Dest	header	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/media/MEDIA_ID'

Responses

Status	Meaning	Body and headers
200	Session-authorized complete private media. Browser Fetch Metadata must describe trusted-player same-origin media/image/video use; authenticated native clients may omit it.	no body; headers: Accept-Ranges, Content-Length, ETag, Content-Disposition
206	One standards-correct byte range.	no body; headers: Accept-Ranges, Content-Range, Content-Length, ETag
416	Unsatisfiable, multiple, or malformed range.	RuntimeProblem (application/problem+json); headers: Content-Range, Accept-Ranges
429	Per-client, screen, or project protected-media egress limit exceeded.	RuntimeProblem (application/problem+json); headers: Retry-After
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

HEAD/media/{media_id}¶

Head Stable Protected Media

Session-authorized immutable media metadata with the same grant checks as GET and no response body.

Authentication: runtimeCookie OR nativeSessionAuthorization
Request body: none
Operation ID: headStableProtectedMedia

Parameters

Name	Send in	Required?	Description
media_id	path	required
Range	header	optional	V1 accepts one byte range only.
Sec-Fetch-Site	header	optional
Sec-Fetch-Mode	header	optional
Sec-Fetch-Dest	header	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request HEAD --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/media/MEDIA_ID'

Responses

Status	Meaning	Body and headers
200	Session-authorized complete private media. Browser Fetch Metadata must describe trusted-player same-origin media/image/video use; authenticated native clients may omit it.	no body; headers: Accept-Ranges, Content-Length, ETag, Content-Disposition
206	One standards-correct byte range.	no body; headers: Accept-Ranges, Content-Range, Content-Length, ETag
416	Unsatisfiable, multiple, or malformed range.	RuntimeProblem (application/problem+json); headers: Content-Range, Accept-Ranges
429	Per-client, screen, or project protected-media egress limit exceeded.	RuntimeProblem (application/problem+json); headers: Retry-After
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

GET/media/manifests/{manifest_revision}/{media_id}¶

Get Protected Media

Authentication: runtimeCookie OR nativeSessionAuthorization
Request body: none
Operation ID: getProtectedMedia

Parameters

Name	Send in	Required?	Description
manifest_revision	path	required
media_id	path	required
Range	header	optional	V1 accepts one byte range only.
Sec-Fetch-Site	header	optional
Sec-Fetch-Mode	header	optional
Sec-Fetch-Dest	header	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/media/manifests/MANIFEST_REVISION/MEDIA_ID'

Responses

Status	Meaning	Body and headers
200	Session-authorized complete private media. Browser Fetch Metadata must describe trusted-player same-origin media/image/video use; authenticated native clients may omit it.	no body; headers: Accept-Ranges, Content-Length, ETag, Content-Disposition
206	One standards-correct byte range.	no body; headers: Accept-Ranges, Content-Range, Content-Length, ETag
416	Unsatisfiable, multiple, or malformed range.	RuntimeProblem (application/problem+json); headers: Content-Range, Accept-Ranges
429	Per-client, screen, or project protected-media egress limit exceeded.	RuntimeProblem (application/problem+json); headers: Retry-After
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

GET/screen/manifests/{manifest_revision}/releases/{release_id}/package¶

Get Native Webapp Package

Retrieves the normalized immutable package for one uploaded application release so a paired native player can retain its authorized last-known-good release across process restart and temporary network loss.

The paired-device cookie, exact screen grant, manifest revision, content-access generation, release membership, and ready package metadata are checked on every request. Project tokens, anonymous runtime cookies, release cookies, external iframe primitives, and direct object-storage access never authorize package bytes.

Authentication: pairedDeviceCookie OR nativeSessionAuthorization
Request body: none
Operation ID: getNativeWebappPackage

Parameters

Name	Send in	Required?	Description
manifest_revision	path	required
release_id	path	required
Range	header	optional	V1 accepts one byte range only.
Sec-Fetch-Site	header	optional
Sec-Fetch-Mode	header	optional
Sec-Fetch-Dest	header	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/manifests/MANIFEST_REVISION/releases/RELEASE_ID/package'

Responses

Status	Meaning	Body and headers
200	Complete normalized private package.	no body; headers: Accept-Ranges, Content-Length, Content-Type, Content-Disposition, Cache-Control, ETag, Referrer-Policy, Cross-Origin-Resource-Policy, X-Content-Type-Options, Vary
206	One standards-correct byte range from the same immutable package.	no body; headers: Accept-Ranges, Content-Range, Content-Length, Content-Type, Content-Disposition, Cache-Control, ETag, Referrer-Policy, Cross-Origin-Resource-Policy, X-Content-Type-Options, Vary
416	Unsatisfiable, multiple, or malformed range.	RuntimeProblem (application/problem+json); headers: Content-Range, Accept-Ranges
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

HEAD/screen/manifests/{manifest_revision}/releases/{release_id}/package¶

Head Native Webapp Package

Returns the same authorization and immutable identity headers as GET without package bytes.

Authentication: pairedDeviceCookie OR nativeSessionAuthorization
Request body: none
Operation ID: headNativeWebappPackage

Parameters

Name	Send in	Required?	Description
manifest_revision	path	required
release_id	path	required
Range	header	optional	V1 accepts one byte range only.
Sec-Fetch-Site	header	optional
Sec-Fetch-Mode	header	optional
Sec-Fetch-Dest	header	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request HEAD --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/manifests/MANIFEST_REVISION/releases/RELEASE_ID/package'

Responses

Status	Meaning	Body and headers
200	Authorized normalized package metadata.	no body; headers: Accept-Ranges, Content-Length, Content-Type, Content-Disposition, Cache-Control, ETag, Referrer-Policy, Cross-Origin-Resource-Policy, X-Content-Type-Options, Vary
206	Authorized metadata for one byte range.	no body; headers: Accept-Ranges, Content-Range, Content-Length, Content-Type, Content-Disposition, Cache-Control, ETag, Referrer-Policy, Cross-Origin-Resource-Policy, X-Content-Type-Options, Vary
416	Unsatisfiable, multiple, or malformed range.	no body; headers: Content-Range, Accept-Ranges
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

GET/{asset_path}¶

Consume Launch Ticket Or Get Release Asset

Exact-release-host operation. With a ticket query, atomically consumes the single-use 30-second ticket, binds Host/release/screen/content-generation/manifest/grant, sets only the exact-host release-grant cookie, and redirects to the same path without the ticket. Without a ticket, validates that cookie on every GET/HEAD.

The asset_path parameter is greedy (x-screenrig-greedy-path) and is resolved only beneath the ready release root. Runtime/project/device cookies and project bearer tokens never authorize this operation.

Authentication: releaseLaunchTicket OR releaseGrantCookie
Request body: none
Operation ID: consumeLaunchTicketOrGetReleaseAsset

Parameters

Name	Send in	Required?
asset_path	path	required
Sec-Fetch-Site	header	optional
Sec-Fetch-Mode	header	optional
Sec-Fetch-Dest	header	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://r-{release_host_label}.apps.screenrig.ai/index.html'

Responses

Status	Meaning	Body and headers
200	Exact-host grant-authorized immutable asset.	no body; headers: Referrer-Policy, X-Content-Type-Options, ETag
302	Ticket consumed once; release-grant cookie issued; ticket removed from Location.	no body; headers: Location, Set-Cookie, Cache-Control, Referrer-Policy
403	Wrong Host/release/screen/generation/grant, stale/replayed ticket, invalid cookie, contradictory Fetch Metadata, or disallowed method.	Problem (application/problem+json)
404	Asset absent without exposing release filesystem shape.	Problem (application/problem+json)

People and project dashboard

POST/api/invitations/inspect¶

Inspect Dashboard Invitation

Inspects an invitation without consuming it. Never reports signup or verification state.

Authentication: none
Request body: InvitationInspectRequest
Operation ID: inspectDashboardInvitation

Request body fields

Field	Description
token (required, string)	pattern: "^[A-Za-z0-9_-]{43}$"

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/invitations/inspect'

Responses

Status	Meaning	Body and headers
200	Inspects an invitation without consuming it.	InvitationInspect (application/json); headers: RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit

POST/api/invitations/passkey-options¶

Start Dashboard Invitation Passkey

Starts a five-minute registration ceremony bound to the invitation digest and mode. Link create_login requires a verified __Host-screenrig-signup cookie and uses its name. Email create_login binds the supplied display name; reset binds the target person.

Authentication: none OR invitationSignup
Request body: InvitationPasskeyOptionsRequest
Operation ID: startDashboardInvitationPasskey

Request body fields

Field	Description
token (required, string)	pattern: "^[A-Za-z0-9_-]{43}$"
mode (required, string)	Allowed: "create_login", "reset"
display_name (optional, DashboardDisplayName)	Trimmed printable display name, at most 80 UTF-8 bytes. Rejects controls, URL-looking text, @, www., ://, and credential material. Never authorization. minLength: 1 maxLength: 80

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/invitations/passkey-options'

Responses

Status	Meaning	Body and headers
201	Starts a five-minute registration ceremony bound to the invitation digest and mode.	DashboardPasskeyRegistration (application/json); headers: RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit

POST/api/invitations/email-verifications¶

Verify Dashboard Invitation Email

Starts a browser-bound link signup and revokes earlier signups for this invitation. The verification challenge is bound to this signup. Development auth verifies the signup immediately without mail.

Authentication: none
Request body: InvitationEmailVerificationRequest
Operation ID: verifyDashboardInvitationEmail

Request body fields

Field	Description
token (required, string)	pattern: "^[A-Za-z0-9_-]{43}$"
display_name (required, DashboardDisplayName)	Trimmed printable display name, at most 80 UTF-8 bytes. Rejects controls, URL-looking text, @, www., ://, and credential material. Never authorization. minLength: 1 maxLength: 80
email (required, string)	minLength: 3 maxLength: 254 format: "email"

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/invitations/email-verifications'

Responses

Status	Meaning	Body and headers
202	Starts a browser-bound link signup and revokes earlier signups for this invitation.	InvitationEmailVerificationAccepted (application/json); headers: Set-Cookie, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit

GET/api/invitations/signup¶

Get Dashboard Invitation Signup

Returns the live signup belonging to this browser. A missing, revoked, consumed, or expired signup cookie returns invitation_invalid.

Authentication: invitationSignup
Request body: none
Operation ID: getDashboardInvitationSignup

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/invitations/signup'

Responses

Status	Meaning	Body and headers
200	Returns the live signup belonging to this browser.	InvitationSignup (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/invitations/accept¶

Accept Dashboard Invitation

Accepts an invitation transactionally and mints a fresh person session, deleting the old session when present. Link create_login requires the verified __Host-screenrig-signup cookie for this invitation. signed_in requires a dashboard session and recent sign-in or fresh proof; email delivery requires a matching verified email.

An already-registered create_login address returns resource_conflict. An organization_admin invitation adds the person to the organization's admins and opens no project; it returns organization_admin_limit when the organization already has 20 admins and stays outstanding, and resource_conflict when the organization was deleted.

Authentication: none OR invitationSignup OR dashboardSession
Request body: InvitationAcceptRequest
Operation ID: acceptDashboardInvitation

Request body fields

Field	Description
token (required, string)	pattern: "^[A-Za-z0-9_-]{43}$"
mode (required, string)	Allowed: "create_login", "signed_in", "reset"
display_name (optional, DashboardDisplayName)	Trimmed printable display name, at most 80 UTF-8 bytes. Rejects controls, URL-looking text, @, www., ://, and credential material. Never authorization. minLength: 1 maxLength: 80
credential (optional, InvitationCredential)
proof (optional, DashboardProof)
buyer (optional, InvitationBuyer)
remove_other_passkeys (optional, boolean)	Sign-in reset only (mode reset). Removes the person's passkeys other than the one this reset registers, or every passkey when the reset sets a password, so a lost or stolen device stops signing in. Absent means true; any other invitation refuses it. default: true

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/invitations/accept'

Responses

Status	Meaning	Body and headers
200	Accepts an invitation transactionally and mints a fresh person session, deleting the old session when present.	InvitationAccepted (application/json); headers: Set-Cookie, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit

PUT/api/session/project¶

Switch Dashboard Project

Switches to one of the person’s projects and updates its last-used time. A staff member may also switch to a project they shadow (GET /api/staff/shadows); that session reports shadow true, is read-only, and updates no last-used time. Any other project returns not_found.

Authentication: dashboardSession
Request body: DashboardProjectSwitch
Operation ID: switchDashboardProject

Request body fields

Field	Description
project_id (required, string)	minLength: 1

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/session/project'

Responses

Status	Meaning	Body and headers
200	Switches to one of the person’s projects and updates its last-used time.	DashboardSession (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/members¶

List Dashboard Members

Lists members of the current project without their private email addresses. Every member has equal authority except removal; owner marks the project owner, and viewer_user_id and viewer_is_owner describe the signed-in person.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardMembers

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/members'

Responses

Status	Meaning	Body and headers
200	Lists members of the current project without their private email addresses.	DashboardMemberList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/members/{user_id}¶

Remove Dashboard Member

Removes a member from the current project. The project owner removes any other member; any member removes themselves to leave. The owner is never removed and never leaves (owner_cannot_leave; transfer ownership first). A member removing someone else is refused with owner_required. A person who is not a member, including one already removed, is not_found.

In one transaction the membership ends, that person's outstanding email invitations to the project are revoked, and the project event member.removed is appended (details user_id, removed_by_user_id, left). The person's sessions stop resolving the project on their next request and fall back as they do after a project deletion.

Agent memberships are separate and stay. People only; no bearer route.

Authentication: dashboardSession
Request body: none
Operation ID: removeDashboardMember

Parameters

Name	Send in	Required?	Description
user_id	path	required
project_id	query	required	The project the caller means; a session whose selection has changed is refused with resource_conflict.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/members/USER_ID?project_id=PROJECT_ID'

Responses

Status	Meaning	Body and headers
204	The membership ended.	no body
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/projects/{id}/deletion-preview¶

Preview Dashboard Staff Project Deletion

Shows the current project name and revision plus the existing operator cascade counts, including bound active and archived devices. Deletion requires a separate approved project.delete request; paired devices require include_paired_screens in that exact request.

Authentication: dashboardSession
Request body: none
Operation ID: previewDashboardStaffProjectDeletion

Parameters

Name	Send in	Required?	Description
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/projects/RESOURCE_ID/deletion-preview'

Responses

Status	Meaning	Body and headers
200	Project metadata and cascade counts, without credentials or device keys.	DashboardStaffDeletionPreview (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/organizations/{id}/lifecycle-preview¶

Preview Dashboard Staff Organization Lifecycle

Shows the organization's current name and revision and up to 101 live project IDs. An approved merge binds the complete source project set, with at most 100 projects, and the destination revision. Reseller relationships require a dated end first. Deletion requires no live projects.

Closure removes domain claims and retains the original wallet, recorded obligations and historical readers. A closed organization receives no new grants; a merge grants no membership and transfers no old money or charges.

Authentication: dashboardSession
Request body: none
Operation ID: previewDashboardStaffOrganizationLifecycle

Parameters

Name	Send in	Required?	Description
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/organizations/RESOURCE_ID/lifecycle-preview'

Responses

Status	Meaning	Body and headers
200	Metadata to confirm deletion or a complete atomic merge.	DashboardStaffOrganizationLifecyclePreview (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/staff/actions¶

Prepare Dashboard Staff Action

Stores one normalized change for ten minutes, bound to this staff session. Preparation grants no access. Approve its request_id with a fresh staff_action passkey proof; the approval accepts no replacement change.

Authentication: dashboardSession
Request body: DashboardStaffChange
Operation ID: prepareDashboardStaffAction

Request body fields

Field	Description
action (required, string)	Allowed: "organization.create", "organization.rename", "organization.admins", "organization.domain", "project.rename", "project.move", "project.owner", "person.deactivate", "person.reinstate", "person.free-cap", "person.reset-sign-in", "organization.plan", "project.plan-to-organization", "project.plan", "project.delete", "organization.delete", "organization.merge", "staff.grant", "staff.revoke", "project.write-mode", "project.write-mode-end", "project.write", "project.shadow", "project.unshadow", "project.member", "project.member-remove", "demo.claim", "demo.release", "demo.offer-live", "demo.send-booking-link", "demo.record-outcome"
organization_id (optional, string)
project_id (optional, string)
user_id (optional, string)
name (optional, string)
domain (optional, string)
admin_user_ids (optional, array)
reason (optional, string)	maxLength: 240
free_limit (optional, integer)	minimum: 0 maximum: 10000
plan_id (optional, string)	Allowed: "standard", "premium", "enterprise", "staff", "promo"
revision (optional, integer)	minimum: 1
include_paired_screens (optional, boolean)	default: false
target_organization_id (optional, string)
target_revision (optional, integer)	minimum: 1
project_ids (optional, array)
demo_request_id (optional, string)
demo_version (optional, string)	Exact saved updated_at from the demo read. format: "date-time"
demo_revision (optional, integer)	Exact staff tracking revision from the demo read. minimum: 0
demo_attendance (optional, string)	Allowed: "unrecorded", "attended", "no_show"
demo_outcome (optional, string)	Allowed: "unrecorded", "interested", "converted", "not_fit", "closed"
demo_followup (optional, string)	Allowed: "unrecorded", "pending", "scheduled", "done", "not_needed"
demo_followup_at (optional, string)	format: "date-time"
revoke_passkeys (optional, boolean)	person.reset-sign-in only: also remove every passkey and end every session at once. default: false

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/staff/actions'

Responses

Status	Meaning	Body and headers
201	The exact proposed change and its approval subject.	DashboardStaffActionRequest (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/staff/actions/{id}/approve¶

Approve Dashboard Staff Action

A fresh passkey proof binds to this specific request_id. Current staff and session authority, the change, exact-retry result and permanent audit share one transaction. Development auth accepts a password proof. Completed retries recheck current staff authority before returning their original result.

Authentication: dashboardSession
Request body: object
Operation ID: approveDashboardStaffAction

Parameters

Name	Send in	Required?	Description
id	path	required

Request body fields

Field	Description
proof (required, DashboardProof)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/staff/actions/RESOURCE_ID/approve'

Responses

Status	Meaning	Body and headers
200	The result of the approved change. person.reset-sign-in answers a DashboardStaffSignInReset.	object (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/organizations¶

List Dashboard Staff Organizations

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardStaffOrganizations

Parameters

Name	Send in	Required?	Description
after	query	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/organizations'

Responses

Status	Meaning	Body and headers
200	At most 100 organizations, including empty organizations.	DashboardStaffOrganizationPage (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/organizations/{id}¶

Get Dashboard Staff Organization

Staff-cookie only; the staff flag is reread for each request. One live organization in the shape of an item of GET /api/staff/organizations. An unknown or deleted organization answers 404 not_found.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardStaffOrganization

Parameters

Name	Send in	Required?	Description
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/organizations/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	The organization.	DashboardStaffOrganization (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/organizations/{id}/projects¶

List Dashboard Staff Organization Projects

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardStaffOrganizationProjects

Parameters

Name	Send in	Required?	Description
id	path	required
after	query	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/organizations/RESOURCE_ID/projects'

Responses

Status	Meaning	Body and headers
200	At most 100 live projects with their owners.	OrganizationProjectPage (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/session/staff-write-mode¶

End this session's approved staff write access

Removes the current write lease and records its end. A fresh approval is required to enter write mode again. Uses the dashboard cookie and same-origin mutation guard.

Authentication: dashboardSession
Request body: none
Operation ID: endDashboardStaffWriteMode

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/session/staff-write-mode'

Responses

Status	Meaning	Body and headers
204	Write mode ended.	no body
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/audit¶

List Dashboard Staff Audit

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardStaffAudit

Parameters

Name	Send in	Required?	Description
after	query	optional
project	query	optional
organization	query	optional	Organization ID. Selects changes to the organization (change.organization_id, or change.target_organization_id of a merge into it) and changes to any of its current live projects (change.project_id). Combines with the other scopes.
actor	query	optional
outcome	query	optional	Recorded audit outcome. Admitted writes are unknown; blocked approvals never became changes.
since	query	optional
until	query	optional
exclude_system	query	optional	true leaves out the changes the backend made on its own, recorded with user_id system (an orphaned organization's deletion, change.reason orphaned).

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/audit'

Responses

Status	Meaning	Body and headers
200	At most 100 immutable staff changes, newest first. Pass next_cursor as after for older entries.	DashboardStaffAuditPage (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/operations/live¶

Get Dashboard Staff Operations Live

Staff-cookie only; the staff flag is reread for each request. Live edge rates from the proxy nodes' 10-second counters, over the last 60 seconds of complete buckets, and the last 15 minutes as a series. At most 5 seconds old. Answers 500 dependency_unavailable when the counters cannot be read.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardStaffOperationsLive

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/operations/live'

Responses

Status	Meaning	Body and headers
200	Live edge rates, per lane, status, traffic class, cache outcome, limit and proxy node.	DashboardStaffOperationsLive (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/operations/insights¶

Get Dashboard Staff Operations Insights

Staff-cookie only; the staff flag is reread for each request. Fixed read-only reports over the edge, service log and usage records, at most 60 seconds old. Each section is null when its read failed or its source is missing. Answers not_ready when the report data source is unavailable.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardStaffOperationsInsights

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/operations/insights'

Responses

Status	Meaning	Body and headers
200	Top downloaders, recent errors, latency, top routes and clients, the 24-hour trend, open streams and ingest lag.	DashboardStaffOperationsInsights (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/reports/catalog¶

Get Dashboard Staff Report Catalog

Staff-only catalog of approved operational datasets and query fields. Uses dashboard cookie authentication.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardStaffReportCatalog

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/reports/catalog'

Responses

Status	Meaning	Body and headers
200	Available read-only datasets and enforced limits.	DashboardStaffReportCatalog (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/staff/reports¶

Run Dashboard Staff Report

Staff-only bounded report or Rig-style query. Accepts a closed read-only grammar, not SQL. Requires dashboard cookie authentication and CSRF proof. Personal fields and free text are excluded.

Authentication: dashboardSession
Request body: DashboardStaffReportRequest
Operation ID: runDashboardStaffReport

Request body fields

Field	Description
words (required, array)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/staff/reports'

Responses

Status	Meaning	Body and headers
200	Reports with time window, source, freshness and sampling metadata.	DashboardStaffReportResponse (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/feedback¶

List Dashboard Staff Feedback

Staff-cookie only; the staff flag is reread for each request. Lists bugs and feature requests across projects, newest first by created_at then id. Text is plain text, never trusted HTML. Pass next_cursor as before for older entries.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardStaffFeedback

Parameters

Name	Send in	Required?	Description
before	query	optional	Opaque cursor from the previous page.
kind	query	optional	Only bug reports or only feature requests. Pass the same kind with before for the next page.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/feedback'

Responses

Status	Meaning	Body and headers
200	At most 100 feedback submissions, newest first.	DashboardStaffFeedbackList (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/users¶

List Dashboard Staff Users

Staff only: the session's person must carry the screenrig_staff flag, reread on every request; any other session answers 403 forbidden. Lists every person, newest first, with login email, credential counts, last activity, and their live projects.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardStaffUsers

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/users'

Responses

Status	Meaning	Body and headers
200	Every person with their live projects.	DashboardStaffUserList (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/users/{id}¶

Get Dashboard Staff User

Staff only: the session's person must carry the screenrig_staff flag, reread on every request; any other session answers 403 forbidden. Returns one person with their live projects, credential counts, and live dashboard session count.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardStaffUser

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/users/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	One person.	DashboardStaffUserDetail (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/demos¶

List Dashboard Staff Demos

Staff-only inclusion-only demo queue. Server scopes precede newest-first 50-row cursor pages. Contains contact metadata, never session material or provider links. Does not switch projects.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardStaffDemos

Parameters

Name	Send in	Required?	Description
q	query	optional
route	query	optional
booking	query	optional
attendance	query	optional
outcome	query	optional
followup	query	optional
owner	query	optional	Dashboard staff person ID or mine/unassigned. Slack ownership is separate.
due	query	optional	Pending follow-up or scheduled follow-up whose time has arrived.
after	query	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/demos'

Responses

Status	Meaning	Body and headers
200	Up to 50 matching demo requests and next-page cursor.	DashboardStaffDemoPage (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/demos/{id}¶

Get Dashboard Staff Demo

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardStaffDemo

Parameters

Name	Send in	Required?	Description
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/demos/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Safe contact, routing, booking and staff-tracking metadata; no visitor cookie or provider URLs.	DashboardStaffDemo (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/journeys¶

Get Dashboard Staff Journeys

Read-only creation-cohort evidence for live signage-enabled projects. At most 1000 newest projects are evaluated; total and truncation make bounded coverage explicit. Missing older retained history is unknown. No project switch or write lease.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardStaffJourneys

Parameters

Name	Send in	Required?	Description
since	query	optional	Creation cohort start inclusive. Defaults to seven days ago.
until	query	optional	Creation cohort end exclusive. Defaults to now. Range at most 90 days.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/journeys'

Responses

Status	Meaning	Body and headers
200	Recorded milestones and coverage; transition medians use exact first-recorded adjacent timestamps only. Return timing is latest observed use, not first-return time.	DashboardStaffJourneys (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/activity¶

List Dashboard Staff Activity

Staff-only global customer events in the common logical retention window. No payloads or delivery material. Timestamp and ObjectID keyset pagination is independent of project sequence numbers. Missing attribution or outcomes are explicit.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardStaffActivity

Parameters

Name	Send in	Required?	Description
project	query	optional
organization	query	optional	Organization ID. Selects events of the organization's current live projects; an organization without projects returns an empty page with the usual since, until and retention_seconds. Combines with project.
actor	query	optional	Exact person or agent ID.
outcome	query	optional
type	query	optional	Exact type or dotted family prefix.
severity	query	optional	Minimum severity.
since	query	optional	Inclusive start. Defaults to 24 hours ago; clipped to the common retention floor.
until	query	optional	Exclusive end. Defaults to now.
after	query	optional	next_cursor from the previous page.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/activity'

Responses

Status	Meaning	Body and headers
200	Up to 100 events with coverage and an opaque next cursor.	DashboardStaffActivityPage (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/screens¶

List Dashboard Staff Screens

Staff-only complete fleet directory, newest first in cursor pages. Filters search all matching screens before paging. Reads do not switch the session project or grant a write lease.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardStaffScreens

Parameters

Name	Send in	Required?	Description
q	query	optional	Literal case-insensitive search of label, ID, project, organization and reported Player kind/version.
project	query	optional
organization	query	optional
state	query	optional	Omitted lists active and pairing-pending screens.
presence	query	optional
after	query	optional	The next_cursor from the previous page.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/screens'

Responses

Status	Meaning	Body and headers
200	Up to fifty matching screens and an opaque next-page position.	DashboardStaffScreenPage (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/screens/{id}¶

Get Dashboard Staff Screen

Staff-only read of one screen's fleet metadata, including archived screens. Screen IDs are never authorization; the current staff flag is reread for each request.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardStaffScreen

Parameters

Name	Send in	Required?	Description
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/screens/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Inclusion-only metadata without pairing credentials, recovery offers, addresses or content paths.	DashboardStaffScreen (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/projects¶

List Dashboard Staff Projects

Staff only: the session's person must carry the screenrig_staff flag, reread on every request; any other session answers 403 forbidden. Lists every live project, newest first, with plan, usage, public credit remaining, and members.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardStaffProjects

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/projects'

Responses

Status	Meaning	Body and headers
200	Every live project with its members.	DashboardStaffProjectList (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/projects/{id}¶

Get Dashboard Staff Project

Staff only: the session's person must carry the screenrig_staff flag, reread on every request; any other session answers 403 forbidden. Returns one live project with plan, usage, screen, media, application, and agent counts, and members.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardStaffProject

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/projects/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	One live project.	DashboardStaffProjectDetail (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/members¶

List Dashboard Staff Members

Staff only: the session's person must carry the screenrig_staff flag, reread on every request; any other session answers 403 forbidden. Lists every staff member.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardStaffMembers

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/members'

Responses

Status	Meaning	Body and headers
200	Every staff member.	DashboardStaffMemberList (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/staff/members¶

Grant Dashboard Staff Member

Staff only: the session's person must carry the screenrig_staff flag, reread on every request; any other session answers 403 forbidden. Adds the person whose verified login is email as staff. Proof-protected: the body carries a fresh passkey proof from a staff_grant reauthentication whose subject_id is that email.

A password proof answers 401 reauthentication_required, except on a development server, which registers no passkeys. Granting is idempotent, and it makes a passkey mandatory for the added person (passkey_enrollment_required on their session until they add one). An address with no verified person answers 404 not_found.

Staff removal is operator-only (screenrig-server local staff revoke).

Authentication: dashboardSession
Request body: DashboardStaffGrantRequest
Operation ID: grantDashboardStaffMember

Request body fields

Field	Description
email (required, string)	minLength: 3 maxLength: 254 format: "email"
proof (required, DashboardProof)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/staff/members'

Responses

Status	Meaning	Body and headers
200	The person is staff.	DashboardStaffMember (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/shadows¶

List Dashboard Staff Shadows

Staff only: the session's person must carry the screenrig_staff flag, reread on every request; any other session answers 403 forbidden. Lists the live projects the reader shadows, by name.

PUT /api/session/project switches to one read-only, without a membership: the session reports shadow true, every current-project mutation answers 403 forbidden, and the reader records no project activity, bills nothing, and does not appear among the project's members.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardStaffShadows

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/shadows'

Responses

Status	Meaning	Body and headers
200	The reader's shadowed projects.	DashboardStaffShadowList (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/projects/{id}/support/conversations¶

List Staff Project Support Conversations

Staff-only project communication history, newest first, at most 100. Available across project plans; does not mark customer messages read.

Authentication: dashboardSession
Request body: none
Operation ID: listStaffProjectSupportConversations

Parameters

Name	Send in	Required?	Description
id	path	required
before	query	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/projects/RESOURCE_ID/support/conversations'

Responses

Status	Meaning	Body and headers
200	Project support conversations.	SupportConversationList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/projects/{id}/support/conversations/{conversation}/messages¶

List Staff Project Support Messages

Staff-only messages in this project's conversation, ascending sequence, at most 100. Does not alter customer read receipts.

Authentication: dashboardSession
Request body: none
Operation ID: listStaffProjectSupportMessages

Parameters

Name	Send in	Required?
id	path	required
conversation	path	required
after	query	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/projects/RESOURCE_ID/support/conversations/CONVERSATION/messages'

Responses

Status	Meaning	Body and headers
200	Conversation messages.	SupportMessageList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/support/conversations¶

List Dashboard Staff Support Inbox

Staff-cookie only; the staff flag is reread for each request. Every project's support conversations, most recent activity first (updated_at, then id), 50 per page, with project and organization names, message facts and the reader's own unread count. counts covers the project, organization and q scopes, not the folder. Reading moves no read receipt.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardStaffSupportInbox

Parameters

Name	Send in	Required?	Description
folder	query	optional	open is every conversation not closed; waiting is open and waiting for staff (human_requested).
project	query	optional	Project ID.
organization	query	optional	Organization ID: conversations of its current live projects. Combines with project.
q	query	optional	Literal, case-insensitive search of the subject.
before	query	optional	next from the previous page, a conversation ID.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/support/conversations'

Responses

Status	Meaning	Body and headers
200	One page of conversations and the scope's folder counts.	DashboardStaffSupportInbox (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/support/conversations/{id}¶

Get Dashboard Staff Support Conversation

Staff-cookie only. One conversation of any project, as an inbox row. An unknown conversation answers 404 not_found.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardStaffSupportConversation

Parameters

Name	Send in	Required?	Description
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/support/conversations/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	The conversation.	DashboardStaffSupportConversation (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/staff/support/conversations/{id}/messages¶

List Dashboard Staff Support Messages

Staff-cookie only. The conversation's messages after a sequence, ascending, at most 100, with each message's author_id and origin where they were recorded. Reading moves no read receipt.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardStaffSupportMessages

Parameters

Name	Send in	Required?	Description
id	path	required
after	query	optional	Project support message sequence; resumes strictly after this position.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/support/conversations/RESOURCE_ID/messages'

Responses

Status	Meaning	Body and headers
200	Conversation messages.	DashboardStaffSupportMessageList (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/staff/support/conversations/{id}/messages¶

Reply Dashboard Staff Support Conversation

Staff-cookie only, with the dashboard's same-origin mutation guard. Adds a staff reply under the staff member's first name. The customer sees it as any staff reply (role staff, counted in unread_staff, sent on /stream/support), any pending Luna answer is cancelled, and the reply is posted into the conversation's Slack thread as "Name (dashboard)".

A closed conversation answers 409 support_conversation_closed until it is reopened; a conversation whose project is not active answers 409 resource_conflict. ScreenRig credential material answers invalid_request; other credential-shaped text is replaced with [redacted].

A retry with the same key returns the original message for 24 hours; a different body under that key is idempotency_mismatch. At most 300 replies per staff member per hour.

Authentication: dashboardSession
Request body: DashboardStaffSupportReply
Operation ID: replyDashboardStaffSupportConversation

Parameters

Name	Send in	Required?	Description
id	path	required
Idempotency-Key	header	required

Request body fields

Field	Description
body (required, string)	1 to 4000 characters after surrounding whitespace is trimmed. minLength: 1 maxLength: 4000

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/staff/support/conversations/RESOURCE_ID/messages'

Responses

Status	Meaning	Body and headers
201	The reply and the conversation after it.	DashboardStaffSupportReplyResult (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PUT/api/staff/support/conversations/{id}/read¶

Read Dashboard Staff Support Conversation

Staff-cookie only, with the dashboard's same-origin mutation guard. Monotonically acknowledges the conversation's messages through sequence for this staff member alone; customer receipts never move. Cannot acknowledge beyond last_sequence.

Authentication: dashboardSession
Request body: SupportRead
Operation ID: readDashboardStaffSupportConversation

Parameters

Name	Send in	Required?	Description
id	path	required

Request body fields

Field	Description
sequence (required, integer)	minimum: 0

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/staff/support/conversations/RESOURCE_ID/read'

Responses

Status	Meaning	Body and headers
200	The acknowledged sequence.	SupportRead (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/staff/support/conversations/{id}/state¶

Change Dashboard Staff Support State

Staff-cookie only, with the dashboard's same-origin mutation guard. Takes over (pauses Luna), resolves (closes) or reopens (leaves Luna paused for staff follow-up) a conversation, exactly as the Slack buttons do. Each change adds one lifecycle notice to the customer's history and the Slack thread; a repeat that changes nothing adds none.

A conversation whose project is not active answers 409 resource_conflict.

Authentication: dashboardSession
Request body: DashboardStaffSupportStateChange
Operation ID: changeDashboardStaffSupportState

Parameters

Name	Send in	Required?	Description
id	path	required

Request body fields

Field	Description
action (required, string)	Allowed: "takeover", "resolve", "reopen"

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/staff/support/conversations/RESOURCE_ID/state'

Responses

Status	Meaning	Body and headers
200	The conversation after the change.	DashboardStaffSupportConversation (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PUT/api/staff/projects/{id}/shadow¶

Shadow Dashboard Staff Project

Staff only: the session's person must carry the screenrig_staff flag, reread on every request; any other session answers 403 forbidden. Adds a live project to the reader's shadow list. Idempotent. An unknown or deleted project answers 404 not_found; a list already holding 200 projects answers 409 resource_conflict.

Authentication: dashboardSession
Request body: none
Operation ID: shadowDashboardStaffProject

Parameters

Name	Send in	Required?	Description
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/projects/RESOURCE_ID/shadow'

Responses

Status	Meaning	Body and headers
204	The reader shadows the project.	no body
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/staff/projects/{id}/shadow¶

Unshadow Dashboard Staff Project

Staff only: the session's person must carry the screenrig_staff flag, reread on every request; any other session answers 403 forbidden. Removes a project from the reader's shadow list. Idempotent. A session shadowing it loses the project on its next request.

Authentication: dashboardSession
Request body: none
Operation ID: unshadowDashboardStaffProject

Parameters

Name	Send in	Required?	Description
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/staff/projects/RESOURCE_ID/shadow'

Responses

Status	Meaning	Body and headers
204	The reader no longer shadows the project.	no body
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/me¶

Get Dashboard Me

Returns the signed-in person’s profile and credential counts.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardMe

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/me'

Responses

Status	Meaning	Body and headers
200	Returns the signed-in person’s profile and credential counts..	DashboardMe (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/me¶

Delete Dashboard Me

Tombstones the signed-in person. Proof-protected: the body carries a fresh sign-in proof verified against a reauthentication bound to this session with kind account_delete and subject_id equal to the signed-in person's user id (start it with POST /api/me/reauthentications). Without a current reauthentication the answer is reauthentication_required.

On success the response is 204, the dashboard session cookie is cleared, and the browser's HTTP cache for the dashboard origin is cleared as on sign-out.

Authentication: dashboardSession
Request body: DashboardProofRequest
Operation ID: deleteDashboardMe

Request body fields

Field	Description
proof (required, DashboardProof)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/me'

Responses

Status	Meaning	Body and headers
204	Person deleted, dashboard session cookie cleared and the browser's HTTP cache for this origin cleared.	no body; headers: Clear-Site-Data
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/me/reauthentications¶

Start Dashboard Reauthentication

Starts passkey step-up bound to the session, kind, and subject. A person without a passkey receives resource_conflict and uses a password proof.

Authentication: dashboardSession
Request body: DashboardReauthenticationRequest
Operation ID: startDashboardReauthentication

Request body fields

Field

Description

kind (required, string)

Allowed: "agent_connection_approval", "agent_connection_denial", "agent_disconnect", "email_change", "password_set", "passkey_add", "passkey_delete", "invitation_accept", "account_delete", "staff_grant", "staff_action", "oauth_authorization_approval", "oauth_authorization_denial", "service_client_change", "review_policy_change"

subject_id (optional, string)

The subject the reauthentication binds to. kind account_delete requires the signed-in person's user id. kind staff_grant is staff only and requires the added person's email address. kind staff_action requires the specific prepared request_id. kinds oauth_authorization_approval and oauth_authorization_denial require the authorization id (oaz_...). kind service_client_change requires the service client id, or the project id when creating a client. kind review_policy_change requires the project id (turning Require review for agent changes off). minLength: 1

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/me/reauthentications'

Responses

Status	Meaning	Body and headers
201	Starts passkey step-up bound to the session, kind, and subject.	DashboardReauthentication (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PUT/api/me/password¶

Set Dashboard Password

Sets or replaces the person’s password after fresh proof. The first password requires passkey proof; replacement accepts the current password or a passkey. Revokes other sessions and queues a sign-in changed notice.

Authentication: dashboardSession
Request body: DashboardPasswordSet
Operation ID: setDashboardPassword

Request body fields

Field	Description
password (required, string)	12–128 UTF-8 bytes, without whitespace. Cannot equal the email or display name or a bundled common password. Stored only as an Argon2id hash. minLength: 12 maxLength: 128 pattern: "^\\S+$"
proof (required, DashboardProof)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/me/password'

Responses

Status	Meaning	Body and headers
204	Sets or replaces the person’s password after fresh proof.	no body
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/me/passkeys¶

List Dashboard Passkeys

Lists the person’s passkeys.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardPasskeys

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/me/passkeys'

Responses

Status	Meaning	Body and headers
200	Lists the person’s passkeys..	DashboardPasskeyList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/me/passkeys/options¶

Start Dashboard Passkey Registration

Verifies fresh proof and starts a registration bound to the session and person. Passkeys are disabled under development auth.

Authentication: dashboardSession
Request body: DashboardProofRequest
Operation ID: startDashboardPasskeyRegistration

Request body fields

Field	Description
proof (required, DashboardProof)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/me/passkeys/options'

Responses

Status	Meaning	Body and headers
201	Verifies fresh proof and starts a registration bound to the session and person.	DashboardPasskeyRegistration (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/me/passkeys/complete¶

Complete Dashboard Passkey Registration

Stores the new passkey, revokes the person’s other sessions, and queues a sign-in changed notice.

Authentication: dashboardSession
Request body: DashboardPasskeyComplete
Operation ID: completeDashboardPasskeyRegistration

Request body fields

Field	Description
ceremony_id (required, string)	minLength: 1
credential (required, object)	WebAuthn credential response.
name (optional, string)	default: "Passkey" minLength: 1 maxLength: 60

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/me/passkeys/complete'

Responses

Status	Meaning	Body and headers
201	Stores the new passkey, revokes the person’s other sessions, and queues a sign-in changed notice..	DashboardPasskey (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PATCH/api/me/passkeys/{id}¶

Rename Dashboard Passkey

Renames a passkey owned by the signed-in person.

Authentication: dashboardSession
Request body: DashboardPasskeyPatch
Operation ID: renameDashboardPasskey

Parameters

Name	Send in	Required?	Description
id	path	required

Request body fields

Field	Description
name (required, string)	minLength: 1 maxLength: 60

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PATCH --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/me/passkeys/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Renames a passkey owned by the signed-in person..	DashboardPasskey (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/me/passkeys/{id}¶

Delete Dashboard Passkey

Deletes a passkey after fresh proof and sends a sign-in changed notice. Removing the last sign-in method returns last_credential. A person whose account requires a passkey (every staff member) cannot remove their last passkey; that returns 409 resource_conflict.

Authentication: dashboardSession
Request body: DashboardProofRequest
Operation ID: deleteDashboardPasskey

Parameters

Name	Send in	Required?	Description
id	path	required

Request body fields

Field	Description
proof (required, DashboardProof)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/me/passkeys/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
204	Deletes a passkey after fresh proof and sends a sign-in changed notice.	no body
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/me/email¶

Get Dashboard Email

Returns the person’s verified and pending email state.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardEmail

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/me/email'

Responses

Status	Meaning	Body and headers
200	Returns the person’s verified and pending email state..	DashboardEmail (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/me/email/change¶

Change Dashboard Email

Requests an email change after fresh proof. The verified address stays effective while verification is pending. An address held by another person returns user_email_conflict. The old address receives a warning, not an undo link.

Authentication: dashboardSession
Request body: UserEmailChangeRequest
Operation ID: changeDashboardEmail

Request body fields

Field	Description
email (required, string)	minLength: 3 maxLength: 254 format: "email"
proof (required, DashboardProof)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/me/email/change'

Responses

Status	Meaning	Body and headers
202	Requests an email change after fresh proof.	UserEmailChangeAccepted (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/inventory/{screen_id}¶

Put Dashboard Advertising Inventory

Authentication: dashboardSession
Request body: AdvertisingInventoryWrite
Operation ID: putDashboardAdvertisingInventory

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Required with an identity bearer on every project route. Exactly one project identifier; no implicit current target. With a project bearer, must match its bound project.
screen_id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.

Request body fields

Field	Description
ads_enabled (required, boolean)
site_name (optional, string)	maxLength: 120
city (optional, string)	maxLength: 120
region (optional, string)	maxLength: 120
venue_type (optional, string)	maxLength: 64
audience_tags (optional, array)
placement (optional, string)	maxLength: 120
public_description (optional, string)	maxLength: 500
rate_override_mcr_per_15s (optional, inline)	Null restores inheritance from the project default; it never means zero.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/inventory/SCREEN_ID'

Responses

Status	Meaning	Body and headers
200	Stored inventory.	AdvertisingInventory (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/media/{id}/thumbnail¶

Get Dashboard Media Thumbnail

Returns a small lossy WebP of a ready image owned by the session's project, so the dashboard's grids never decode originals. There is one size: it fits inside 512 x 512 with the aspect kept and is never upscaled, and an animated image shows its first frame.

The first request generates it and stores it beside the original; later requests stream the stored copy, and deleting the media removes it with the original. Another project's identifier, video, audio, and media that is not ready return not_found. Range is not accepted.

The ETag is strong and names the original and the thumbnail generator, so it is the same on every request and host. The response is private, no-cache, and an If-None-Match that matches, checked after the media resolves in the session's project, returns 304 without reading the thumbnail. Completed bytes are recorded as dashboard_media egress.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardMediaThumbnail

Parameters

Name	Send in	Required?	Description
id	path	required
If-None-Match	header	optional	Thumbnail ETag returned by this route.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/media/RESOURCE_ID/thumbnail'

Responses

Status	Meaning	Body and headers
200	The WebP thumbnail.	string (image/webp); headers: Content-Length, Content-Disposition, ETag, Cache-Control, X-Content-Type-Options
304	The thumbnail ETag matches If-None-Match. No body or egress increment is produced.	no body; headers: ETag, Cache-Control
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

HEAD/api/media/{id}/thumbnail¶

Head Dashboard Media Thumbnail

Applies the same ownership, conditional and generation rules as getDashboardMediaThumbnail and returns its headers without the body. No egress is recorded.

Authentication: dashboardSession
Request body: none
Operation ID: headDashboardMediaThumbnail

Parameters

Name	Send in	Required?	Description
id	path	required
If-None-Match	header	optional	Thumbnail ETag returned by this route.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request HEAD --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/media/RESOURCE_ID/thumbnail'

Responses

Status	Meaning	Body and headers
200	Thumbnail metadata with no body.	no body; headers: Content-Length, Content-Disposition, ETag, Cache-Control, X-Content-Type-Options
304	The thumbnail ETag matches If-None-Match. No egress increment is produced.	no body; headers: ETag, Cache-Control
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/email/verify¶

Peek Dashboard Email Verification

Scanner-safe verification peek. It never verifies an address, mutates a user, or signs the visitor in.

Authentication: none
Request body: none
Operation ID: peekDashboardEmailVerification

Parameters

Name	Send in	Required?	Description
token	query	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET 'https://screenrig.ai/api/email/verify?token=TOKEN'

Responses

Status	Meaning	Body and headers
200	Verification status.	EmailVerifyResult (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/email/verify¶

Verify Dashboard Email

Explicit human confirmation consumes one purpose-bound verification challenge. Link-signup challenges require the matching __Host-screenrig-signup cookie; email-change challenges are token-bound. Verification never signs the visitor in.

Authentication: none OR invitationSignup
Request body: EmailVerifyRequest
Operation ID: verifyDashboardEmail

Request body fields

Field	Description
token (required, string)	minLength: 1

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/email/verify'

Responses

Status	Meaning	Body and headers
200	Verification status.	EmailVerifyResult (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/webauthn/assertions¶

Start Dashboard Passkey Assertion

Starts one usernameless WebAuthn assertion ceremony and returns the request options verbatim for navigator.credentials.get. No cookie is required, and no allowCredentials list is published, so the route reveals nothing about which users or credentials exist. The ceremony expires with DashboardCeremonyTTL of five minutes.

When the server runs dashboard development authentication, this route returns passkeys_disabled.

Authentication: none
Request body: none
Operation ID: startDashboardPasskeyAssertion

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST 'https://screenrig.ai/api/webauthn/assertions'

Responses

Status	Meaning	Body and headers
201	WebAuthn request options bound to this ceremony.	DashboardPasskeyAssertion (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
403	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/webauthn/assertions/complete¶

Complete Dashboard Passkey Assertion

Verifies one usernameless assertion and mints the dashboard session cookie for the user the discoverable credential identifies. No cookie authenticates the request. A ceremony that is unknown, elapsed, or already used returns passkey_invalid, and so does an assertion the relying party cannot verify or a sign counter that moves backwards.

The credential identifier is not authorization on its own: the signed assertion is. When the server runs dashboard development authentication, this route returns passkeys_disabled.

Authentication: none
Request body: DashboardPasskeyAssertionComplete
Operation ID: completeDashboardPasskeyAssertion

Request body fields

Field	Description
ceremony_id (required, string)
credential (required, object)	WebAuthn assertion response serialized from the PublicKeyCredential the authenticator returned.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/webauthn/assertions/complete'

Responses

Status	Meaning	Body and headers
200	Session cookie minted from a verified assertion.	DashboardSession (application/json); headers: Cache-Control, Set-Cookie
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
403	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/sessions¶

Create Dashboard Session

Signs in the person identified by verified email and password. Unknown email, no password, and wrong password return the same unauthorized response. Opens the last-used project if still a membership, otherwise the most recent membership, or no project. Development auth uses this same password flow.

Authentication: none
Request body: DashboardPasswordLogin
Operation ID: createDashboardSession

Request body fields

Field	Description
email (required, string)	The person’s verified email address. Unknown email, no password, and wrong password return the same unauthorized response. minLength: 3 maxLength: 254 format: "email"
password (required, string)	minLength: 12 maxLength: 128

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/sessions'

Responses

Status	Meaning	Body and headers
200	Person session minted from verified email and password.	DashboardSession (application/json); headers: Cache-Control, Set-Cookie, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
403	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/session¶

Get Dashboard Session

Returns the current dashboard session. The session cookie and server-side session establish authority; user_id is descriptive. A 401 response means sign-in is required. The dev_auth field is reserved for local development and is false on the hosted service.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardSession

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/session'

Responses

Status	Meaning	Body and headers
200	Current dashboard session.	DashboardSession (application/json); headers: Cache-Control
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/logout¶

Logout Dashboard Session

Deletes the server-side session row and expires the session cookie. It does not delete the user and does not remove any credential. It is intrinsically idempotent and takes no Idempotency-Key.

A successful sign-out also clears the browser's HTTP cache for the dashboard origin, dropping the private, no-cache media, screenshot and ad review bytes the session viewed; a session that only expires leaves them until the browser evicts them.

Authentication: dashboardSession
Request body: none
Operation ID: logoutDashboardSession

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/logout'

Responses

Status	Meaning	Body and headers
204	Session row deleted, session cookie expired and the browser's HTTP cache for this origin cleared.	no body; headers: Cache-Control, Set-Cookie, Clear-Site-Data
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/agents¶

List Dashboard Agents

Lists every pending, active, revoked, cancelled, and expired agent of the session project with safe installation metadata, last use, authenticated request count, and directly attributable metered credits. No bearer, recipient key bytes, envelope, or project identifier is returned.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardAgents

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/agents'

Responses

Status	Meaning	Body and headers
200	Project agents.	AgentList (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/agents/{id}/events¶

List Dashboard Agent Events

This agent's history, newest first, as ONE record per trigger. It carries both what the agent asked for and what changed as a result. A request that changed something is its domain event, stamped with the command that caused it. A request that changed nothing — refused, failed, or an event-less success — is one agent.command event.

There is no separate commands endpoint; showing the same trigger on two panels was the defect this replaced. Lifecycle events for this agent are included. Worker, player, and dashboard-only activity is never inferred as agent activity. Two requests are two triggers. A retry after a refusal is a second record, never a rewrite of the first.

Reads are not recorded, because they change nothing and a polling agent would bury every real action. Anonymous enrollment and connection creation are excluded. Requests using temporary ScreenRig-Agent-Connect authority are also excluded, because that authority has not authenticated a project agent installation.

Every part of the command stamp is derived from the route this server matched or from the problem registry. There is no argument vector, no request body, no header, and no free text anywhere in a record, so nothing needs redacting and no caller can write chosen text into an operator-visible surface.

Resource identifiers appear because an identifier is never authorization and is already published on events. Paging keys on sequence, descending.

Pass the returned next_cursor as after to continue. next_cursor is empty when the page is short, which is the end of the history: a concurrent append only takes a higher sequence, and retention removes the lowest sequences first, so a cursor never duplicates or skips a surviving record. Offset paging is not supported.

Every search parameter is an exact-match or range predicate on a server-written token. A malformed cursor or filter value is refused with invalid_request. A limit outside 1-200 is clamped to the default rather than refused. Records expire on the project's own event retention window.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardAgentEvents

Parameters

Name	Send in	Required?	Description
id	path	required
after	query	optional	Cursor from a previous page's next_cursor.
limit	query	optional
command	query	optional	Exact route-derived command name, such as screens.archive.
type	query	optional	Exact event type, such as agent.command or screen.archived.
resource_type	query	optional	Exact kind of object the request acted on.
resource_id	query	optional	Exact identifier of the object the request acted on.
outcome	query	optional	Present only on agent.command records; a domain event implies ok.
problem_code	query	optional	Exact stable problem code the server refused with.
since	query	optional
until	query	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/agents/RESOURCE_ID/events'

Responses

Status	Meaning	Body and headers
200	Agent history.	EventList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/agents/{id}/disconnect¶

Disconnect Dashboard Agent

Disconnects the agent from the selected project after fresh proof. The project must be one of the person’s memberships. Pending connections and credential issuances are cancelled; no replacement token is issued.

Authentication: dashboardSession
Request body: DashboardAgentAction
Operation ID: disconnectDashboardAgent

Parameters

Name	Send in	Required?	Description
id	path	required

Request body fields

Field	Description
project_id (required, string)	minLength: 1
proof (required, DashboardProof)
capabilities (optional, array)	Optional on agent connection and connected-app approval only. Omitted approves the full requested set; a non-empty subset of the connection's capabilities narrows the granted credential; anything else is invalid_request.
user_code (optional, string)	Required when approving a device sign-in (flow device): the code the person confirms matches the terminal. A mismatch is agent_connection_code_mismatch; the fifth expires the sign-in (agent_connection_expired). Ignored otherwise. maxLength: 32
access (optional, string)	The access level a device sign-in or a connected app is approved with (Read only, Propose or Manage); omitted keeps the level asked for. Ignored for other connections. A person who cannot approve reviews may not approve Manage (403 approver_required). Allowed: "read", "propose", "manage"

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/agents/RESOURCE_ID/disconnect'

Responses

Status	Meaning	Body and headers
204	Agent disconnected.	no body
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/agents/{id}/notes¶

List Dashboard Agent Notes

The notes this agent wrote in the session project, newest first, open and resolved. state is all (the default), open or resolved. Pass next_cursor back as after; it is empty on the last page. Note bodies are plain text written by an agent; render them as text, never as HTML or Markdown.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardAgentNotes

Parameters

Name	Send in	Required?	Description
id	path	required
state	query	optional
after	query	optional	next_cursor of the previous page.
limit	query	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/agents/RESOURCE_ID/notes'

Responses

Status	Meaning	Body and headers
200	The agent's notes.	NotePage (application/json); headers: Cache-Control
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/agents/{id}/notes/{note_id}/resolve¶

Resolve Dashboard Agent Note

Resolves one of the agent's open notes as the signed-in person, with a required reason; resolution.by names the person. Appends note.resolved with the person as actor. A resolved note is note_not_open.

Authentication: dashboardSession
Request body: NoteResolve
Operation ID: resolveDashboardAgentNote

Parameters

Name	Send in	Required?	Description
id	path	required
note_id	path	required	The id of one of the agent's notes.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
reason (required, string)	minLength: 1 maxLength: 500

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/agents/RESOURCE_ID/notes/NOTE_ID/resolve'

Responses

Status	Meaning	Body and headers
200	The resolved note.	Note (application/json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
422	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/agents/{id}/notes/{note_id}¶

Delete Dashboard Agent Note

Deletes one of the agent's notes, open or resolved, as the signed-in person. Appends note.deleted with the person as actor.

Authentication: dashboardSession
Request body: none
Operation ID: deleteDashboardAgentNote

Parameters

Name	Send in	Required?	Description
id	path	required
note_id	path	required	The id of one of the agent's notes.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/agents/RESOURCE_ID/notes/NOTE_ID'

Responses

Status	Meaning	Body and headers
204	Deleted.	no body
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/agent-connections/pending¶

List Dashboard Agent Connections

The pending connection requests addressed to the session project, which a member may review and approve: requests naming the project, and device sign-ins or connects by an agent identity already a member of it.

A new installation's sign-in is not listed (its project hint is client-supplied); a person reaches it by its user code (POST /api/agent-connections/lookup).

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardAgentConnections

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/agent-connections/pending'

Responses

Status	Meaning	Body and headers
200	The pending requests, newest first, at most 100.	object (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/agent-connections/lookup¶

Lookup Dashboard Agent Connection

Resolves the user code of a pending device sign-in (`screenrig login`), as typed or prefilled on the connect page, to its connection, whose approval view then shows it. Approves nothing. Separators, spaces and case are ignored. An unknown, used or invalid code is agent_connection_invalid; an expired one agent_connection_expired.

Limited to 5 lookups per dashboard session per 10 minutes, 20 per client address per hour and 1200 per hour fleet-wide (rate_limited).

Authentication: dashboardSession
Request body: object
Operation ID: lookupDashboardAgentConnection

Request body fields

Field	Description
user_code (required, string)	maxLength: 32

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/agent-connections/lookup'

Responses

Status	Meaning	Body and headers
200	The connection the code names.	object (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/agent-connections/{id}¶

Get Dashboard Agent Connection

Returns safe connection review metadata. Review does not select a project; approval selects one of the person’s memberships.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardAgentConnection

Parameters

Name	Send in	Required?	Description
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/agent-connections/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Safe connection metadata.	AgentConnection (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/agent-connections/{id}/approve¶

Approve Dashboard Agent Connection

Approves the connection for the selected project after fresh proof and creates a pending agent. The project must be one of the person’s memberships. Returns safe metadata, never the bearer.

Authentication: dashboardSession
Request body: DashboardAgentAction
Operation ID: approveDashboardAgentConnection

Parameters

Name	Send in	Required?	Description
id	path	required

Request body fields

Field	Description
project_id (required, string)	minLength: 1
proof (required, DashboardProof)
capabilities (optional, array)	Optional on agent connection and connected-app approval only. Omitted approves the full requested set; a non-empty subset of the connection's capabilities narrows the granted credential; anything else is invalid_request.
user_code (optional, string)	Required when approving a device sign-in (flow device): the code the person confirms matches the terminal. A mismatch is agent_connection_code_mismatch; the fifth expires the sign-in (agent_connection_expired). Ignored otherwise. maxLength: 32
access (optional, string)	The access level a device sign-in or a connected app is approved with (Read only, Propose or Manage); omitted keeps the level asked for. Ignored for other connections. A person who cannot approve reviews may not approve Manage (403 approver_required). Allowed: "read", "propose", "manage"

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/agent-connections/RESOURCE_ID/approve'

Responses

Status	Meaning	Body and headers
200	Pending agent safe metadata.	Agent (application/json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/agent-connections/{id}/deny¶

Deny Dashboard Agent Connection

Denies the connection for the selected project after fresh proof without creating an agent. The project must be one of the person’s memberships.

Authentication: dashboardSession
Request body: DashboardAgentAction
Operation ID: denyDashboardAgentConnection

Parameters

Name	Send in	Required?	Description
id	path	required

Request body fields

Field	Description
project_id (required, string)	minLength: 1
proof (required, DashboardProof)
capabilities (optional, array)	Optional on agent connection and connected-app approval only. Omitted approves the full requested set; a non-empty subset of the connection's capabilities narrows the granted credential; anything else is invalid_request.
user_code (optional, string)	Required when approving a device sign-in (flow device): the code the person confirms matches the terminal. A mismatch is agent_connection_code_mismatch; the fifth expires the sign-in (agent_connection_expired). Ignored otherwise. maxLength: 32
access (optional, string)	The access level a device sign-in or a connected app is approved with (Read only, Propose or Manage); omitted keeps the level asked for. Ignored for other connections. A person who cannot approve reviews may not approve Manage (403 approver_required). Allowed: "read", "propose", "manage"

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/agent-connections/RESOURCE_ID/deny'

Responses

Status	Meaning	Body and headers
204	Connection denied.	no body
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/summary¶

Get Dashboard Summary

Project network-status counters for the session's project. Screen online counts are derived from live paired runtime event streams, the same derivation Screen.online publishes; they are not a stored boolean and not a player heartbeat. Media bytes are the durable bytes of ready media only.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardSummary

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/summary'

Responses

Status	Meaning	Body and headers
200	Project summary counters.	DashboardSummary (application/json); headers: Cache-Control
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/billing/payout-status¶

Get Dashboard Payout Status

Truthful payout capability state. rails_available is false and unavailable_reason is financial_rails_unavailable while card, tax and cash-out rail are unavailable. No raw bank credentials are returned.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardPayoutStatus

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/billing/payout-status'

Responses

Status	Meaning	Body and headers
200	Payout status.	BillingPayoutStatus (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/billing/receipts/{id}¶

Get Dashboard Receipt

One finalized receipt/tax document owned by the caller. No receipt exists while money collection is unshipped, so this is not_found rather than a fabricated document.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardReceipt

Parameters

Name	Send in	Required?	Description
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/billing/receipts/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
404	not_found - no receipt exists.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/billing/topups¶

Create Dashboard Topup

Answers billing_unavailable when payment and payout rails are not configured, rather than quoting a payment.

Authentication: dashboardSession
Request body: none
Operation ID: createDashboardTopup

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/billing/topups'

Responses

Status	Meaning	Body and headers
404	billing_unavailable.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/billing/topups/{id}/checkout¶

Checkout Dashboard Topup

Answers billing_unavailable when payment rails are not configured; no payment attempt is created.

Authentication: dashboardSession
Request body: none
Operation ID: checkoutDashboardTopup

Parameters

Name	Send in	Required?	Description
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/billing/topups/RESOURCE_ID/checkout'

Responses

Status	Meaning	Body and headers
404	billing_unavailable.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/billing/withdrawal-quotes¶

Create Dashboard Withdrawal Quote

Answers billing_unavailable when payout rails are not configured.

Authentication: dashboardSession
Request body: none
Operation ID: createDashboardWithdrawalQuote

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/billing/withdrawal-quotes'

Responses

Status	Meaning	Body and headers
404	billing_unavailable.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/billing/withdrawals¶

Create Dashboard Withdrawal

Answers billing_unavailable when payout rails are not configured; the project bearer never authorizes a cash-out.

Authentication: dashboardSession
Request body: none
Operation ID: createDashboardWithdrawal

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/billing/withdrawals'

Responses

Status	Meaning	Body and headers
404	billing_unavailable.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/billing/payout-onboarding¶

Start Dashboard Payout Onboarding

Answers billing_unavailable when payout rails are not configured; no hosted payout onboarding is created.

Authentication: dashboardSession
Request body: none
Operation ID: startDashboardPayoutOnboarding

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/billing/payout-onboarding'

Responses

Status	Meaning	Body and headers
404	billing_unavailable.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PUT/api/media/uploads/{id}/content¶

Put Dashboard Media Upload Content

Same-origin object write for one cookie media upload. No signed URL is involved and the session cookie is the authority.

Authentication: dashboardSession
Request body: string
Operation ID: putDashboardMediaUploadContent

Parameters

Name	Send in	Required?	Description
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/octet-stream' --data-binary '@request.bin' 'https://screenrig.ai/api/media/uploads/RESOURCE_ID/content'

Responses

Status	Meaning	Body and headers
204	Bytes stored.	no body
404	not_found - the upload is unknown.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/balance¶

Get Dashboard Balance

Returns the session project's public whole-credit balance. This cookie-authenticated read never debits, so it remains available at zero after an unpaid billable dashboard-stream event closes the SSE response. It is the dashboard recovery surface; the cookie-only dashboard never presents a project bearer to GET /api/project.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardBalance

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/balance'

Responses

Status	Meaning	Body and headers
200	Public whole-credit balance.	DashboardBalance (application/json); headers: Cache-Control
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/applications/{id}/preview-launches¶

Create Dashboard Application Preview Launch

Mints one single-use thirty-second launch ticket for the latest ready release of an application the session's project owns, on that release's own exact preview host, never the release host Players frame, so a Player and the dashboard in one browser never share that host's cached documents or grant cookie.

The ticket converts to the release-grant cookie on that host only, so the preview is cross-origin by construction and web application code can never read a dashboard cookie. Assign launch_url to iframe.src and to nothing else. Authority here is owner authority: the session's project owns the application.

That is a deliberate second authority source alongside exact-current-manifest authority for screenrig.webapp-package/v1, and it is scoped to this operation. Do not generalize it to media or to protected runtime content. There is no parent player, so the browser SDK and the key-value bridge fail closed and the preview is presentation-only.

An application with no ready release is resource_conflict.

Authentication: dashboardSession
Request body: none
Operation ID: createDashboardApplicationPreviewLaunch

Parameters

Name	Send in	Required?	Description
id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/applications/RESOURCE_ID/preview-launches'

Responses

Status	Meaning	Body and headers
201	Single-use 30-second exact-release-host preview launch.	ReleaseLaunch (application/json); headers: Cache-Control, Referrer-Policy, RateLimit-Policy, RateLimit
401	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
404	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
409	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/organizations/{org_id}/projects¶

Dashboard Organizations Projects

Organization admins read project names, owners, status and screen counts only; this grants no project access.

Authentication: dashboardSession
Request body: none
Operation ID: dashboardOrganizationsProjects

Parameters

Name	Send in	Required?
org_id	path	required
cursor	query	optional
limit	query	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/projects'

Responses

Status	Meaning	Body and headers
200	Organization result.	OrganizationProjectPage (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/organizations/{org_id}/discovery¶

Dashboard Organizations Discovery

Projects elsewhere whose owners have a verified email on the exact verified domain. Contact addresses and subdomains do not match, and admins cannot pull projects in.

Authentication: dashboardSession
Request body: none
Operation ID: dashboardOrganizationsDiscovery

Parameters

Name	Send in	Required?
org_id	path	required
cursor	query	optional
limit	query	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/discovery'

Responses

Status	Meaning	Body and headers
200	Organization result.	OrganizationProjectPage (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/organizations/{org_id}/domain-challenges¶

Dashboard Organizations Start Domain

Open a 7-day DNS TXT challenge for one domain, replacing that domain's pending challenge; the organization's other domains are unchanged. Put its exact value at its returned DNS name and keep it there. An organization holds at most 20 domains, verified and pending together (resource_conflict). A domain another organization holds is resource_conflict.

A domain this organization already holds may be proved again, which records the new value for the daily DNS check.

Authentication: dashboardSession
Request body: OrganizationDomainInput
Operation ID: dashboardOrganizationsStartDomain

Parameters

Name	Send in	Required?	Description
org_id	path	required

Request body fields

Field	Description
domain (required, string)	Exact DNS domain; no wildcard, URL or IP address. minLength: 3 maxLength: 253

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/organizations/ORG_ID/domain-challenges'

Responses

Status	Meaning	Body and headers
201	Organization result.	OrganizationDomainChallenge (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/organizations/{org_id}/domain-verification¶

Dashboard Organizations Verify Domain

Verify one unexpired challenge against DNS and add its domain to the organization, beside the domains it already holds. Each exact domain belongs to one organization. A proof rotated during lookup is refused. Keep the TXT record in place; a daily check removes a domain whose record stays missing for seven days.

Once the claim commits, and in the background after this response, each project whose owner is a verified person at exactly the domain and which sits alone in that owner's personal organization is moved into this organization (renamed "<name> (<owner>)" on a name conflict).

Projects in any other organization, projects holding a customer-paid plan of their own, and projects their owner or staff moved out of a domain organization stay where they are; a project the organization's limits refuse is retried a day later. Placement grants no access.

Authentication: dashboardSession
Request body: OrganizationDomainProof
Operation ID: dashboardOrganizationsVerifyDomain

Parameters

Name	Send in	Required?	Description
org_id	path	required

Request body fields

Field	Description
challenge_id (required, string)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/organizations/ORG_ID/domain-verification'

Responses

Status	Meaning	Body and headers
200	Organization result.	VerifiedOrganizationDomain (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/organizations/{org_id}/admins¶

Dashboard Organizations Admins

A designated admin reads the organization's admins, the candidates who may become one (verified, active owners of its live projects who are not admins yet) and the organization revision. Anyone else is refused as on the other organization admin routes. People only; agents and bearer credentials have no admin route.

Authentication: dashboardSession
Request body: none
Operation ID: dashboardOrganizationsAdmins

Parameters

Name	Send in	Required?	Description
org_id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/admins'

Responses

Status	Meaning	Body and headers
200	Organization admins.	OrganizationAdmins (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PUT/api/organizations/{org_id}/admins¶

Dashboard Organizations Set Admins

A designated admin replaces the organization's admins. If-Match carries the organization revision; a stale one is revision_conflict with current_revision. The set names 1 to 20 people, each a current admin or a candidate, otherwise invalid_request; an admin removes themselves only while another admin remains.

The change increments the revision, is recorded in the organization audit, grants no project membership, and returns the same shape as GET. People only; agents and bearer credentials have no admin route.

Authentication: dashboardSession
Request body: OrganizationAdminsUpdate
Operation ID: dashboardOrganizationsSetAdmins

Parameters

Name	Send in	Required?	Description
org_id	path	required
If-Match	header	required	The organization revision from GET, optionally quoted.

Request body fields

Field	Description
admin_user_ids (required, array)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'If-Match: "REVISION"' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/organizations/ORG_ID/admins'

Responses

Status	Meaning	Body and headers
200	Organization admins after the change.	OrganizationAdmins (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/organizations/{org_id}/people¶

Dashboard Organizations People

A designated admin reads the organization's people across its live projects.

Read-only. projects lists the organization's live projects, ordered by name, at most 500. people is the union of those projects' active memberships (suspended memberships are left out) and the designated admins, ordered by display name then email; each person carries their role in each project (owner or member) and whether they are an admin, and an admin in no project appears with an empty projects list. email is empty for a person whose address is not verified.

Deactivated people and agents never appear. At most 500 people are returned, admins always among them; truncated is true when people, projects or memberships were left out. Anyone else is refused as on the other organization admin routes. People only; agents and bearer credentials have no route.

Authentication: dashboardSession
Request body: none
Operation ID: dashboardOrganizationsPeople

Parameters

Name	Send in	Required?	Description
org_id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/people'

Responses

Status	Meaning	Body and headers
200	Organization people.	OrganizationPeople (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/organizations/{org_id}/admin-invitations¶

Dashboard Organizations List Admin Invitations

A designated admin lists the organization's admin invitations by id, 50 at a time, after expiring those whose time has passed. Recipient addresses are visible to the organization's admins, who supplied them. Tokens and credential URLs are never listed. People only; agents and bearer credentials have no admin route.

Authentication: dashboardSession
Request body: none
Operation ID: dashboardOrganizationsListAdminInvitations

Parameters

Name	Send in	Required?
org_id	path	required
status	query	optional
cursor	query	optional

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/admin-invitations'

Responses

Status	Meaning	Body and headers
200	The organization's admin invitations.	OrganizationAdminInvitationList (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/organizations/{org_id}/admin-invitations¶

Dashboard Organizations Create Admin Invitations

A designated admin invites people by email to become admins. Accepting adds the person to the organization's admins and creates their login if they have none; it grants no project membership. At most 20 admins counting pending admin invitations (organization_admin_limit); an address whose person already administers the organization is invalid_request.

Email invitations expire after seven days; an outstanding invitation to the same address is reused. The organization and inviter names must be fit for email. People only; agents and bearer credentials have no admin route.

Authentication: dashboardSession
Request body: OrganizationAdminInvitationCreate
Operation ID: dashboardOrganizationsCreateAdminInvitations

Parameters

Name	Send in	Required?	Description
org_id	path	required
Idempotency-Key	header	required

Request body fields

Field	Description
emails (required, array)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/organizations/ORG_ID/admin-invitations'

Responses

Status	Meaning	Body and headers
201	The organization admin invitations, one per distinct address.	OrganizationAdminInvitationCreated (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)
429	Stable rate_limited problem. Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	Problem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit

POST/api/organizations/{org_id}/admin-invitations/{invitation_id}/revoke¶

Dashboard Organizations Revoke Admin Invitation

A designated admin revokes an outstanding admin invitation and frees its admin slot. An already revoked invitation returns 204; an accepted one returns invitation_consumed; an id the organization does not hold is not_found. People only; agents and bearer credentials have no admin route.

Authentication: dashboardSession
Request body: none
Operation ID: dashboardOrganizationsRevokeAdminInvitation

Parameters

Name	Send in	Required?	Description
org_id	path	required
invitation_id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/admin-invitations/INVITATION_ID/revoke'

Responses

Status	Meaning	Body and headers
204	The invitation is revoked.	no body
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/organizations/{org_id}/domain¶

Dashboard Organizations Remove Domain

Remove every verified domain and pending challenge the organization holds; future placement and domain discovery stop. DELETE /api/organizations/{org_id}/domains/{domain} removes one.

Authentication: dashboardSession
Request body: none
Operation ID: dashboardOrganizationsRemoveDomain

Parameters

Name	Send in	Required?	Description
org_id	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/domain'

Responses

Status	Meaning	Body and headers
200	Organization result.	OrganizationDomainRemoved (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

DELETE/api/organizations/{org_id}/domains/{domain}¶

Dashboard Organizations Remove One Domain

Remove one domain, verified or pending, and leave the organization's other domains. Future placement and discovery for it stop, and another organization may verify it. Projects already in the organization stay. A domain the organization neither holds nor is proving is not_found.

Authentication: dashboardSession
Request body: none
Operation ID: dashboardOrganizationsRemoveOneDomain

Parameters

Name	Send in	Required?	Description
org_id	path	required
domain	path	required

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request DELETE --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/domains/DOMAIN'

Responses

Status	Meaning	Body and headers
200	Organization result.	OrganizationDomainRemoved (application/json); headers: Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PUT/api/members/{user_id}/approver¶

Set Dashboard Member Approver

Sets whether a member can approve: decide reviews and grant agents Manage access. A member who cannot approve has their agents held to Propose. The project owner only (forbidden otherwise); the owner's own row is fixed (resource_conflict); a non-member is not_found. Appends project.member_approver_changed (details user_id, can_approve).

Authentication: dashboardSession
Request body: MemberApproverUpdate
Operation ID: setDashboardMemberApprover

Parameters

Name	Send in	Required?	Description
user_id	path	required

Request body fields

Field	Description
can_approve (required, boolean)
project_id (optional, string)	The project the caller means; a session whose selection has changed is refused with resource_conflict. minLength: 1 maxLength: 200

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

shell · request template

curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/members/USER_ID/approver'

Responses

Status	Meaning	Body and headers
200	The member.	DashboardMember (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

API lifecycle, deprecations, and rate limits

URL families are /api, /screen, /stream, /media, /website, /agentid. Compatible changes stay additive within a major:

Additive endpoints and methods.
Optional request members.
New problem codes.
New fields only where the published schema permits unknown fields.

These changes require a new major:

Route or field removal or rename.
Type, meaning, or authorization changes.
Making optional input required.
Adding a member to a closed enum.
Adding a field to a closed response object.

A new major overlaps for at least 180 days. Sunset notice is at least 90 days, and a deprecated operation remains served for at least 90 days from the RFC 9745 Deprecation effective date unless a later published commitment controls.

No operations are currently deprecated.

Lifecycle signals are:

OpenAPI deprecated true on the operation.
RFC 9745 Deprecation with its effective date.
RFC 8594 Sunset once the sunset date is fixed.
Link with rel=deprecation to migration documentation.

Rate-limit fields

Operations with disclosed fixed-window controls declare x-rate-limit-policies. Eligible admitted responses may include the optional RateLimit-Policy and RateLimit structured field list members. Exact replays and deployments without shared admission may omit them. Fixed-window denials include them; concurrency and byte-budget denials may omit them. These fields follow draft-ietf-httpapi-ratelimit-headers-11, an Internet-Draft rather than an RFC. On every 429, Retry-After is authoritative.

RFC 9457 problems

Errors use application/problem+json. Branch on status and stable code; treat detail as explanation. Generated from problems.yaml.

free_organization_limit

409 · Free organization limit reached

type: https://screenrig.ai/problems/free-organization-limit

organization_plan_required

409 · The organization needs a plan before it admits screens

type: https://screenrig.ai/problems/organization-plan-required

project_name_conflict

409 · Project name already used in the organization

type: https://screenrig.ai/problems/project-name-conflict

project_delete_blocked

409 · Project cannot be deleted in its current state

type: https://screenrig.ai/problems/project-delete-blocked

owner_required

409 · A responsible person is required

type: https://screenrig.ai/problems/owner-required

owner_cannot_leave

409 · The project owner cannot leave

type: https://screenrig.ai/problems/owner-cannot-leave

internal_error

500 · Internal server error

type: https://screenrig.ai/problems/internal-error

invalid_request

400 · Request is invalid

type: https://screenrig.ai/problems/invalid-request

unauthorized

401 · Authentication is required

type: https://screenrig.ai/problems/unauthorized

credential_retired

401 · Credential was retired

type: https://screenrig.ai/problems/credential-retired

client_update_required

410 · Update the screenRIG plugin or CLI

type: https://screenrig.ai/problems/client-update-required

forbidden

403 · Request is not allowed

type: https://screenrig.ai/problems/forbidden

insufficient_access

403 · This access level cannot do this

type: https://screenrig.ai/problems/insufficient-access

approver_required

403 · Only an approver can do this

type: https://screenrig.ai/problems/approver-required

review_not_pending

409 · The review is no longer pending

type: https://screenrig.ai/problems/review-not-pending

review_stale

409 · The playlist changed after this proposal

type: https://screenrig.ai/problems/review-stale

review_blocked

409 · Another review must be decided first

type: https://screenrig.ai/problems/review-blocked

playlist_not_approved

409 · The playlist has no approved version

type: https://screenrig.ai/problems/playlist-not-approved

not_found

404 · Resource was not found

type: https://screenrig.ai/problems/not-found

method_not_allowed

405 · Method is not allowed

type: https://screenrig.ai/problems/method-not-allowed

idempotency_mismatch

409 · Idempotency key does not match the original request

type: https://screenrig.ai/problems/idempotency-mismatch

credential_issuance_expired

410 · Credential issuance expired

type: https://screenrig.ai/problems/credential-issuance-expired

user_email_conflict

409 · Email address belongs to another person

type: https://screenrig.ai/problems/user-email-conflict

provisioning_invalid

404 · Browser provisioning invalid

type: https://screenrig.ai/problems/provisioning-invalid

provisioning_expired

410 · Browser provisioning expired

type: https://screenrig.ai/problems/provisioning-expired

provisioning_consumed

409 · Browser provisioning consumed

type: https://screenrig.ai/problems/provisioning-consumed

provisioning_exchange_mismatch

409 · Browser provisioning exchange mismatch

type: https://screenrig.ai/problems/provisioning-exchange-mismatch

browser_already_paired

409 · Browser already paired

type: https://screenrig.ai/problems/browser-already-paired

handoff_code_invalid

404 · Browser handoff code invalid

type: https://screenrig.ai/problems/handoff-code-invalid

handoff_code_expired

410 · Browser handoff code expired

type: https://screenrig.ai/problems/handoff-code-expired

handoff_session_rate_limited

429 · Browser handoff session rate limited

type: https://screenrig.ai/problems/handoff-session-rate-limited

handoff_session_conflict

409 · Browser handoff session conflict

type: https://screenrig.ai/problems/handoff-session-conflict

browser_link_not_claimed

409 · Browser link not claimed

type: https://screenrig.ai/problems/browser-link-not-claimed

browser_link_project_mismatch

403 · Browser link project mismatch

type: https://screenrig.ai/problems/browser-link-project-mismatch

origin_not_allowed

403 · Origin is not allowed

type: https://screenrig.ai/problems/origin-not-allowed

resource_conflict

409 · Resource state conflicts with the request

type: https://screenrig.ai/problems/resource-conflict

card_invalid

400 · Card placement is invalid

type: https://screenrig.ai/problems/card-invalid

card_data_invalid

409 · Card data document does not fit a card that reads it

type: https://screenrig.ai/problems/card-data-invalid

revision_conflict

412 · Resource revision does not match

type: https://screenrig.ai/problems/revision-conflict

invalid_range

416 · Requested byte range is not satisfiable

type: https://screenrig.ai/problems/invalid-range

quota_exceeded

413 · Project content quota is exceeded

type: https://screenrig.ai/problems/quota-exceeded

payment_required

402 · Prepaid credit is required

type: https://screenrig.ai/problems/payment-required

rate_limited

429 · Request rate is too high

type: https://screenrig.ai/problems/rate-limited

revocation_unavailable

500 · Credential revocation state is unavailable

type: https://screenrig.ai/problems/revocation-unavailable

dependency_unavailable

500 · Required dependency is unavailable

type: https://screenrig.ai/problems/dependency-unavailable

dependency_timeout

500 · Required dependency did not answer in time

type: https://screenrig.ai/problems/dependency-timeout

schema_incompatible

500 · Database schema is incompatible

type: https://screenrig.ai/problems/schema-incompatible

not_ready

500 · Service is not ready

type: https://screenrig.ai/problems/not-ready

server_draining

421 · Service is draining

type: https://screenrig.ai/problems/server-draining

manifest_degraded

500 · Runtime manifest projection is degraded

type: https://screenrig.ai/problems/manifest-degraded

screenshot_unavailable

409 · Screenshot is not available

type: https://screenrig.ai/problems/screenshot-unavailable

identity_invalid

400 · Player public key is invalid

type: https://screenrig.ai/problems/identity-invalid

identity_conflict

409 · Player public key does not match the enrollment

type: https://screenrig.ai/problems/identity-conflict

enrollment_bound

409 · Player public key is already bound to a project

type: https://screenrig.ai/problems/enrollment-bound

proof_invalid

401 · Player identity proof is invalid

type: https://screenrig.ai/problems/proof-invalid

screen_archived

409 · Screen is archived

type: https://screenrig.ai/problems/screen-archived

screen_archive_required

409 · Archive the screen instead of deleting or unbinding it

type: https://screenrig.ai/problems/screen-archive-required

passkey_invalid

401 · Passkey ceremony is invalid

type: https://screenrig.ai/problems/passkey-invalid

passkeys_disabled

403 · Passkeys are disabled on this server

type: https://screenrig.ai/problems/passkeys-disabled

application_in_use

409 · A live manifest still references an application release

type: https://screenrig.ai/problems/application-in-use

agent_connection_invalid

404 · Agent connection is invalid

type: https://screenrig.ai/problems/agent-connection-invalid

agent_connection_code_mismatch

400 · The code does not match this sign-in

type: https://screenrig.ai/problems/agent-connection-code-mismatch

agent_connection_expired

410 · Agent connection is expired

type: https://screenrig.ai/problems/agent-connection-expired

agent_connection_conflict

409 · Agent connection is already resolved

type: https://screenrig.ai/problems/agent-connection-conflict

agent_connection_not_approved

409 · Agent connection is not approved

type: https://screenrig.ai/problems/agent-connection-not-approved

agent_connection_cancelled

410 · Agent connection was cancelled

type: https://screenrig.ai/problems/agent-connection-cancelled

agent_limit_exceeded

409 · Agent limit is exceeded

type: https://screenrig.ai/problems/agent-limit-exceeded

agent_lockout_risk

409 · Disconnecting the last active agent risks lockout

type: https://screenrig.ai/problems/agent-lockout-risk

recovery_ambiguous

409 · Device identifier is attached to more than one screen

type: https://screenrig.ai/problems/recovery-ambiguous

recovery_expired

410 · Screen recovery offer has expired

type: https://screenrig.ai/problems/recovery-expired

recovery_not_offered

404 · No screen recovery is pending

type: https://screenrig.ai/problems/recovery-not-offered

invitation_limit_reached

409 · Project has the maximum outstanding invitations

type: https://screenrig.ai/problems/invitation-limit-reached

organization_admin_limit

409 · Organization admin limit reached

type: https://screenrig.ai/problems/organization-admin-limit

version_required

409 · Playlist requires a newer API version

type: https://screenrig.ai/problems/version-required

price_change_pending

409 · Campaign is paused until new rates are accepted

type: https://screenrig.ai/problems/price-change-pending

quote_stale

409 · Advertising quote is stale or expired

type: https://screenrig.ai/problems/quote-stale

insufficient_credits

402 · Eligible credits are insufficient

type: https://screenrig.ai/problems/insufficient-credits

self_deal

409 · A project cannot buy advertising in its own network

type: https://screenrig.ai/problems/self-deal

invitation_invalid

404 · Invitation is invalid

type: https://screenrig.ai/problems/invitation-invalid

invitation_expired

410 · Invitation is expired

type: https://screenrig.ai/problems/invitation-expired

invitation_consumed

409 · Invitation is already accepted

type: https://screenrig.ai/problems/invitation-consumed

invitation_email_mismatch

403 · Invitation belongs to a different email address

type: https://screenrig.ai/problems/invitation-email-mismatch

reauthentication_required

401 · Fresh sign-in proof is required

type: https://screenrig.ai/problems/reauthentication-required

member_limit_reached

409 · Project has the maximum members

type: https://screenrig.ai/problems/member-limit-reached

last_credential

409 · Last sign-in method cannot be removed

type: https://screenrig.ai/problems/last-credential

no_project

409 · No current project is selected

type: https://screenrig.ai/problems/no-project

billing_unavailable

404 · This billing action is not available

type: https://screenrig.ai/problems/billing-unavailable

feature_unavailable

404 · This feature is not available on this server

type: https://screenrig.ai/problems/feature-unavailable

user_binding_stale

409 · Claiming user email binding is stale

type: https://screenrig.ai/problems/user-binding-stale

session_expired

401 · Runtime session is expired or no longer current

type: https://screenrig.ai/problems/session-expired

credential_revoked

401 · Device credential no longer binds this device to a screen

type: https://screenrig.ai/problems/credential-revoked

proof_clock_skew

401 · Player identity proof is outside the accepted time window

type: https://screenrig.ai/problems/proof-clock-skew

key_retired

401 · Player key was replaced and its grace window has closed

type: https://screenrig.ai/problems/key-retired

assignment_not_found

404 · Screen has no playlist assignment

type: https://screenrig.ai/problems/assignment-not-found

upgrade_required

403 · Player version is below the supported minimum

type: https://screenrig.ai/problems/upgrade-required

reboot_unsupported

409 · Screen cannot reboot remotely

type: https://screenrig.ai/problems/reboot-unsupported

webhook_limit_reached

409 · Project has the maximum webhooks

type: https://screenrig.ai/problems/webhook-limit-reached

fleet_link_limit_reached

409 · Project has the maximum fleet links

type: https://screenrig.ai/problems/fleet-link-limit-reached

webhook_url_rejected

400 · Webhook URL must be HTTPS on a public Internet host

type: https://screenrig.ai/problems/webhook-url-rejected

note_contains_credential

422 · Note text contains a credential

type: https://screenrig.ai/problems/note-contains-credential

note_rejected

422 · Note text was rejected

type: https://screenrig.ai/problems/note-rejected

note_not_open

409 · Note is not open

type: https://screenrig.ai/problems/note-not-open

note_limit_reached

409 · Project has the maximum open notes

type: https://screenrig.ai/problems/note-limit-reached

trigger_limit_reached

409 · Project has the maximum triggers

type: https://screenrig.ai/problems/trigger-limit-reached

kv_webhook_limit_reached

409 · Application has the maximum key/value webhooks

type: https://screenrig.ai/problems/kv-webhook-limit-reached

support_conversation_closed

409 · Support conversation is closed

type: https://screenrig.ai/problems/support-conversation-closed

submission_too_short

422 · Submission is too short to act on

type: https://screenrig.ai/problems/submission-too-short

submission_unclear

422 · Submission does not describe a problem or request

type: https://screenrig.ai/problems/submission-unclear

submission_rejected

422 · Submission was not accepted

type: https://screenrig.ai/problems/submission-rejected

submission_screening_unavailable

500 · Submission cannot be screened right now

type: https://screenrig.ai/problems/submission-screening-unavailable

demo_slot_unavailable

409 · Demo time is no longer available

type: https://screenrig.ai/problems/demo-slot-unavailable

agentid_claim_invalid

400 · AgentID claim is invalid or expired

type: https://screenrig.ai/problems/agentid-claim-invalid

agentid_already_enrolled

409 · AgentID is already enrolled

type: https://screenrig.ai/problems/agentid-already-enrolled

Diagnostics and contract source

Bundled CLI diagnostics keep authorization, cookies, signed upload details, object identifiers, and customer content out of retained output. The raw OpenAPI document is the HTTP source of truth.

Schema index

Generated names, required fields, and schema descriptions; use raw OpenAPI for complete JSON Schema.

AccessLevel — required: none
read (Read only) < propose < manage. Propose reads, contributes (media, notes, comments, support, feedback, screenshots, ad drafts) and turns playlist and screen changes into reviews (docs/reviews.md).
AccessLimitedBy — required: none
Why effective_access is lower than the credential's access. project - the project requires review for agent changes. person - the agent's responsible person is a member who cannot approve reviews.
AdslotPageWrite — required: id, type, adslot_id
Whole-page advertising slot. At most 16 adslot pages, and at least one ordinary page with no visibility, are server checks and are not expressed here.
AdvertisingCampaign — required: id, revision, name, state, pause_reasons, price_change_pending, daily_cap_mcr, lifetime_cap_mcr, reserved_mcr, spent_mcr, flight_start, flight_end, networks, created_at, updated_at
AdvertisingCampaignDraft — required: name, daily_cap_mcr, lifetime_cap_mcr, flight_start, flight_end, networks
AdvertisingCampaignList — required: campaigns
AdvertisingCampaignNetwork — required: seller_project_id, membership_id, admission_generation, screen_ids, slot_ids, creative_ids, network_cap_mcr, network_reserved_mcr, network_spent_mcr, accepted_pricing_generation, price_change_pending, barrier_generation, enabled
AdvertisingCampaignNetworkDraft — required: seller_project_id, screen_ids, slot_ids, creative_ids
AdvertisingCreative — required: id, revision, media_id, media_revision, sha256, kind, content_type, duration_ms, width, height, bytes, state, created_at
AdvertisingCreativeCreate — required: media_id
AdvertisingCreativeList — required: creatives
AdvertisingCreativeReview — required: id, seller_project_id, creative_revision, state, created_at
AdvertisingDaypart — required: start, end
AdvertisingDeliveryReport — required: gross_mcr, fee_mcr, net_mcr, completed, interrupted, unbillable, rows, coverage
AdvertisingDeliveryRow — required: screen_id, slot_id, reservation_id, gross_mcr, fee_mcr, net_mcr, completed_at
AdvertisingInventory — required: screen_id, revision, ads_enabled, audience_tags, rate_override_mcr_per_15s, rate_revision, created_at, updated_at
AdvertisingInventoryList — required: inventory
AdvertisingInventoryWrite — required: ads_enabled
AdvertisingJoinedInventory — required: inventory, slots
AdvertisingJoinedNetwork — required: seller_project_id, membership_id, policy, admission_generation, scope, price_change_pending, default_rate_mcr_per_15s
AdvertisingJoinedNetworkList — required: networks
AdvertisingMembership — required: id, seller_project_id, admission_generation, policy_revision, policy, scope, state, revision, created_at, updated_at
AdvertisingMembershipList — required: memberships
AdvertisingMembershipScope — required: policy, screen_ids, slot_ids
AdvertisingNetwork — required: id, revision, enabled, rate_revision, pricing_generation, seller_fee_bps, seller_fee_revision, created_at, updated_at
AdvertisingNetworkCreate — required: name
AdvertisingQuote — required: id, campaign_id, campaign_revision, revision, state, expires_at, items, pricing_generations, created_at
AdvertisingQuoteAccept — required: quote_id
AdvertisingQuoteItem — required: seller_project_id, screen_id, slot_id, creative_id, duration_ms, rate_mcr_per_15s, play_price_mcr, pricing_generation, fee_bps, fee_revision
AdvertisingRate — required: rate_mcr_per_15s
AdvertisingReportCoverage — required: mode, outcomes_complete
Coverage of playback outcome counts. Monetary totals always come from immutable settlements. When outcomes_complete is false, counts are observed lower bounds and missing history is unavailable, not zero.
AdvertisingReview — required: id, creative_id, creative_revision, state, created_at
AdvertisingReviewDetail — required: review, creative
AdvertisingReviewList — required: reviews
AdvertisingReviewRejection — required: reason
AdvertisingScope — required: screen_ids, slot_ids
AdvertisingSlot — required: id, revision, name, enabled, accepted_media, max_image_duration_ms, max_video_duration_ms, muted, rate_override_mcr_per_15s, rate_revision, created_at, updated_at
AdvertisingSlotList — required: slots
AdvertisingSlotWrite — required: name, accepted_media, max_image_duration_ms, max_video_duration_ms
AdvertisingSpendReport — required: campaign_id, spent_mcr, reserved_mcr, completed, unbillable, pending, coverage
Agent — required: id, name, agent_type, capabilities, state, authenticated_requests, metered_credits, created_at
AgentCapability — required: none
One agent-credential capability area. Capabilities are fixed when the credential is minted; to change them, connect a new agent and disconnect the old one. Canonical order is this enum order; capability lists never contain duplicates.
AgentConnection — required: connection_id, name, agent_type, status, capabilities, expires_at, created_at
AgentConnectionRequest — required: recipient_public_key
AgentConnectionStart — required: connection_id, connection_token, approval_url, expires_at
AgentCredentialCollection — required: agent, credential_envelope, issuance_expires_at
AgentCredentialEnvelope — required: algorithm, ephemeral_public_key, nonce, ciphertext
AgentDisconnectRequest — required: none
AgentIdentityCredential — required: agent_id, identity_token, issuance_expires_at
AgentInput — required: none
AgentList — required: items
AgentSelfStatus — required: agent, connection_ready
Application — required: id, name, revision, created_at, updated_at
ApplicationEventContext — required: primitive_id, code
ApplicationEventReport — required: severity, code, context
ApplicationList — required: items
ApplicationRename — required: name
ArchivedProjectDevice — required: screen_id, label, host
BillingBalance — required: wallet_revision, remaining_mcr, reserved_mcr, available_mcr, sources, withdrawal
BillingPayer — required: kind, id
BillingPayoutStatus — required: rails_available, unavailable_reason
BillingSourceBucket — required: remaining_mcr, reserved_mcr
BillingSources — required: nonredeemable, purchased, ad_earned
BillingStatement — required: entries, next_cursor
BillingStatementEntry — required: sequence, journal_id, kind, amount_mcr, amount_credits, amount_usd, occurred_at
BillingUsageAllowance — required: bandwidth_bytes, storage_mcr, api_events, storage_mcr_per_gb_month
The monthly allowance one payer's pool waives, as canonical decimal strings. Unused allowance does not roll over.
BillingUsageAmounts — required: bandwidth_bytes, waived_bandwidth_bytes, storage_mcr, waived_storage_mcr, api_events
BillingWithdrawal — required: eligible_earned_mcr, amount_usd_cents, threshold_exclusive_usd_cents, allowed, blockers, rails_available
BrowserLinkClaim — required: session_id, status, screen
BrowserLinkClaimRequest — required: code
BrowserLinkClaimScreen — required: id, public_id, state, public_url
BrowserLinkEvent — required: session_id, status, event_id, expires_at
BrowserLinkSession — required: session_id, code, display_code, status, expires_at
BrowserLinkStatus — required: session_id, code, display_code, status, continuation_path, expires_at
BrowserProvisioningCompletion — required: screen, public_url
BrowserProvisioningExchange — required: provisioning_token, exchange_id
CLIEnrollment — required: project, agent, connection_ready, token, issuance_id, issuance_expires_at, invitation
CLIEnrollmentOAuth — required: project, agent, connection_ready, issuance_id, issuance_expires_at, invitation, access_token, token_type, expires_in, refresh_token, refresh_expires_at, scope
Enrollment in the oauth credential format. The enrollment's grant (client screenrig-cli, Manage on the new project with every capability, identity access Manage) issued its first token pair; an exact retry before issuance_expires_at returns the same pair, later retries return credential_issuance_expired.
CLIEnrollmentRequest — required: client_id
CanvasBackground — required: none
Solid canonical uppercase #RRGGBBAA, or a top-to-bottom linear gradient.
CanvasColor — required: none
Canonical uppercase sRGB RRGGBBAA.
Capabilities — required: api_version, protocol_version, application_compressed_bytes, application_expanded_bytes, application_package_bytes, application_file_count, application_file_bytes, application_path_depth, application_path_bytes, media_image_bytes, media_audio_bytes, playlist_max_pages, playlist_max_items_per_page, playlist_max_media_per_selector, transition_max_duration_ms, screens_per_project, project_content_bytes, features
CardDataEntry — required: key, document, bytes, sha256, revision, created_at, updated_at
CardDataList — required: items, next_cursor
CardDataSummary — required: key, bytes, sha256, revision, created_at, updated_at
CardDataWrite — required: document
Comments — required: comments
CommentsWrite — required: comments
CreatedProject — required: project, organization
DashboardAgentAction — required: project_id, proof
DashboardApplicationSummary — required: count
DashboardBalance — required: credit_remaining, credit_included, credit_reset
DashboardDisplayName — required: none
Trimmed printable display name, at most 80 UTF-8 bytes. Rejects controls, URL-looking text, @, www., ://, and credential material. Never authorization.
DashboardEmail — required: email, email_verified, email_revision
The current user's own email view. The verified address stays effective while a change is pending, and the pending candidate is visible only to its owner.
DashboardHealthSummary — required: display_disconnected, hot, crashing, stale
Active screens with a health report, counted by condition; a screen can count in several. display_disconnected, hot, and crashing count only online screens whose latest report is current (not stale); stale counts online screens whose report is older than 35 minutes and nothing else.
DashboardMe — required: user_id, display_name, email, password, passkeys, created_at
DashboardMediaSummary — required: count, bytes
Ready media counters for the session's project. bytes counts stored media bytes only; it is not the project used_bytes total, which also covers release trees and key/value entries.
DashboardMember — required: user_id, display_name, joined_at, passkeys, password, owner
DashboardMemberList — required: items, viewer_user_id, viewer_is_owner
DashboardPasskey — required: id, name, created_at, last_used_at
DashboardPasskeyAssertion — required: ceremony_id, request_options
DashboardPasskeyAssertionComplete — required: ceremony_id, credential
DashboardPasskeyComplete — required: ceremony_id, credential
DashboardPasskeyList — required: items
DashboardPasskeyPatch — required: name
DashboardPasskeyProof — required: type, ceremony_id, credential
DashboardPasskeyRegistration — required: ceremony_id, creation_options
DashboardPasswordLogin — required: email, password
DashboardPasswordProof — required: type, password
DashboardPasswordSet — required: password, proof
DashboardPendingEmail — required: email, expires_at
DashboardProject — required: status, created_at, email, email_verified, screen_count, screen_limit, used_bytes, reserved_bytes, content_limit_bytes, event_retention_days, name
Status, contact address, enforced limits, usage, retention, and public whole-credit state for one project. The internal plan identifier remains unpublished.
DashboardProjectList — required: items
DashboardProjectListItem — required: id, name, last_used_at
DashboardProjectReference — required: id, name
DashboardProjectSwitch — required: project_id
DashboardProof — required: none
DashboardProofRequest — required: proof
DashboardReauthentication — required: ceremony_id, options
DashboardReauthenticationRequest — required: kind
DashboardScreenSummary — required: total, online, pairing_pending, active, archived
Screen counters for the session's project. total is pairing_pending plus active and excludes archived, matching project screen_count. online is derived from live paired runtime event streams exactly as Screen.online is; it is not a stored boolean and not a player heartbeat.
DashboardSession — required: user_id, display_name, email, project, auth_method, authenticated_at, expires_at, dev_auth, staff, shadow, passkey_enrollment_required
Person session. Identifiers are descriptive; the session cookie establishes authority. A person with no projects has project: null.
DashboardStaffActionRequest — required: request_id, change, state, created_at, expires_at
DashboardStaffActivity — required: id, project_id, sequence, at, type, severity, outcome, actor_kind
DashboardStaffActivityPage — required: items, next_cursor, since, until, retention_seconds
DashboardStaffAudit — required: audit_id, request_id, user_id, change, created_at
DashboardStaffAuditPage — required: items, next_cursor
DashboardStaffChange — required: action
Only fields required by the selected action are accepted. project.write-mode requires a reason and the current session project; it grants ten minutes of staff write access, ending on a project switch, logout, staff revoke or unshadow.
Every admitted project write has a permanent audit. project.write, project.write-mode-end, project.shadow, project.unshadow, project.member and project.member-remove are audit-only actions and cannot be proposed; project.member records a membership granted, and project.member-remove one ended, by the screenrig-admin org apply command, whose rows carry its reason. staff.grant and staff.revoke appoint an existing verified person by ID. person.free-cap sets how many free Standard organizations the person may open (free_limit; none restores one) and changes no organization they hold; organization.domain with no domain removes the claim; a domain set pulls in, after the approved change commits, the projects its verified people hold alone in their personal organizations, as domain verification does. project.owner explicitly appoints the person and adds their project membership.
Admin and owner targets must be existing verified people. organization.plan with no plan_id schedules removal; project.plan-to-organization with no plan_id moves the existing plan; the organization's other projects holding plans of their own roll up into it, each paying for itself until the next UTC month boundary or the organization plan's start, whichever is later.
An organization holds premium, enterprise, promo or the staff-assigned staff plan; every organization without one pays on Standard, so organization.plan standard removes the plan as no plan_id does, and project.plan-to-organization refuses standard.
Organization billing must be enabled for both; the result names the actual effective time and grant. project.plan takes standard, which ends a plan the project still holds of its own at the next UTC month boundary and refuses occupancy above Standard's limits.
Project-held Enterprise is accepted only before organization billing is enabled, through the retained provisioning path. person.reset-sign-in emails a one-hour sign-in reset link to the person's verified email address only; the link is never returned to staff, and the result names only the delivery and expiry.
Demo actions bind the exact demo_version and demo_revision. Attendance, staff-reported outcomes and follow-up decisions are separate; completed booking never implies attendance or conversion. Offer-live and booking-link actions queue existing durable notification jobs only after approval.
With revoke_passkeys it also removes every passkey of the person, ends every dashboard session and cuts off every token already issued to them, in the same approved action.
DashboardStaffDeletionPreview — required: none
DashboardStaffDemo — required: id, email, organization, country, screen_range, budget, timezone, source, route, review_requested, confidence, created_at, updated_at, booking, tracking, notifications_enabled
DashboardStaffDemoBooking — required: state
DashboardStaffDemoPage — required: items, next_cursor
DashboardStaffDemoTracking — required: revision, attendance, outcome, followup
DashboardStaffFeedback — required: id, project_id, kind, title, body, created_at
Staff-only feedback with plain text fields. Escape for the display context, including historical submissions.
DashboardStaffFeedbackList — required: items, next_cursor
DashboardStaffGrantRequest — required: email, proof
DashboardStaffJourney — required: id, name, created_at, stages, progress, stalled
DashboardStaffJourneyCount — required: key, label, observed, ordered, unknown, not_observed, waiting, covered_gap
DashboardStaffJourneyStage — required: key, state, source, timing
DashboardStaffJourneyTransition — required: from, to, samples
DashboardStaffJourneys — required: as_of, since, until, event_history_since, playback_history_since, total, scanned, truncated, stalled, counts, transitions, items
DashboardStaffMember — required: user_id, display_name, email, created_at
A person carrying the screenrig_staff flag.
DashboardStaffMemberList — required: items
DashboardStaffOperationsAds — required: requests_per_second, bits_per_second
DashboardStaffOperationsClientRow — required: client, requests, errors, bytes, client_kind, bot_name
DashboardStaffOperationsClients — required: window_seconds, rows
DashboardStaffOperationsDownloader — required: project_id, project_name, bytes, requests
DashboardStaffOperationsDownloaders — required: window, projects
DashboardStaffOperationsEdgeErrorRow — required: status, route, lane, term, requests, last_seen
DashboardStaffOperationsEdgeErrors — required: window_seconds, rows
DashboardStaffOperationsIngestLag — required: window_seconds, p50_ms, p95_ms
DashboardStaffOperationsInsights — required: generated_at, top_downloaders, server_errors, client_errors, service_errors, latency, top_routes, top_clients, trend, streams_open, ingest_lag
Each section is null when its read failed or its source is missing. Every list is sorted by its count, descending, except trend, which is by time.
DashboardStaffOperationsLane — required: lane, requests_per_second, bits_per_second, ingress_bits_per_second, client_errors_per_second, server_errors_per_second, mean_duration_ms
DashboardStaffOperationsLatency — required: window_seconds, rows
DashboardStaffOperationsLatencyRow — required: lane, requests, p50_ms, p95_ms, p99_ms
DashboardStaffOperationsLive — required: generated_at, through, bucket_seconds, window_seconds, total, lanes, ads, statuses, traffic, cache, limited, nodes, series, screens_online
Rates are per second over window_seconds of complete buckets ending at through. Every list is sorted by its rate, descending.
DashboardStaffOperationsNamedRate — required: name, per_second
DashboardStaffOperationsNode — required: node, requests_per_second, bits_per_second, reporting, last_flush
DashboardStaffOperationsRates — required: requests_per_second, bits_per_second, ingress_bits_per_second, client_errors_per_second, server_errors_per_second, mean_duration_ms
DashboardStaffOperationsRouteRow — required: route, lane, requests, bytes, server_errors, p95_ms
DashboardStaffOperationsRoutes — required: window_seconds, rows
DashboardStaffOperationsSeriesPoint — required: at, requests, bytes, client_errors, server_errors, nodes
DashboardStaffOperationsServiceErrorRow — required: service, severity, message, exception_type, count, hosts, last_seen
DashboardStaffOperationsServiceErrors — required: window_seconds, rows
DashboardStaffOperationsStatusRate — required: status, per_second
DashboardStaffOperationsTrend — required: window_seconds, bucket_seconds, rows
DashboardStaffOperationsTrendRow — required: at, lane, requests, bytes, server_errors, p95_ms
DashboardStaffOrganization — required: none
DashboardStaffOrganizationLifecyclePreview — required: organization, project_ids, can_close
DashboardStaffOrganizationPage — required: items, next_cursor
DashboardStaffPlan — required: none
The project's plan identifier, visible to staff only.
DashboardStaffPlayer — required: legacy, seen_at
DashboardStaffProject — required: id, name, status, plan, email, screen_count, screen_limit, used_bytes, content_limit_bytes, credit_remaining, created_at, members, shadowed
DashboardStaffProjectDetail — required: id, name, status, plan, email, email_verified, screen_count, screen_limit, used_bytes, reserved_bytes, content_limit_bytes, credit_remaining, created_at, members, screens, media, applications, agents, shadowed
DashboardStaffProjectList — required: items
DashboardStaffProjectMember — required: user_id, display_name, email, joined_at, last_used_at
DashboardStaffProjectOperation — required: route, state
Recorded before staff domain work starts. A missing completion means its outcome is unknown. Contains the registered route pattern, never a raw URL, query, body, proof or credentials. Admitted work can finish after lease expiry or revocation.
DashboardStaffReport — required: report, columns, metadata, rows
DashboardStaffReportCatalog — required: datasets, environment, max_rows, max_window, active_window
DashboardStaffReportDataset — required: name, fields, sums, defaults
DashboardStaffReportRequest — required: words
DashboardStaffReportResponse — required: reports
DashboardStaffScreen — required: id, label, state, project_id, project_name, online, created_at
DashboardStaffScreenPage — required: items, next_cursor
DashboardStaffShadowList — required: items
DashboardStaffSignInReset — required: user_id, delivery, expires_at, passkeys_removed, sessions_revoked
The result of an executed person.reset-sign-in. It never carries the reset link.
DashboardStaffSupportConversation — required: id, project_id, project_name, subject, created_at, updated_at, last_sequence, human_requested, closed, message_count, customer_names, awaiting_reply, unread
A support conversation as the staff inbox shows it.
DashboardStaffSupportCounts — required: open, waiting, closed, unread
Conversations in the inbox's project, organization and q scope, whatever the folder.
DashboardStaffSupportInbox — required: items, next, counts
DashboardStaffSupportLastMessage — required: role, author, preview, created_at
DashboardStaffSupportMessage — required: id, conversation_id, sequence, role, author, body, created_at
A support message with who wrote it and where, for staff.
DashboardStaffSupportMessageList — required: items
DashboardStaffSupportReply — required: body
DashboardStaffSupportReplyResult — required: conversation, message
DashboardStaffSupportStateChange — required: action
DashboardStaffUser — required: user_id, display_name, email, email_verified, staff, password, passkeys, created_at, projects
DashboardStaffUserDetail — required: user_id, display_name, email, email_verified, staff, password, passkeys, created_at, projects, active_sessions
DashboardStaffUserList — required: items
DashboardStaffUserProject — required: id, name, status, screen_count, joined_at, last_used_at
A live project the person belongs to.
DashboardStaffWriteMode — required: request_id, project_id, expires_at
DashboardSummary — required: screens, media, applications
DeletedProject — required: id, screens, paired_screens_active, paired_screens_archived, paired_screens_completed_pending, agents, media, applications, playlists, memberships
DemoRequestInput — required: email, country, screen_range, organization, budget, timezone, source, flow_id
DemoResult — required: route, booking, review_requested, video_url, email, country, timezone, flow_id, source
DemoSlots — required: slots, timezone
DemoSource — required: none
DeviceSessionRequest — required: none
Cookie-paired browser mint. The body is optional. Unknown members are ignored (docs/player-compatibility.md §1.1).
DisplayWindow — required: days
EmailVerifyRequest — required: token
EmailVerifyResult — required: purpose, status
EnrollmentInvitation — required: id, status, expires_at
Event — required: cursor, type, severity, message, at
EventActor — required: user_id, display_name
Dashboard user that caused this mutation. Optional and absent on every event an agent, the CLI, a player, or a worker produced, so the field distinguishes a dashboard mutation rather than labelling all traffic. It is descriptive attribution only and is never authorization. display_name is the name the user chose at registration and is not verified.
EventAgent — required: agent_id, name, agent_type
Safe agent principal attribution present only when the event was directly caused by an authenticated agent bearer. It is never authorization.
EventCommand — required: name, method
The agent request that caused this event. Optional and absent on every event a dashboard user, a player, or a worker produced. It is descriptive attribution only and is never authorization. Every field is written by the server from the route it matched or from the problem registry.
A command object cannot carry an argument vector, a request body, a header, or any text the caller chose, and there is deliberately no field for one. name and method appear on every event an agent request committed.
The outcome fields appear ONLY on an agent.command event, which is the record for a request that committed no domain event: a committed domain event is itself the proof that the request succeeded.
EventList — required: items, next_cursor
FeedbackContext — required: none
Closed diagnostic envelope. Every member is an optional constrained scalar, nesting is structurally impossible, and an unknown member is rejected with invalid_request. The shape exists so a client cannot persist argument values, credentials, or free-form environment data through it.
FeedbackList — required: items
FeedbackSubmission — required: id, kind, title, body, created_at
One immutable project-scoped submission. It has no revision because it never changes after it is written.
FeedbackWrite — required: title, body
FleetLink — required: id, label, enabled, tags, screens_created, revision, created_at, updated_at
A Player URL that turns every device opening it into its own screen in this project.
FleetLinkList — required: items
FleetLinkPatch — required: none
FleetLinkWrite — required: label
HLSStreamSource — required: protocol, url
HealthResponse — required: status
HealthTrend — required: items, next_cursor
HealthTrendHour — required: hour, screens_reporting, hot, display_disconnected, crashing
HostContext — required: platform
The shell and hardware a player runs on, as the player reported it. A HINT that names a device; never a credential, never authorization. Only the Ed25519 key authorizes.
Stored per screen, replaced by every session mint that carries one, deleted with the screen, never written to operation logs, never echoed in problem responses, and never returned to any project other than the owner's. Read-only on the project API; ScreenPatch cannot write it.
HostDevice — required: none
Optional hardware identifiers. duid and serial are the only two the recovery hint consults; a failed read on the player omits the field.
Invitation — required: id, kind, delivery, status, project_id, created_at, expires_at
InvitationAcceptRequest — required: token, mode
New credentials are required for create_login and reset. Link create_login requires the verified signup cookie and uses its display name and email.
Email create_login requires display_name. signed_in needs sign-in within ten minutes or an invitation_accept proof bound to the invitation id. buyer applies only to ad_buyer; new buyer projects start at zero credit.
InvitationAccepted — required: kind, project_id, next
InvitationAdvertising — required: screen_ids, slot_ids, policy
Seller-owned scope: at least one screen or slot. Screens only, slots only, or both are accepted.
InvitationBuyer — required: none
InvitationCreate — required: kind
Email delivery requires emails. Link delivery is project_member only and omits emails and advertising. ad_buyer requires advertising. At most 50 outstanding member and buyer invitations per project; an outstanding email invitation of the same kind and address is reused.
InvitationCreated — required: invitations
InvitationCredential — required: none
InvitationEmailVerificationAccepted — required: status, expires_at
InvitationEmailVerificationRequest — required: token, display_name, email
InvitationInspect — required: id, kind, delivery, project, expires_at, person, modes, methods
Non-consuming inspection. person is null for links. Never reports signup verification state. Email modes are create_login or signed_in; links offer both, and resets offer reset.
InvitationInspectRequest — required: token
InvitationIssued — required: id, kind, delivery, status, project_id, created_at, expires_at
InvitationKind — required: none
InvitationList — required: items, next_cursor
InvitationPasskeyOptionsRequest — required: token, mode
InvitationPasswordCredential — required: type, password
InvitationSignup — required: email, display_name, verified, expires_at
InvitationStatus — required: none
KVEntry — required: application_id, key, value_base64, content_type, bytes, sha256, revision
KVList — required: items, next_cursor
KVSummary — required: application_id, key, content_type, bytes, sha256, revision
KVWebhook — required: id, application_id, key, description, url, created_at
An incoming key/value webhook. Its secret is returned only by create and rotate-secret.
KVWebhookCreate — required: key
KVWebhookList — required: items
KVWebhookWithSecret — required: none
KVWebhookWriteResult — required: key, revision, bytes, sha256, content_type, updated_at
KVWrite — required: value_base64
LinearGradientBackground — required: type, stops
Top-to-bottom linear gradient. There is no angle field. stops has 2 through 8 entries, strictly increasing at in [0, 1], first at=0, last at=1.
LinearGradientStop — required: at, color
One stop on a top-to-bottom linear canvas background. at=0 is the top edge, at=1 is the bottom edge.
ManifestActivatedContext — required: manifest_revision
ManifestActivatedReport — required: severity, code, context
ManifestUpgradeContext — required: manifest_revision, state
ManifestUpgradePlaylist — required: id, name, revision
The playlist identity behind an issued or queued desired revision: desired_playlist uses its exact desired grant or the read-only shared content goal for the current effective assignment before grant issuance. active_playlist always uses the exact acknowledged historical grant, never a newer assignment or content edit. id plus revision are the playlist version an operator reads as Target v42 / Playing v41; name is the playlist's display name, null when the playlist no longer exists or cannot be resolved.
A missing historical active grant is null, never a fabricated revision. A queued desired goal grants no content access.
ManifestUpgradeReport — required: severity, code, context
One latest-wins manifest-upgrade lifecycle snapshot for the session screen.
The server stores one slot per screen and derives the project read model Screen.manifest_upgrade from it; a stale, superseded, or post-activation pre-activation report is accepted with no change (202), never refused as a conflict, and no report ever promotes a grant. severity is envelope-only: the derived project event severity comes from state.
McrString — required: none
Exact integer millicredit amount as a canonical decimal string. 1 credit is 1000 mcr.
Media — required: id, filename, primitive, content_type, operation_id, sha256, bytes, revision, state, created_at, updated_at
MediaCommit — required: content_type, bytes, sha256
Declares only what the server can re-verify against the stored object byte for byte. Codec identity is not declared here: the server derives it from the container during asynchronous verification, so a client cannot assert a codec that drives player behaviour.
MediaFolder — required: id, name, parent_id, revision, created_at, updated_at
One media library folder. A playlist selector by:folder plays the ready files directly inside it, not those of its subfolders.
MediaFolderCreate — required: name
MediaFolderList — required: items
MediaFolderPatch — required: none
MediaGeneration — required: media, usage
Ready generated still plus billed usage. Never image bytes, b64_json, object keys, signed URLs, vendor URLs, vendor cost, vendor tokens, the deployment model name, or the prompt.
MediaGenerationReference — required: none
Exactly one of media_id or b64. HTTP URLs are rejected.
MediaGenerationRequest — required: prompt
Requests one still image. The prompt is customer bytes and is never returned, logged, or published on project SSE. aspect_ratio defaults to 16:9. quality is low, medium, or high and defaults to medium. tag is stored on the ready media object like an upload tag. Optional references are inline base64 or a project media_id; HTTP URLs are rejected.
The summed size of all references of one request, inline and media_id alike, must not exceed 25165824 bytes (24 MiB); a request over the bound is refused.
Remaining that cannot cover twice the vendor cost of the still, rounded up to whole credits, after the intro floor (negative 1,000,000 credits until 2027-01-01, then zero) returns payment_required, except development.
MediaGenerationUsage — required: quality, credits, usd
Customer-facing debit for one stored still. quality is the requested quality and changes the image, not a fixed price. credits are twice the vendor cost of that still, rounded up to whole ScreenRig credits. usd is the dollar equivalent of those credits. Never a vendor name, vendor cost, or token count.
MediaList — required: items
MediaMove — required: folder_id
At least one id across media_ids and folder_ids, at most 1000 in all.
MediaMoveResult — required: media, folders
MediaSelectorTagFilter — required: none
MediaSingleTagPatch — required: tag
MediaTagPatch — required: none
MediaTagsPatch — required: tags
MediaUploadDeclaration — required: filename, content_type, bytes, sha256
Declares one upload. The bytes maximum is a plan-independent transport ceiling, not an achievable size. An image content type is bounded further at 20971520 bytes, 20 MiB, and a larger image declaration is rejected with invalid_request before any byte is transferred.
That image bound is a byte-only gate: declaration never decodes the image to enforce it, and it applies to animated GIF and animated WebP exactly as it applies to a still. The default plan has no product storage cap.
A custom storage ceiling, when present, is checked first and a declaration it cannot hold is rejected with quota_exceeded before any byte is transferred. Remaining prepaid credit of zero rejects declare and commit with payment_required.
An audio/mpeg (MP3) declaration is bounded at 178257920 bytes, 170 MiB, and a larger one is rejected the same way; read media_audio_bytes to preflight it. Read media_image_bytes from the capabilities document to preflight the image bound, and project_content_bytes there, or content_limit_bytes on the project, to know any custom storage ceiling.
An optional tag is stored on the ready media object and is not redeclared at commit.
An optional source_filename records the caller's original file name when the client transcoded the bytes before upload; the ready object's filename is then derived from it so distinct sources never collide (photo.png uploaded as photo.webp is stored as photo.png.webp, photo.jpg as photo.jpg.webp, and a source photo.webp stays photo.webp).
MediaUploadSession — required: id, operation, upload_url, method, headers, expires_at
MediaUploadSource — required: filename, content_type, sha256, bytes
Verified original upload identity when ingest normalized EXIF orientation. Read-only; use it to recognize retries. The ready media digest, size and type describe the normalized delivery bytes.
MemberApproverUpdate — required: can_approve
NativeIdentityChallenge — required: nonce, expires_at, aud, op, request_hash
Compare the returned op and request_hash with your locally computed values before signing. Each nonce expires in 120 seconds and can be consumed once.
NativeIdentityChallengeRequest — required: kid, op, request_hash
Supply the operation and its request_hash for every challenge. An unknown key also requires public_key and op=pairing.start. Creating a challenge does not enroll the key.
NativeIdentityProof — required: kid, public_key, signature
Compact JWS protected header is exactly {"alg":"EdDSA"}. Claims are kid, nonce, aud=screenrig-runtime, op, integer iat/exp, nonempty jti, and request_hash.
Contextual proofs last at most 120 seconds and expire no later than their issued challenge. request_hash is lowercase SHA-256 hex of UTF-8 strings joined by one NUL, with no trailing NUL, starting with screenrig.native.identity.request.v1 and op.
Append Idempotency-Key for pairing.start and session.mint; append the exact srp_ pairing credential then completion_nonce for pairing.complete; append nothing for identity.reset. Every proof must include request_hash. A cached operation result still requires a fresh issued proof or the exact accepted proof while its short-lived receipt remains valid.
Duplicate or unknown JWS/JWK members, noncanonical base64url, and non-prime-order keys are rejected. Unknown request body members are ignored.
NativeIdentitySessionRequest — required: kid, public_key, signature
NativeIdentityProof with op=session.mint plus the optional host hint. A present host REPLACES the host stored on the screen, because firmware and shell versions drift over a screen's life. The hint never affects authorization; only the signed proof does.
Unknown members are ignored, and host and playback are read tolerantly (docs/player-compatibility.md §1.1).
NativePairingComplete — required: completion_nonce, public_key, signature
NativePairingCompletion — required: screen, public_url
NativePairingFleetLink — required: status
What the presented fleet link did for this pairing session. claimed and recovered mean the screen is already chosen, and the Player completes pairing without showing its code. Any other status leaves the code on the glass for an ordinary claim.
NativePairingRecovery — required: offered
Present only when the host duid or serial in the start request matched exactly one existing screen bound to a different key. It carries no screen, label, or project: the offer is surfaced project-side as Screen.recovery_pending and the screen.recovery_offered event, and only the owning project can confirm it.
It is absent, exactly as without a match, when the identifier is ambiguous, when the matched screen's key showed life within the last ten minutes, or when that screen already took three offers in the rolling hour. The pairing code still issues and displays exactly as without a match. The player uses this solely to log pairing.recovery_offered.
NativePairingSession — required: code, pairing_credential, expires_at
NativePairingStart — required: kid, public_key, signature
Proof of private-key possession is required before enrollment or locator creation. Sign a fresh pairing.start challenge bound to the exact Idempotency-Key; unsigned starts are rejected. The optional host object is a hint about the device, not a credential; it is stored on the screen at claim and may open a recovery offer project-side.
Unknown body members are ignored. The host hint is read tolerantly. An unknown host key is ignored and a malformed host field is dropped, never refused (docs/player-compatibility.md §1.1.1).
NativeRuntimeSession — required: paired, capabilities, event_cursor, public_url, runtime_credential
Runtime-owned native session (docs/player-compatibility.md §8). Readers ignore unknown members and unknown capabilities values. A new member is sent only to sessions whose grants cover it.
NextAction — required: command, reason
Note — required: id, body, about, state, author, created_at, confirmed_at, review_at, expires_at, resolved_at, resolution, due
A project note. Context written by an agent, never an instruction or approval; render body as plain text.
NoteAbout — required: type, id
NoteAuthor — required: agent_id, name, agent_type
The writing agent as it was when the note was added. Attribution, never authority.
NoteCounts — required: open, new, due
The project's open notes, and how many are new to and due for this caller.
NoteList — required: items, next_cursor, review, counts
NotePage — required: items, next_cursor
NoteResolution — required: cause, reason, by
NoteResolve — required: reason
NoteResolvedBy — required: kind, id, name
Who resolved the note. agent_type is present for an agent. Attribution, never authority.
NoteWrite — required: body
OAuthAuthorization — required: id, client_name, client_registered, redirect_host, access, capabilities, created_at, expires_at
OAuthAuthorizationRedirect — required: redirect_uri
OAuthError — required: error
OAuthTokenResponse — required: access_token, token_type, expires_in
Operation — required: id, kind, state, created_at, updated_at
OperationAccepted — required: id, release_id, operation_id
OrganizationAdminInvitation — required: id, kind, delivery, status, recipient_email, organization_id, created_at, expires_at
OrganizationAdminInvitationCreate — required: emails
OrganizationAdminInvitationCreated — required: invitations
OrganizationAdminInvitationList — required: items, next_cursor
OrganizationAdmins — required: admins, candidates, revision
OrganizationAdminsUpdate — required: admin_user_ids
OrganizationBillingUsage — required: org_id, period, pool, allowance, screens, projects, next_cursor
OrganizationDomainChallenge — required: organization_id, challenge_id, domain, name, value, expires_at
OrganizationDomainInput — required: domain
OrganizationDomainProof — required: challenge_id
OrganizationDomainRemoved — required: status
OrganizationList — required: organizations, new_organization_allowed
OrganizationPeople — required: projects, people, truncated
OrganizationPeopleMembership — required: project_id, role
OrganizationPeoplePerson — required: user_id, display_name, email, admin, projects
OrganizationPeopleProject — required: project_id, name
OrganizationPerson — required: user_id, display_name, email
OrganizationPersonal — required: none
The organization is only its one project's wrapper: exactly one live project, no verified domain, no organization plan now or scheduled, and no admin other than that project's owner. The dashboard hides the organization level for it.
OrganizationProject — required: id, name, organization_id, status, screen_count
OrganizationProjectPage — required: projects, next_cursor
OrganizationRename — required: name
OrganizationSummary — required: id, name, personal
OrganizationView — required: id, name, personal, revision, admin, project_count, plan_id, free, plan_required
PageFailure — required: page_id, code, at
Latest accepted playback.page_failed report for this screen. Absent until a player reports one. Read-only project health metadata; it does not change screen revision or manifest authority.
PageVisibility — required: enabled
Optional page visibility schedule. It is a sibling of advance and is never part of screenrig.canvas/v1; it describes playback orchestration, not geometry. The server validates and carries these rules as data. The player evaluates them against the screen timezone published at the manifest root.
A page is eligible when enabled is true, now is inside [from, until), and either windows is absent or at least one window matches. Every playlist must keep at least one page with no visibility field at all, so eligible content always exists. Conformance vectors for the evaluation rules are the screenrig.schedule/v1 family in packages/schedule-contract.
PageVisibilityWindow — required: days
One recurring civil window. Omitting start and end selects the whole day. When end is less than or equal to start the window crosses midnight and the start day owns it, so fri 22:00 to 02:00 runs into Saturday morning.
PairScreen — required: code
PairingClaim — required: screen, public_url
PairingClaimedEvent — required: type, completion_nonce
PairingComplete — required: completion_nonce
PairingCompletion — required: screen, public_url
PairingSession — required: code, expires_at
PasskeyAdditionProof — required: authorization_ceremony_id, authorization_credential
PlaybackAggregate — required: screen_id, media_id, filename, day, play_count, last_page_id, last_manifest_revision, first_started_at, last_started_at
PlaybackAggregateCsv — required: none
RFC 4180 CSV, CRLF records, UTF-8, with the header row screen_id,media_id,filename,primitive,day,play_count,last_page_id,last_manifest_revision,first_started_at,last_started_at. Times are RFC 3339 UTC. A cell beginning with =, +, -, @, tab, or carriage return is prefixed with a single quote so spreadsheets do not evaluate it.
Content-Disposition names playback-aggregates.csv. A stream that fails after the header is aborted at the connection.
PlaybackAggregateList — required: items
PlaybackApplicationStartedContext — required: manifest_revision, page_id, primitive_id, release_id
PlaybackApplicationStartedReport — required: severity, code, context
One visible start of an application primitive on a page: the application became visible on glass, reported once per page appearance by the Player controller — the application content never reports its own visibility, and a package download is never a start.
The sending screen is authenticated; page, primitive, release and manifest identities are reported observations without content or grant membership checks. Stores one durable per-play record (GET /api/playback/plays). Project-owned release/application housekeeping timestamps follow through a recoverable batch projection.
Ordinary playback acknowledgments omit optional credit balance headers. There is no daily aggregate row for application starts; the play records are the evidence.
PlaybackGrant — required: none
The playback handshake the backend granted: the intersection of the mint's PlaybackHandshake and what this backend supports, signed into the session. Omitted from the session when nothing intersects, so a session minted without a handshake is unchanged. A Player uses /screen/manifest only when manifest_versions contains 3.
PlaybackHandshake — required: none
Optional playback handshake a Player declares at mint. It is a hint that selects behavior, never authorization: unknown members and entries of the wrong type are ignored, and a value that is not an object negotiates nothing. The mint response echoes the supported intersection as PlaybackGrant. adslot-v1 is granted only to paired sessions.
PlaybackMediaStartedContext — required: media_id, manifest_revision, page_id, primitive
PlaybackMediaStartedReport — required: severity, code, context
One visible start of an image or video primitive on a page. Players send this once per page appearance of the media, for images exactly as for videos; loops inside one appearance are not restarts. The sending screen is authenticated; media, page, primitive and manifest identities are observations without content or grant membership checks.
Success acknowledges durable raw insertion; daily counts follow through a recoverable batched projection. Ordinary playback acknowledgments omit optional credit balance headers.
PlaybackPageFailedContext — required: page_id, code
PlaybackPageFailedReport — required: severity, code, context
Reports that one page could not become ready. On acceptance the server replaces Screen.last_page_failure and appends a durable project-only playback.page_failed event in the same transaction. It does not change screen revision or manifest authority.
PlaybackPlay — required: screen_id, page_id, media_id, primitive, received_at
One durable Player-reported start of an image, video, or application.
The session authenticates screen and project; item, page, manifest, primitive and release identities are reported observations and do not authorize content access. playlist_id and playlist_revision are optional metadata enriched asynchronously from a matching screen manifest; missing metadata stays absent.
Application starts carry release_id with empty media_id and primitive. primitive_id and started_at are present only when the Player reports them; started_at is clamped to [received_at - 24h, received_at + 5m].
PlaybackPlayCsv — required: none
RFC 4180 CSV, CRLF records, UTF-8, with the header row screen_id,playlist_id,page_id,primitive_id,media_id,primitive,started_at,received_at,manifest_revision,playlist_revision in that fixed order; an absent value is an empty cell. Times are RFC 3339 UTC. A cell beginning with =, +, -, @, tab, or carriage return is prefixed with a single quote.
Content-Disposition names playback-plays.csv. A complete export ends after its last CRLF record with no trailer; a stream that fails after the header is aborted at the connection (the client sees a transport error, never a clean end), so retry from the last received_at.
PlaybackPlayList — required: items, next_cursor
PlaybackTotals — required: by, day_from, day_to, truncated
Play totals over the inclusive UTC days day_from to day_to. Exactly one of days (by=day), screens (by=screen), media (by=media) or screen_days (by=screen_day, grouped by screen in rank order, days ascending) is present, the one the request named. truncated is true when a ranking may leave out keys that ranked below the best of a slice or a store.
PlaybackTotalsDay — required: day, play_count, first_started_at, last_started_at
PlaybackTotalsMedia — required: media_id, play_count, first_started_at, last_started_at
PlaybackTotalsScreen — required: screen_id, play_count, first_started_at, last_started_at
PlaybackTotalsScreenDay — required: screen_id, day, play_count
PlaybackVideoStartedContext — required: media_id, manifest_revision, page_id
PlaybackVideoStartedReport — required: severity, code, context
Report one visible video start. This uses the same daily aggregation as playback.media_started with primitive video. Send one report per start; sending both event types counts the start twice. Use playback.media_started when reporting both images and videos.
PlayerCardsIdentity — required: none
The built-in cards library the Player carries (docs/player-compatibility.md §3.1): the library CalVer and each card's semver, whose major says which card placements the screen renders. Stored on the screen with the rest of player. Malformed entries are dropped one by one; it is never a 400.
PlayerIdentity — required: kind
Player self-identification, sent only on the three mint routes (docs/player-compatibility.md §3.1). It is a hint and never authorization, and it is not covered by the native proof. It is read tolerantly: unknown members are ignored, an invalid optional member is dropped on its own, and a player that is not an object or has no valid kind declares nothing.
It is never a 400. A paired mint stores it on the screen for the operator fleet histogram.
PlayerPublicKey — required: kty, crv, x
PlayerShellIdentity — required: kind
The shell a web Player runs under. Its compat tokens are recorded, never granted. An invalid kind drops the shell.
Playlist — required: id, name, revision, pages
PlaylistAdvance — required: none
PlaylistAdvanceWrite — required: none
PlaylistApplicationAdvance — required: mode, max_ms
PlaylistApplicationPrimitive — required: none
PlaylistApplicationPrimitiveWrite — required: id, primitive, release_id, rect, layer, content_fit
PlaylistApproval — required: state, review_id
Present while a review of this playlist is pending. The playlist itself is the live (approved) version.
PlaylistAudio — required: tracks, loop, volume
Stored playlist soundtrack with defaults filled in.
PlaylistAudioCue — required: track
Optional soundtrack hint on an ordinary page. When the page becomes current, the Player switches to the named track from its start unless it is already playing; restart true restarts it even then. The sequence continues from that track.
Players may ignore a hint. track must name a track id in the playlist audio; a cue without a playlist audio is invalid_request. Not allowed on adslot pages.
PlaylistAudioTrack — required: id, media_id
PlaylistAudioWrite — required: tracks
Optional playlist soundtrack: ordered ready audio (MP3) media that plays continuously while pages change (docs/playlist-audio.md). Page changes never stop or restart it. PUT replaces the whole playlist, so omitting audio removes the soundtrack.
PlaylistCanvas — required: width, height, background
PlaylistCardPrimitive — required: id, primitive, card, major, params, rect, layer, content_fit, controller
PlaylistCardPrimitiveWrite — required: id, primitive, card, rect, layer, content_fit
A built-in card the Player draws natively (clock, weather, menu board, ticker, KPI tiles and the rest of the vendored cards catalog, screenrig.cards.contract/v1). params holds the placement's static properties (theme, view, corner, location, titles, column definitions) and changes only with a republish. data names a card data document (GET/PUT /api/card-data/{key}) that holds the card's dynamic properties (menu sections, ticker items, KPI tiles); agents change it without a republish.
With data, params may not carry dynamic properties; without it, params carry the whole configuration. Publish refuses an unknown card or major and invalid params (card_invalid), and a bound key whose stored document the card rejects (card_data_invalid). A card with a third-party feed (weather) reads it from the key the server derives from its static params.
PlaylistDurationAdvance — required: mode, after_ms
PlaylistIframePrimitive — required: id, primitive, src, title, rect, layer, content_fit, controller
PlaylistIframePrimitiveWrite — required: id, primitive, src, title, rect, layer, content_fit
PlaylistImagePrimitive — required: id, primitive, selector, resolved_media, rect, layer, content_fit, controller
PlaylistImagePrimitiveWrite — required: id, primitive, selector, rect, layer, content_fit
PlaylistIntrinsicSize — required: width, height
PlaylistList — required: items
PlaylistMediaEndAdvance — required: mode, max_ms
PlaylistMediaEndAdvanceWrite — required: mode
PlaylistMediaSelector — required: none
PlaylistMediaSelectorByAll — required: by
PlaylistMediaSelectorByFolder — required: by, folder_id
The ready files of the primitive directly inside one media folder (GET /api/media-folders), not those of its subfolders, ordered and paced like by:all. Like a tag, the folder is read again at every selector resolve, so moving files in or out changes what playing screens show from their next loop.
Writing a playlist requires the folder to exist in the project; it may be empty. A folder that holds no ready file of the primitive, or is deleted later, matches nothing. Players receive it as by:all; the server resolves the folder.
PlaylistMediaSelectorByID — required: by, media_id
PlaylistMediaSelectorByIDs — required: by, media_ids
PlaylistMediaSelectorByTag — required: by
PlaylistPage — required: id, canvas, transition, advance, primitives
PlaylistPageV2 — required: none
PlaylistPageWrite — required: id, canvas, transition, advance, primitives
PlaylistPageWriteV2 — required: none
PlaylistPrimitive — required: none
PlaylistPrimitiveWrite — required: none
PlaylistRect — required: x, y, width, height
PlaylistResolvedMedia — required: media_id, intrinsic_size
PlaylistStreamPrimitive — required: id, primitive, sources, fallback_media_id, rect, layer, content_fit, muted, controller, resolved_media
PlaylistStreamPrimitiveWrite — required: id, primitive, sources, fallback_media_id, rect, layer, content_fit
PlaylistTransition — required: type, duration_ms
Page transition. type and duration_ms are both required; OpenAPI does not default them. Swipe authoring examples use duration_ms 600; that value is not a schema default.
PlaylistV2 — required: id, name, revision, pages
PlaylistV2List — required: items
PlaylistVideoPrimitive — required: id, primitive, selector, resolved_media, muted, loop, rect, layer, content_fit, controller
PlaylistVideoPrimitiveWrite — required: id, primitive, selector, rect, layer, content_fit
PlaylistWrite — required: name, pages
PlaylistWriteV2 — required: name, pages
PrimitiveEnter — required: type
Optional object enter. Playlist write and the runtime manifest use this object as-is; there is no snake_case rename inside it. Absent means paint at rest, full opacity. Optional integer stagger 0 through 8 delays start by stagger*120 ms after the shared 500 ms delay. Absent or 0 is today's start. Duration is a named constant in screenrig.canvas/v1.
PrimitiveMotion — required: none
Optional persistent object motion. Playlist write and the runtime manifest use this object as-is; there is no snake_case rename inside it. Absent means the primitive stays at rest after enter.
Copied through uninterpolated. spin and drift apply to image and video only; application and iframe with spin or drift are rejected by the server (motion_not_allowed_for_primitive). path applies to image, video, application, and iframe. This restriction is not encoded as OpenAPI if/then.
PrimitiveMotionDrift — required: type, zoom, direction, speed
Continuous slow scale about the clipRect centre combined with a slow translate. Image and video only; the server rejects drift on application and iframe. Ping-pongs; never jumps.
PrimitiveMotionPath — required: type, points, rate
Translation along a polyline of canvas-unit waypoints after the authored rect. loop defaults to loop when omitted. Valid on image, video, application, and iframe.
PrimitiveMotionPoint — required: x, y
PrimitiveMotionSpin — required: type, direction, speed
Continuous rotation about the clipRect centre. Image and video only; the server rejects spin on application and iframe.
Problem — required: errors, instance, request_id
The problem document every route answers except the Player-facing runtime, content, and probe routes (RuntimeProblem). The error itself is errors[0]: its status, code, type, title, detail, and hint. Only document members stay at the top level. Branch on errors[0].code, never on detail or hint, which are prose.
A blamed request field adds errors[0].field; each further blamed field is its own entry with that field's detail.
ProblemError — required: status, code, type, title, detail, hint
One error of a problem document. Members beyond these describe this error further (for example dependencies on not_ready).
ProblemField — required: field, code, detail
Project — required: id, revision, status, email, email_verified, used_bytes, reserved_bytes, screen_count, content_limit_bytes, screen_limit, credit_remaining, created_at, updated_at, name
ProjectBillingUsage — required: period, usage, allowance
ProjectCapabilities — required: project_id, plan_id, features, feature_revision, capabilities
ProjectContext — required: project, organization
ProjectContextList — required: projects
ProjectCreate — required: name
ProjectDeleteConfirmation — required: name, revision
ProjectDeletionPreview — required: project, organization, devices, allowed
ProjectFeatures — required: advertiser, screens
ProjectMove — required: organization_id
ProjectMoveDestinations — required: organizations
ProjectName — required: none
Trimmed printable project name. Rejects controls, URL-looking text, @, www., and ://.
ProjectOwnerTransfer — required: user_id
ProjectPatch — required: name
ProjectUptime — required: items
ProvisionScreen — required: none
ReadyResponse — required: status, degraded
ReleaseLaunch — required: launch_url, expires_at
Review — required: id, kind, state, subject, proposer, url, created_at, updated_at, impact
ReviewAdCreative — required: creative_id, creative_revision, content_path
ReviewApproveRequest — required: none
ReviewBlocker — required: id, state, subject
ReviewChangesRequest — required: note
ReviewDecider — required: none
ReviewDecisionResult — required: review
ReviewDependentResult — required: id, state
ReviewImpact — required: screens
ReviewList — required: items, next_cursor, pending_count
ReviewLocation — required: project_id, project_name
ReviewMediaChange — required: media_id, filename, before, after
The pending change of one media item a selector_refresh review asks about.
ReviewMediaFields — required: tags, folder_id
ReviewMediaPlaylist — required: id, name, screens, media_added, media_removed
ReviewPending — required: status, review
A review-class write under Propose access. The change is not on glass until a person approves the review.
ReviewPerson — required: user_id, name
ReviewPlaylistChange — required: operation, base_revision, proposed, diff
ReviewPlaylistDiff — required: name_changed, pages_added, pages_removed, pages_changed, soundtrack_changed, media_added, media_removed
ReviewPolicy — required: agent_changes_require_review, review_policy_revision
ReviewPolicyUpdate — required: agent_changes_require_review
ReviewPreview — required: live, proposed
Live and proposed playlists in the stored shape GET /api/playlists/{id} returns (pages with resolved_media).
ReviewProposer — required: kind
ReviewRejectRequest — required: reason
ReviewScreenChange — required: action, screens, request, playlist_ids
ReviewSubject — required: type, id, name
ReviewSummary — required: id, kind, state, url, subject, impact
RuntimeAdslotCandidate — required: page_id, occurrence_id, check_sequence, earliest_start_at
RuntimeAdslotEvent — required: event_id, decision_id, occurrence_id, kind, client_sequence
RuntimeAdslotEventBatch — required: events
RuntimeAdslotEventResponse — required: results
RuntimeAdslotEventResult — required: event_id, state
RuntimeAdslotMedia — required: kind, duration_ms, content_type, bytes, sha256, content_path, fit
RuntimeAdslotPage — required: id, type, adslot_id
Whole-page advertising slot, sent only to a paired session granted adslot-v1. A Player that meets an unknown page type drops that page.
RuntimeAdslotResolveRequest — required: manifest_revision, candidates
RuntimeAdslotResolveResponse — required: server_time, results
RuntimeAdslotResult — required: occurrence_id, check_sequence, state
RuntimeAdvance — required: mode
RuntimeApplicationPackage — required: version, url, bytes, sha256, entrypoint, contentType
Immutable normalized package built only from the independently validated application tree. Native players verify bytes and SHA-256 before atomically retaining this release for offline last-known-good restoration. The URL is an authorization-bound transport reference, not a public or durable object URL.
RuntimeApplicationPrimitive — required: id, primitive, applicationId, releaseId, launchUrl, origin, protocol, grantId, package, rect, layer, contentFit
RuntimeAudio — required: loop, volume, tracks
Playlist soundtrack (docs/playlist-audio.md). Emitted only when the playlist has one and at least one track projected. The Player plays tracks in order, independently of the page sequencer; page changes, transitions and visibility never pause or restart it.
Track identity is id plus mediaId plus sha256, never src, so a manifest refresh that keeps the playing track does not restart it. Effective gain is volume times the Player volume. A defective track is dropped on its own (invalid_audio_track).
RuntimeAudioCue — required: track, restart
Soundtrack hint emitted on a page that authored audio_cue. When the page becomes current: if a different track is playing, or none, switch to track from its start; if track is playing, restart it only when restart is true. The sequence continues from track. A hint may be ignored. A cue that names no manifest track is dropped (invalid_audio_cue).
RuntimeAudioTrack — required: id, mediaId, src, sha256, bytes, contentType, durationMs, grantId
RuntimeCanvas — required: width, height, viewportFit, background
RuntimeCardPrimitive — required: id, primitive, card, major, params, rect, layer, contentFit
A built-in card. The Player merges the card's defaults, then params, then, when data is present, the dynamic properties of the document at GET /screen/card-data/{data} (only keys the card marks dynamic).
A card with data stays hidden until its first document arrives and then fades in; screen.card_data_changed for the key refetches it in place. feed, when present, is fetched from the same route and passed to the card as its feed. A Player that lacks the card or its major draws nothing for it.
RuntimeChrome — required: schema_version, banner
Runtime-owned chrome (docs/player-compatibility.md §8). Readers read the members they know and ignore the rest; a banner shape a reader does not understand shows no banner.
RuntimeCodecs — required: none
Server-derived RFC 6381 codec list for this exact rendition, never client-declared. It is a sibling of contentType; a Player can form a capability query as contentType followed by codecs="VALUE". A video whose codec cannot be derived is rejected at upload. The property is optional. An absent value does not mean that the codec is unsupported.
A present value currently contains one video-track entry; the grammar permits comma-separated entries.
RuntimeConditionReport — required: severity, code, context
RuntimeDisplay — required: none
The screen's display power control, evaluated on the device (docs/player-compatibility.md §6.5). Omitted when the screen has none; then the display stays on. Unknown members are ignored.
RuntimeHealthWrite — required: none
The PUT /screen/health body. Every member is optional; send what the platform can measure. Unknown members are ignored and a value out of range is dropped (not refused). Integers are whole JSON numbers.
RuntimeHostHint — required: platform
The optional native host hint on pairing start, pairing completion, and identity session mint. It names a device and is never authorization.
It is read tolerantly (docs/player-compatibility.md §1.1.1): unknown members are ignored, a malformed field or capabilities entry is dropped, at most 32 capabilities are kept, and a value that is not an object or a platform outside the pattern drops the whole hint. None of these refuses the request.
A Player still sends only the registered platform values and the members below, because a pre-contract backend refuses anything else.
RuntimeHostHintDevice — required: none
Optional hardware identifiers in the native host hint. A malformed field is dropped.
RuntimeIframePrimitive — required: id, primitive, src, title, rect, layer, contentFit
RuntimeImagePrimitive — required: id, primitive, selector, resolvedMedia, grantId, rect, layer, contentFit
RuntimeImageResolvedMedia — required: mediaId, src, intrinsicSize, sha256, bytes, contentType
RuntimeIntrinsicSize — required: width, height
RuntimeKVEntry — required: application_id, key, value_base64, content_type, bytes, sha256, revision
RuntimeKVList — required: items
RuntimeKVSummary — required: application_id, key, content_type, bytes, sha256, revision
RuntimeKVWrite — required: value_base64
RuntimeManifest — required: schemaVersion, manifestRevision, grantId, contentGeneration, screenId, screenLabel, playlistRevision, generatedAt, pages
Immutable runtime manifest using the deterministic screenrig.canvas/v1 canvas, rectangle, fit, and source-order contract. Read-side additional properties are permitted so a player on this contract ignores unknown keys (compatibility rule 2). Write schemas stay closed.
Pages are ordinary canvas pages and, for a paired session granted adslot-v1, whole-page adslot pages; a manifest with no adslot page is house content.
RuntimeManifestDiagnostic — required: level, code, detail
One fail-safe runtime projection omission. Players and the CLI may show these; they are never authorization.
RuntimeMediaSelector — required: none
RuntimeMediaSelectorByAll — required: by, oneAtATime
RuntimeMediaSelectorByID — required: by, mediaId, oneAtATime
RuntimeMediaSelectorByIDs — required: by, mediaIds, oneAtATime
RuntimeMediaSelectorByTag — required: by, oneAtATime
RuntimeObservationSurfaceWrite — required: id, width, height, pixel_ratio, presentation
RuntimeObservationWrite — required: observed_at, surfaces
The PUT /screen/observation body. Unknown members are ignored (docs/player-compatibility.md §1.1). The stored value is the project ScreenObservation.
RuntimeOrigins — required: content
The delivered origin allowlist (docs/player-compatibility.md §2.3). Present on a mint response only for a Player granted origins-v1.
The Player unions content with its compiled content origins and ignores an invalid entry. release_suffix replaces the compiled release suffix only when it is a valid DNS suffix of at least two labels; it is absent when the runtime origin serves releases itself (local development).
The delivered set never changes the credential origin, and the backend never puts a URL on an origin this session's mint did not deliver. A Player stores the object it validated last-known-good under, so a later session without origins keeps that LKG valid.
RuntimePage — required: contractVersion, id, canvas, transition, advance, primitives
RuntimePairingScreen — required: id, public_id, label, state, revision, manifest_revision, content_access_generation, created_at, updated_at
Runtime-owned screen summary in pairing and browser provisioning completions. Its member set is frozen: project Screen fields never appear here (docs/player-compatibility.md §8). state stays within the three values below.
RuntimePrimitive — required: none
RuntimeProblem — required: type, title, status, detail, instance, code, request_id, errors
The problem document of the Player-facing screen (/screen/) and media (/media/) routes, the pairing streams and the probe routes (/.ready, /.health): every member flat at the top level. Store-released Players read its top-level code and action (docs/player-compatibility.md §5), so this shape stays as it is; every other route answers Problem.
RuntimeRect — required: x, y, width, height
RuntimeReport — required: none
Report bodies and contexts are read tolerantly (docs/player-compatibility.md §1.1). A code needs its own context members; other members are ignored. Players still send only the members below, because a pre-contract backend refuses any other.
RuntimeScreenLabel — required: screen_label
The stored screen name, the value the manifest carries as screen_label.
RuntimeScreenLabelWrite — required: screen_label
The PUT /screen/screen-label body. The server trims screen_label and stores 1 to 120 UTF-8 bytes without control characters. Unknown members are ignored (docs/player-compatibility.md §1.1).
RuntimeSelectorSnapshot — required: manifestRevision, snapshotRevision, selections, pageMaxMs
RuntimeSession — required: paired, capabilities, event_cursor, public_url
Runtime-owned session (docs/player-compatibility.md §8). Readers ignore unknown members and unknown capabilities values. A new member is sent only to sessions whose grants cover it.
RuntimeSessionRequest — required: public_id
Anonymous viewer mint. Unknown members are ignored (docs/player-compatibility.md §1.1).
RuntimeStorageWrite — required: observed_at, volume, cache, durability, plan, transfer_24h
The PUT /screen/storage body. Unknown members are ignored (docs/player-compatibility.md §1.1). The stored value is the project ScreenStorage plus server received_at.
RuntimeStreamPrimitive — required: id, primitive, sources, muted, fallback, grantId, rect, layer, contentFit
RuntimeTelemetryBatch — required: telemetry_epoch, stream_id, sequence, created_at, reports
A durable FIFO Player queue sends at most one ordinary batch per minute with a randomized phase, or earlier when full. Total JSON body is at most 256 KiB; at most 64 reports, each at most 32 KiB. Every report retains its occurrence timestamp and stable play_id.
Keep one immutable in-flight batch on disk until 202, increment sequence only after acknowledgement, and retry the same bytes after lost replies or restarts. Sequence starts at 1 and has no gaps.
Dedupe retains at most eight live streams per screen, each watermark for at least the 24 hours in which its batch can still be replayed; keep the same stream through credential renewal. Records expire locally after 24 hours with explicit accounting. manifest.activated and manifest.upgrade stay individual and immediate.
Interactive writes, ad resolution, content fetches, screenshots, and SDK emitConfirmed() also stay immediate. Health sampling retains its fifteen-minute cadence; urgent display/health transitions are sent immediately. Observation and ordinary health snapshots are latest-wins with original occurrence times. Health requires health.write.
Existing individual reports remain accepted. Report item abuse limits apply per new item rather than per HTTP envelope; committed replay consumes only request admission.
RuntimeTransition — required: type, durationMs
Authored page transition. The runtime mint passes type through; it does not rewrite swipe to crossfade.
RuntimeUpgradeNotice — required: state, player_kind, recommended
Present on a mint response when the player's comparable version is below the recommended version for player_kind (docs/player-compatibility.md §6.1). The Player starts a platform update check and shows nothing on glass. A reader ignores the member for a state it does not know.
RuntimeVideoPrimitive — required: id, primitive, selector, resolvedMedia, muted, loop, grantId, rect, layer, contentFit
RuntimeVideoResolvedMedia — required: mediaId, src, intrinsicSize, sha256, bytes, contentType
Screen — required: id, public_id, label, revision, manifest_revision, manifest_upgrade, content_access_generation, state, online, created_at, updated_at
ScreenAction — required: none
One fleet action, discriminated by type. Each member carries only its own parameters; a member of another type is an unknown field and invalid_request.
ScreenActionAddTags — required: type, tags
Adds tags a screen does not already carry. A screen that would exceed 16 tags fails with invalid_request.
ScreenActionAssign — required: type, playlist_id
ScreenActionClearDisplaySchedule — required: type
Removes each screen's display schedule; a screen without one is ok and unchanged.
ScreenActionClearPlaylistSchedule — required: type
Removes each screen's playlist schedule; a screen without one is ok and unchanged.
ScreenActionDisplay — required: type, power
Same rules as ScreenDisplayWrite. until is checked against the request clock when the Idempotency-Key has no fleet record, and again by each screen.
ScreenActionDisplayClear — required: type
Ends each screen's manual display override (DELETE /api/screens/{id}/display); a screen without one is ok and unchanged.
ScreenActionReboot — required: type
POST /api/screens/{id}/reboot per screen; a screen whose host did not declare reboot fails alone with reboot_unsupported.
ScreenActionReload — required: type
ScreenActionRemoveTags — required: type, tags
Removes the listed tags; a tag the screen does not carry is ignored.
ScreenActionRequest — required: selector, action
ScreenActionResult — required: action, matched, succeeded, failed, results
ScreenActionScreenResult — required: screen_id, status
One screen's outcome. ok carries the result of the single-screen path: revision (and tags for tag actions) for assign, tag, takeover, takeover_clear, set_playlist_schedule, and clear_playlist_schedule actions, reload for reload, toast for toast. failed carries the problem that screen's own request would have answered.
ScreenActionSelector — required: none
ScreenActionSelectorIds — required: by, screen_ids
ScreenActionSelectorTag — required: by, tag
Every active screen whose tags contain tag, in creation order. There is no screen-count cap.
ScreenActionSetDisplaySchedule — required: type, enabled, windows
Replaces each screen's display schedule (ScreenDisplayScheduleWrite), normalized once before fan-out. A screen without a timezone fails alone with invalid_request.
ScreenActionSetPlaylistSchedule — required: type, entries
Replaces each screen's playlist schedule with the same entries (ScreenPlaylistScheduleWrite). Entry ids are assigned once before fan-out. A screen without a timezone or without a default playlist fails alone with invalid_request.
ScreenActionSetTags — required: type, tags
Replaces each screen's tag set; an empty array clears it.
ScreenActionTakeover — required: type, playlist_id
Same rules as ScreenTakeoverWrite. until is checked against the request clock before fan-out when the Idempotency-Key has no fleet record, and again by each screen.
ScreenActionTakeoverClear — required: type
Ends each screen's takeover; a screen without one is ok and unchanged.
ScreenActionToast — required: type, level, text
Same level, text, and duration rules as ScreenToastWrite, validated once before fan-out.
ScreenDisplay — required: requested, source
Display power state. requested is what the screen should show now: the active override, else the enabled display schedule evaluated in the screen timezone, else on (source override, schedule, or default); until is when that next changes, when known. reported is the Player's latest health display (power, connected, reported_at, stale after 35 minutes).
Absent when the screen has no schedule, no override, and no reported display.
ScreenDisplayOverride — required: override_id, power, until, ends_at, set_at
ScreenDisplaySchedule — required: enabled, windows, updated_at
ScreenDisplayScheduleView — required: display_schedule
ScreenDisplayScheduleWrite — required: enabled, windows
ScreenDisplayWrite — required: power
ScreenEffectivePlaylist — required: id, source
The playlist the screen's runtime manifest is built from: the takeover, else the first matching playlist schedule entry (entry_id), else the assigned default. until is the next instant this is known to change (takeover end or the next schedule boundary within eight days), absent when nothing time-based changes it.
The boundary worker applies a change at most 60 seconds late. A takeover or entry whose playlist cannot be shown is skipped. Absent when the screen shows no playlist.
ScreenHealth — required: reported_at, stale
The latest device health report (PUT /screen/health), sanitized, with server reported_at. A member the Player did not send is absent. stale is true when reported_at is more than 35 minutes old; stale health is still shown, never deleted; archive and screen recovery clear it.
Transitions append the project-only screen.health_changed with details.changes, a list of {change, ...}: display_disconnected, display_reconnected, display_power (from, to), temperature_high (at or above 80 °C), temperature_normal (below 75 °C again), crash_spike and renderer_restart_spike (the 24-hour count rose by 3 or more since the last spike event; crashes_24h or renderer_restarts_24h and previous).
Read-only; never authorization.
ScreenHealthHistory — required: none
A page of reports (resolution raw) or hourly summaries (resolution hour).
ScreenHealthHour — required: hour, reports, temperature_max_c, temperature_avg_c, cpu_load_max, memory_used_ratio_max, wifi_rssi_min_dbm, display_disconnected, crashes_24h_max, renderer_restarts_24h_max, last_reported_at
One screen's reports in one UTC hour. A member is null when no report of the hour carried it.
ScreenHealthHours — required: resolution, hours, next_cursor
ScreenHealthSample — required: reported_at
One stored device health report: Screen.health without stale. A member the Player did not send is absent.
ScreenHealthSamples — required: resolution, samples, next_cursor
ScreenList — required: items
ScreenManifestUpgrade — required: desired_revision, active_revision, desired_playlist, active_playlist, state, code, attempt, retry_at, missing_page_count, state_since, reported_at
Always-present computed manifest-upgrade state for this screen, derived at read time from its issued desired revision or queued shared-playlist content goal, its last server-acknowledged active manifest revision (manifest.activated), and the latest accepted manifest.upgrade report slot.
Read-only project state: no body can write it, and no report ever promotes a grant. active_revision is the last acknowledged activation, not proof that every simultaneous session already shows it.
Being offline never produces failure, and an overdue retry_at on a retrying state is client presentation, never a server judgment. desired_revision null is none. state pending names a desired revision with no matching report; activating names a target already on glass whose acknowledgement is still pending; a report slot whose revision stopped matching desired_revision is ignored until a new report matches, so a new desired manifest derives pending without clearing anything.
Before the next manifest contact issues a shared edit's desired grant, the desired revision and playlist can expose that queued goal as read-only intention; it grants no access. Active identity always comes from the exact acknowledged historical grant. An older activation cannot announce the newer queued goal as current.
ScreenObservation — required: observed_at, surfaces
Player-reported playback surface. Absent on Screen until the first accepted PUT /screen/observation. Read-only on the project API; ScreenPatch, PairScreen, pairing bodies, session bodies, canvas, runtime manifest, and POST /screen/reports cannot write it.
ScreenObservationSurface — required: id, width, height, pixel_ratio, presentation
ScreenPatch — required: none
ScreenPlaylistSchedule — required: entries, updated_at
Server-evaluated playlist schedule. It never reaches the runtime manifest; the manifest is built from the effective playlist it selects. Write it with PUT /api/screens/{id}/playlist-schedule.
ScreenPlaylistScheduleView — required: entries
ScreenPlaylistScheduleWrite — required: entries
ScreenPresenceHistory — required: items, next_cursor
ScreenPresenceTransition — required: at, state
ScreenProvisioning — required: screen, public_url, provisioning_url, expires_at
ScreenRebootAccepted — required: reboot_id, expires_at
ScreenRecoveryHost — required: none
What the device asking to recover this screen says it is, copied from the pairing start's host object. Descriptive fields only; it never carries duid, serial, or mac. Absent fields were not reported.
ScreenRecoveryPending — required: expires_at
Present while a native pairing session that presented this screen's hardware identity is waiting for the owning project to confirm with POST /api/screens/{id}/recovery/confirm. Carries the deadline, which is the pairing session's own expiry, and the offering device's descriptive host fields (never duid, serial, or mac).
A DUID is readable by any application on the panel, so an offer is a phishing surface: compare host.model and host.firmware with the display in front of you before confirming.
The server refuses an offer while the screen's bound key has shown life within the last ten minutes (session mint, runtime stream, manifest fetch, or presence heartbeat), and accepts at most three offers per screen per rolling hour; a new offer replaces the pending one. Absent once confirmed, lapsed, or claimed as a new screen. Read-only.
ScreenReloadAccepted — required: reload_id, expires_at
ScreenScheduleEntry — required: id, playlist_id, windows
ScreenScheduleEntryWrite — required: playlist_id, windows
One playlist schedule entry. id is optional (entry_N is assigned in order when omitted) and unique in the schedule. from (inclusive) and until (exclusive) are optional civil minute-precision bounds with no offset, from before until.
ScreenScheduleWindow — required: days
One screenrig.schedule/v1 window in the screen timezone. days are stored mon-to-sun. Omit start and end for the whole day. end <= start crosses midnight and the start day owns it (fri 22:00-02:00 runs into Saturday morning); equal edges run a full 24 hours.
ScreenScreenshotAccepted — required: capture_id, expires_at
ScreenScreenshotFailedDetails — required: capture_id, reason
details object on a durable screen.screenshot_failed event.
ScreenScreenshotReadyDetails — required: capture_id, bytes, width, height, sha256
details object on a durable screen.screenshot_ready event. Pixels and object keys are not present.
ScreenScreenshotRequestedDetails — required: capture_id, expires_at, max_width_divisor, max_height_divisor, format, quality, max_bytes
details object on a durable screen.screenshot_requested event. Image bytes and object keys are not present.
ScreenScreenshotStatus — required: state
ScreenStorage — required: observed_at, received_at, volume, cache, durability, plan, transfer_24h
Sanitized player storage report. Absent until the first accepted PUT /screen/storage. Cleared on identity reset, unpair, and archive. Consumers treat received_at older than 24 hours as stale. Read-only on the project API. Never authorization or admission. ScreenPatch cannot write it.
ScreenStorageCache — required: house_used_bytes, capacity_bytes, reserve_bytes, protected_bytes, fallback_bytes, warm_bytes, ad_headroom_bytes
ScreenStorageExcludedPage — required: page_id, reason
ScreenStorageForecast — required: manifest_revision, fit, excluded_page_count, basis, received_at
Approximate steady-state target selection (plan A.3 only, no transition) from the last reported capacity and the screen's desired manifest. Absent without a storage report, which consumers read as unknown. basis is reported_capacity. Recomputed when a storage report arrives and when the screen's manifest revision changes. Never authorization or admission.
ScreenStorageForecastDryRun — required: fit, excluded_page_count, required_bytes, capacity_bytes, basis, received_at
Pre-assignment fit dry run for one playlist. fit, excluded_page_count, and required_bytes come from plan A.3 target selection against the screen's last reported capacity (basis reported_capacity); there is no transition prediction and nothing is treated as local. required_bytes is the retained cost of every page of the playlist. fit unknown means the screen has no storage report, or the playlist's content references are not ready; required_bytes, capacity_bytes, and received_at are null then. received_at is the storage report's receipt time, and a report older than 24 hours is stale but still forecast from, exactly like Screen.storage_forecast.
It is read-only metadata and never authorization or admission.
ScreenStorageForecastRequest — required: playlist_id
Body of the pre-assignment fit dry run. playlist_id must be a playlist of the authenticated project; another project's or an unknown id is not_found.
ScreenStoragePlan — required: manifest_revision, fit, transition, required_bytes, target_bytes, excluded_pages
ScreenStorageShortfall — required: at, fit, required_bytes, capacity_bytes, excluded_page_count
Present while the player's reported fit is partial, transition_blocked, or none_fit, except a transition_blocked plan whose only blocking reason is anchor_unavailable: that is a failed download on a device with room, not a shortfall. at is when the condition began.
It is set once when the condition begins and removed when it ends, each transition appending one project-only event, screen.storage_shortfall or screen.storage_shortfall_cleared. Those events are not delivered on GET /screen/events. Cleared with Screen.storage on identity reset, unpair, and archive.
Read-only project health metadata; it does not change screen revision or manifest authority and is never authorization.
ScreenStorageTransfer — required: new, refetch, repair, failed
ScreenStorageVolume — required: total_bytes, available_bytes
ScreenSurfaceChangedDetails — required: observed_at, surfaces
details object on a durable screen.surface_changed project event. Pixels are not present. This type is not a runtime audience command and is not delivered on GET /screen/events.
ScreenTags — required: none
Fleet selector tags, 0 to 16 unique exact tags, each matching the media tag grammar. On ScreenPatch the array replaces the whole set and an empty array clears it; a duplicate or malformed tag is invalid_request. Changing tags bumps the screen revision (If-Match guards it) and appends screen.updated with details.tags; it never changes the manifest revision.
Tags are never on the runtime manifest and never authorization.
ScreenTakeover — required: playlist_id, until, set_at
The playlist that wins over the schedule and the assignment until until, or until cleared when until is null.
ScreenTakeoverWrite — required: playlist_id
ScreenToastAccepted — required: expires_at
ScreenToastDetails — required: level, text, duration_ms, expires_at
details object on a durable screen.toast event. Colours are not present.
ScreenToastWrite — required: level, text
ScreenUptime — required: items
ScreeningResult — required: checked_at
Staff-only intake screening verdict. label is the Jev decision model's label (real) with its probability; unscreened is true when the model did not run (no key installed, timeout or provider error) and only the deterministic checks did. contains_credential is true when credential-shaped text was redacted.
Submissions recorded before screening have no screening member.
ScreenshotCaptureID — required: none
Optional stage_, qa_, or development_ prefix, then shot_ and a random suffix. New suffixes use 16 alphanumeric characters excluding oOlL; retained legacy suffixes are accepted.
SelectorPreview — required: primitive, selector, matched_count, candidates
SelectorPreviewInput — required: primitive, selector
SelectorPreviewMedia — required: media_id, filename, tags
ServiceClient — required: id, project_id, name, capabilities, access, state, created_by, keys, secrets, created_at, updated_at, authenticated_requests, tokens_issued
ServiceClientChange — required: none
ServiceClientKey — required: kid, alg, thumbprint, jwk, added_at
ServiceClientList — required: items
ServiceClientResult — required: client
ServiceClientSecret — required: id, hint, added_at
SessionKeySet — required: keys
SignInPolicy — required: password, passkey, passkey_enrollment_required, policy_revision, federated
Verified person sign-in policy. Passive defaults preserve local sign-in. An enforced organization policy directs sign-in through its identity provider.
SignInResetAccepted — required: status
Identical for known and unknown addresses; no address, credential, project, or delivery status is returned.
SignInResetRequest — required: email
StreamSource — required: none
SupportConversation — required: id, subject, created_at, updated_at, last_sequence, human_requested, unread_staff, closed
SupportConversationList — required: items, next, unread_staff_total
SupportHours — required: timezone, start, end, weekdays, excludes_bc_holidays
SupportMessage — required: id, conversation_id, sequence, role, author, body, created_at
SupportMessageList — required: items
SupportRead — required: sequence
SupportStatus — required: chat_allowed, available, staffed, hours, human_wait_seconds, docs_url
SupportSubmission — required: conversation, message
SupportWrite — required: body
Trigger — required: id, kind, label, target, default_for_seconds, url, username, revision, created_at, updated_at
A CAP alert trigger. Its password is returned only by create and rotate-secret.
TriggerAlert — required: id, revision, state, status, msg_type, sender, identifier, until, screens, started_at, updated_at
The trigger's latest alert, from the CAP message fields.
TriggerAlertScreens — required: targeted, taken_over, cleared, skipped, failed, pending
What the latest takeover change did. skipped counts screens without a default playlist, archived or gone, and, when clearing, screens another takeover has replaced since.
TriggerList — required: items
TriggerReceipt — required: outcome, trigger_id
TriggerTarget — required: none
Exactly one of tag and screen_ids.
TriggerWithPassword — required: none
TriggerWrite — required: label, target
UDPStreamSource — required: protocol, group, port
UptimeDay — required: day, online_s, offline_s, availability, coverage
One UTC day. availability is online_s over online_s plus offline_s, null when nothing was recorded. coverage is the share of the day (of every reporting screen's day in a project row) with a recorded state, 0 to 1: a gap lowers coverage and is never offline time. intervals (screen rows) is how many recorded intervals touched the day; screens (project rows) how many screens had a recorded state; live marks a screen day that includes the open interval up to now.
UserEmailChangeAccepted — required: none
UserEmailChangeRequest — required: email, proof
Requests a verified-email change using fresh proof. The current email stays effective while verification is pending. The old address receives a warning only, with no undo link.
VerifiedOrganizationDomain — required: domain, organization_id, state, verified_at
VersionResponse — required: version, commit, api_version, protocol_version
Webhook — required: id, url, event_types, enabled, revision, status, created_at, updated_at
A project webhook. Player log records (runtime.reported) are not delivered.
Each matching project event is POSTed to url as the same JSON object GET /api/events returns, with headers ScreenRig-Webhook-Id, ScreenRig-Event-Id (the event cursor, stable across retries), User-Agent, and ScreenRig-Signature t=<unix seconds>,v1=<hex HMAC-SHA256 over "<t>.<raw body>" keyed with the secret string>.
A 2xx answer within 10 seconds succeeds; any other status, a redirect (never followed), a timeout, or a connection or TLS failure is retried with exponential backoff (30 seconds doubling to one hour, jittered) for 24 hours and then failed. After three consecutive timeouts the attempt timeout drops to 5 seconds until a response arrives.
A webhook has at most one attempt in flight and a project at most two, across all servers. Delivery is at least once and unordered; deduplicate on ScreenRig-Event-Id.
Each attempt is metered like a listen-stream event (1 credit after the monthly 10,000 API/SSE allowance), and the same events that are free on the listen stream are free here: screen.*, runtime.*, application.event, playback.page_failed, and agent.command.
An attempt refused before anything is sent (url_rejected, dns_failed) is not billed. payment_required and secret_unavailable back off but never count toward failing or auto-disable. status is failing while no delivery has succeeded since failing_since; after 72 hours of continuous failure the webhook is disabled (disabled_reason delivery_failures) and webhook.disabled is appended.
WebhookDelivery — required: id, webhook_id, event_id, event_type, state, attempts, created_at
WebhookDeliveryAttempt — required: attempt, at, status, error, duration_ms
WebhookDeliveryAttemptList — required: items
WebhookDeliveryList — required: items, next_cursor
WebhookEventTypes — required: none
Exact event types such as screen.online, or prefixes ending in .* such as screen.* (every type starting with screen.). webhook.test is never fanned out by a subscription; it is sent only by POST /api/webhooks/{id}/test.
WebhookList — required: items
WebhookPatch — required: none
WebhookWithSecret — required: id, url, event_types, enabled, revision, status, created_at, updated_at, secret
A Webhook plus its signing secret. Returned only by create and rotate-secret.
WebhookWrite — required: url, event_types
X25519PublicJWK — required: kty, crv, x