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	`dashboard.screenrig.ai`	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.
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, password, 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 chooses a passkey or password; 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

300 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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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)

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/v1/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/v1/capabilities'

Responses

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

Projects, invitations, and sign-in

GET/api/v1/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
Request body: none
Operation ID: listInvitations

Parameters

Name	Send in	Required?
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]' 'https://api.screenrig.ai/api/v1/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/v1/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
Request body: InvitationCreate
Operation ID: createInvitations

Parameters

Name	Send in	Required?	Description
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]' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/v1/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/v1/invitations/{id}/revoke¶

Revoke Invitation

Revokes an outstanding invitation. An accepted invitation returns invitation_consumed.

Authentication: projectBearer
Request body: none
Operation ID: revokeInvitation

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: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/v1/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/v1/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. For a contact address with no person, enrollment invitations are reissued for at most ten recent projects with zero members.

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://api.screenrig.ai/api/v1/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/v1/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
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 (required, string)	Unverified project contact address. Enrollment always creates a new project and queues its invitation; an address alone grants no authority. minLength: 3 maxLength: 254 format: "email"
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: "ScreenRig CLI" 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

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/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.	CLIEnrollment (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/api/v1/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/v1 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
Request body: none
Operation ID: getProject

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/project'

Responses

Status	Meaning	Body and headers
200	Project	Project (application/json); headers: ScreenRig-Credits-Remaining, ScreenRig-Credits-Reset, ScreenRig-Credits-Included
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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/v1/project¶

Update Project

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

Authentication: projectBearer
Request body: ProjectPatch
Operation ID: updateProject

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 --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/v1/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)

GET/api/v1/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
Request body: none
Operation ID: getProjectCapabilities

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/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)

Credit balances and statements

GET/api/v1/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
Request body: none
Operation ID: getBillingBalance

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/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/v1/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
Request body: none
Operation ID: getBillingStatement

Parameters

Name	Send in	Required?	Description
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]' 'https://api.screenrig.ai/api/v1/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)

Agent installations and connections

POST/api/v1/agent-connections¶

Start Agent Connection

Starts a request to connect another agent to an existing project. The human has 24 hours to approve it. The caller supplies an X25519 public JWK and receives a temporary connection credential separately from the browser approval URL. No project bearer, cookie, Origin header, query credential, or Idempotency-Key is accepted.

The connection id is descriptive and never authority.

Authentication: none
Request body: AgentConnectionRequest
Operation ID: startAgentConnection

Request body fields

Field	Description
name (optional, string)	minLength: 1 maxLength: 80
agent_type (optional, string)	pattern: "^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$"
platform (optional, string)	maxLength: 80
version (optional, string)	maxLength: 40
capabilities (optional, array)	The installation's requested capability areas. Omitted requests all six. Unknown, duplicate, or empty lists are invalid_request.
recipient_public_key (required, X25519PublicJWK)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://api.screenrig.ai/api/v1/agent-connections'

Responses

Status	Meaning	Body and headers
201	Temporary connection authority and safe dashboard approval URL. The temporary credential is never placed in the URL.	AgentConnectionStart (application/json); headers: Cache-Control, Referrer-Policy
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)

GET/api/v1/agent-connections/{id}/events¶

Stream Agent Connection Events

Status-only SSE authenticated by the temporary ScreenRig-Agent-Connect credential in Authorization. Data contains only AgentConnection metadata and closes on approved, denied, connected, expired, or cancelled. It never contains a bearer, credential envelope, nonce, cookie, or project identifier.

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/api/v1/agent-connections/RESOURCE_ID/events'

Responses

Status	Meaning	Body and headers
200	Status-only connection SSE.	string (text/event-stream); headers: Cache-Control, X-Accel-Buffering
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/v1/agent-connections/{id}/credential¶

Collect Agent Credential

Collects the exact replay-safe credential envelope after approval. The temporary connection bearer authenticates the request, while X25519, HKDF-SHA-256, and AES-256-GCM bind the envelope to the recipient key supplied at connection creation. No plaintext project bearer is returned by this route.

Approval starts a fresh 24-hour delivery window so the recipient can resume after being offline. The envelope is deleted on activation, cancellation, or expiry.

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/v1/agent-connections/RESOURCE_ID/credential'

Responses

Status	Meaning	Body and headers
200	Recipient-bound credential envelope.	AgentCredentialCollection (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)
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)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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/v1/agents/self/activate¶

Activate Current Agent

Proves successful envelope decryption and durable local storage by presenting the pending bearer. Atomically activates both the agent and token, deletes the delivery envelope, and is replay-safe with the now-active bearer. It takes no body and does not debit the API meter.

Authentication: pendingAgentBearer
Request body: none
Operation ID: activateCurrentAgent

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/agents/self/activate'

Responses

Status	Meaning	Body and headers
200	Active agent.	Agent (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)
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)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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/v1/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

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/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/v1/agents/self/disconnect¶

Disconnect Current Agent

Revokes the calling agent and its bearer without deleting the project or 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.

Authentication: revocableAgentBearer
Request body: AgentDisconnectRequest
Operation ID: disconnectCurrentAgent

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/v1/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)

Applications and operations

GET/api/v1/applications¶

List Applications

Authentication: projectBearer
Request body: none
Operation ID: listApplications

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/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/v1/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
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://api.screenrig.ai/api/v1/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/v1/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
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/v1/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/v1/applications/{id}¶

Get Application

Authentication: projectBearer
Request body: none
Operation ID: getApplication

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: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/v1/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)

DELETE/api/v1/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
Request body: none
Operation ID: deleteApplication

Parameters

Name	Send in	Required?	Description
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/v1/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; Problem.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/v1/operations/{id}¶

Get Operation

Authentication: projectBearer
Request body: none
Operation ID: getOperation

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: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/v1/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/v1/operations/{id}/cancel¶

Cancel Operation

Authentication: projectBearer
Request body: none
Operation ID: cancelOperation

Parameters

Name	Send in	Required?	Description
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/v1/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/v1/media¶

List Media

Authentication: projectBearer
Request body: none
Operation ID: listMedia

Parameters

Name	Send in	Required?	Description
tag	query	optional	Exact media tag. Untagged objects are omitted when this filter is present.
primitive	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/v1/media'

Responses

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

POST/api/v1/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/v1/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 at least 1 credit.

Empty selected-vendor configuration returns not_ready. Project bearer only. One in-flight generation per project; further parallelism is rate_limited.

Authentication: projectBearer
Request body: MediaGenerationRequest
Operation ID: createMediaGeneration

Parameters

Name	Send in	Required?	Description
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]' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/v1/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/v1/media/{id}/content. GET /api/v1/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)

POST/api/v1/media/uploads¶

Create Media Upload

Authentication: projectBearer
Request body: MediaUploadDeclaration
Operation ID: createMediaUpload

Parameters

Name	Send in	Required?	Description
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]' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/v1/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/v1/media/uploads/{id}/commit¶

Commit Media Upload

Authentication: projectBearer
Request body: MediaCommit
Operation ID: commitMediaUpload

Parameters

Name	Send in	Required?	Description
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]' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/v1/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)

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

Get Media

Authentication: projectBearer
Request body: none
Operation ID: getMedia

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: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/v1/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/v1/media/{id}¶

Patch Media

Authentication: projectBearer
Request body: MediaTagPatch
Operation ID: patchMedia

Parameters

Name	Send in	Required?	Description
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
tag (required, inline)	Replacement tag or null to clear 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 PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/v1/media/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Ready media with the updated tag. Matching by:tag playlists rematerialize in the same transaction.	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/v1/media/{id}¶

Delete Media

Authentication: projectBearer
Request body: none
Operation ID: deleteMedia

Parameters

Name	Send in	Required?	Description
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/v1/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/v1/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.

Authentication: projectBearer
Request body: none
Operation ID: exportMediaContent

Parameters

Name	Send in	Required?	Description
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]' 'https://api.screenrig.ai/api/v1/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
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/v1/media/{id}/content¶

Head Media Content

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

Authentication: projectBearer
Request body: none
Operation ID: headMediaContent

Parameters

Name	Send in	Required?	Description
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]' 'https://api.screenrig.ai/api/v1/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
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/v2/playlists¶

List Playlists V2

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

Authentication: projectBearer
Request body: none
Operation ID: listPlaylistsV2

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v2/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/v2/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
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)
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://api.screenrig.ai/api/v2/playlists'

Responses

Status	Meaning	Body and headers
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/v2/playlists/{id}¶

Get Playlist V2

Authentication: projectBearer
Request body: none
Operation ID: getPlaylistV2

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: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/v2/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/v2/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
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)
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://api.screenrig.ai/api/v2/playlists/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
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/v2/playlists/{id}¶

Delete Playlist V2

Authentication: projectBearer
Request body: none
Operation ID: deletePlaylistV2

Parameters

Name	Send in	Required?	Description
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/v2/playlists/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
204	Playlist tombstoned.	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/v1/playlists¶

List Playlists

Lists playlists. Authenticated /api/v1 control-plane read; costs 1 credit.

Authentication: projectBearer
Request body: none
Operation ID: listPlaylists

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/playlists'

Responses

Status	Meaning	Body and headers
200	Playlists	PlaylistList (application/json); headers: ScreenRig-Credits-Remaining, ScreenRig-Credits-Reset, ScreenRig-Credits-Included
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)

POST/api/v1/playlists¶

Create Playlist

Authentication: projectBearer
Request body: PlaylistWrite
Operation ID: createPlaylist

Parameters

Name	Send in	Required?	Description
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)
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://api.screenrig.ai/api/v1/playlists'

Responses

Status	Meaning	Body and headers
201	Playlist	Playlist (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/v1/playlists/{id}¶

Get Playlist

Authentication: projectBearer
Request body: none
Operation ID: getPlaylist

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: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/v1/playlists/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Playlist	Playlist (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/v1/playlists/{id}¶

Update Playlist

Authentication: projectBearer
Request body: PlaylistWrite
Operation ID: updatePlaylist

Parameters

Name	Send in	Required?	Description
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)
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://api.screenrig.ai/api/v1/playlists/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Playlist	Playlist (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/v1/playlists/{id}¶

Delete Playlist

Authentication: projectBearer
Request body: none
Operation ID: deletePlaylist

Parameters

Name	Send in	Required?	Description
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/v1/playlists/RESOURCE_ID'

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)

Screens

GET/api/v1/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.

Authentication: projectBearer
Request body: none
Operation ID: listScreens

Parameters

Name	Send in	Required?	Description
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.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/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/v1/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.

Authentication: projectBearer
Request body: PairScreen
Operation ID: pairScreen

Parameters

Name	Send in	Required?	Description
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]' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/v1/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/v1/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
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/v1/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/v1/screens/actions¶

Apply Screen Actions

Applies one action to many screens in one request. The selector is either by ids (1 to 500 unique screen ids, any state; each id is resolved like its single-screen route) or by tag (every active screen whose tags contain the exact tag, at most 500, else invalid_request).

Each screen runs the same code path as its single-screen route, so revisions, events, and runtime signalling are identical: assign is PATCH /api/v1/screens/{id} with playlist_id, reload is POST /api/v1/screens/{id}/reload, toast is POST /api/v1/screens/{id}/toast, and set_tags, add_tags, and remove_tags edit Screen.tags (add then remove, applied against the stored set inside the screen transaction).

The answer is 200 with one result per selected screen in selector order; a failed screen carries the problem its single-screen request would have answered, so partial success is normal and not an error. A malformed selector or action fails the whole request before any screen is touched.

The request is one metered API request regardless of fan-out. reload and toast share the single-screen budgets: the fan-out is charged all at once against reload-project or toast-project (600 per minute per project), and a fan-out larger than what remains in the window is refused whole with 429 rate_limited before any screen is touched; each screen then spends its own reload-screen (6 per minute) or toast-screen (20 per minute) unit, and a screen over it fails alone with a per-screen rate_limited problem.

Idempotency-Key is optional.

The resolved screen list is pinned under the key before fan-out, so a retry after an interrupted request fans out to the same screens even when a tag edit changed what the selector matches, replays finished screens without repeating their side effects or spending budget, and completes the rest; an exact retry of a completed request returns the recorded answer for twenty-four hours.

The action object is discriminated by type; new action types are additive. takeover is POST /api/v1/screens/{id}/takeover (playlist_id, until, reason; until is validated once against the request clock before fan-out), takeover_clear is DELETE /api/v1/screens/{id}/takeover, and set_playlist_schedule is PUT /api/v1/screens/{id}/playlist-schedule with the entries normalized once before fan-out (so every screen stores the same entry ids), and clear_playlist_schedule is DELETE /api/v1/screens/{id}/playlist-schedule.

A takeover's until is checked against the clock only when the Idempotency-Key has no fleet record, so an exact retry replays after until has passed.

These four share the single-screen screen-control budgets the way reload and toast share theirs: the fan-out is charged all at once against screen-control-project (600 per minute per project), refused whole with 429 rate_limited when larger than what remains, and each screen spends its own screen-control-screen unit (20 per minute), failing alone with rate_limited when over it. reboot, display, display_clear, set_display_schedule, and clear_display_schedule run DELETE /api/v1/screens/{id}/display for display_clear and POST /api/v1/screens/{id}/reboot, POST /api/v1/screens/{id}/display, and PUT and DELETE /api/v1/screens/{id}/display-schedule, charging reboot-project (600 per minute) with reboot-screen (2 per 10 minutes), or display-project (600 per minute) with display-screen (10 per minute), the same way.

Authentication: projectBearer
Request body: ScreenActionRequest
Operation ID: applyScreenActions

Parameters

Name	Send in	Required?	Description
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
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/v1/screens/actions'

Responses

Status	Meaning	Body and headers
200	Per-screen results. Partial success is a normal answer.	ScreenActionResult (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)
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/v1/screens/{id}¶

Get Screen

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

Authentication: projectBearer
Request body: none
Operation ID: getScreen

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: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/v1/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/v1/screens/{id}¶

Update Screen

Authentication: projectBearer
Request body: ScreenPatch
Operation ID: updateScreen

Parameters

Name	Send in	Required?	Description
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)	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://api.screenrig.ai/api/v1/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)

DELETE/api/v1/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. This route does not grant administrative break-glass permission to release native enrollment.

Authentication: projectBearer
Request body: none
Operation ID: deleteScreen

Parameters

Name	Send in	Required?	Description
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/v1/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; Problem.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/v1/screens/{id}/public-id/rotate¶

Rotate Screen Public Id

Authentication: projectBearer
Request body: none
Operation ID: rotateScreenPublicId

Parameters

Name	Send in	Required?	Description
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/v1/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/v1/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
Request body: none
Operation ID: confirmScreenRecovery

Parameters

Name	Send in	Required?	Description
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]' 'https://api.screenrig.ai/api/v1/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/v1/screens/{id}/archive¶

Archive Screen

Hides the screen from the default list and darkens the live glass. Does not unbind the player public key. Releases screen_count quota.

Authentication: projectBearer
Request body: none
Operation ID: archiveScreen

Parameters

Name	Send in	Required?	Description
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/v1/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/v1/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.

Authentication: projectBearer
Request body: none
Operation ID: unarchiveScreen

Parameters

Name	Send in	Required?	Description
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/v1/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/v1/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
Request body: none
Operation ID: reloadScreen

Parameters

Name	Send in	Required?	Description
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/v1/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/v1/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
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/v1/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/v1/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
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
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/v1/screens/RESOURCE_ID/playlist-schedule'

Responses

Status	Meaning	Body and headers
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/v1/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
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/v1/screens/RESOURCE_ID/playlist-schedule'

Responses

Status	Meaning	Body and headers
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/v1/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
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
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/v1/screens/RESOURCE_ID/takeover'

Responses

Status	Meaning	Body and headers
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/v1/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
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/v1/screens/RESOURCE_ID/takeover'

Responses

Status	Meaning	Body and headers
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/v1/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
Request body: none
Operation ID: rebootScreen

Parameters

Name	Send in	Required?	Description
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/v1/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/v1/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/v1/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
Request body: ScreenDisplayWrite
Operation ID: setScreenDisplay

Parameters

Name	Send in	Required?	Description
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]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/v1/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/v1/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
Request body: none
Operation ID: clearScreenDisplay

Parameters

Name	Send in	Required?	Description
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/v1/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/v1/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
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/v1/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/v1/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
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/v1/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/v1/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
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/v1/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/v1/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
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/v1/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/v1/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
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/v1/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/v1/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.

Authentication: projectBearer
Request body: none
Operation ID: getScreenScreenshot

Parameters

Name	Send in	Required?	Description
id	path	required
capture_id	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/v1/screens/RESOURCE_ID/screenshot'

Responses

Status	Meaning	Body and headers
200	Current ready still WebP.	string (image/webp); headers: Content-Type, Content-Length, ETag, Cache-Control, Content-Disposition
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/v1/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
Request body: none
Operation ID: requestScreenScreenshot

Parameters

Name	Send in	Required?	Description
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/v1/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/v1/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
Request body: none
Operation ID: getScreenScreenshotStatus

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: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/v1/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)

Private advertising networks and campaigns

GET/api/v1/advertising/network¶

Get Advertising Network

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

Authentication: projectBearer
Request body: none
Operation ID: getAdvertisingNetwork

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/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/v1/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
Request body: AdvertisingNetworkCreate
Operation ID: createAdvertisingNetwork

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]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/v1/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/v1/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
Request body: AdvertisingRate
Operation ID: setAdvertisingDefaultRate

Parameters

Name	Send in	Required?	Description
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]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/v1/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/v1/advertising/inventory¶

List Advertising Inventory

The calling seller's opted-in inventory.

Authentication: projectBearer
Request body: none
Operation ID: listAdvertisingInventory

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/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/v1/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
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://api.screenrig.ai/api/v1/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/v1/advertising/slots¶

List Advertising Slots

Authentication: projectBearer
Request body: none
Operation ID: listAdvertisingSlots

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/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/v1/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
Request body: AdvertisingSlotWrite
Operation ID: createAdvertisingSlot

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]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/v1/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/v1/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
Request body: AdvertisingSlotWrite
Operation ID: updateAdvertisingSlot

Parameters

Name	Send in	Required?	Description
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]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/v1/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/v1/advertising/memberships¶

List Advertising Memberships

Authentication: projectBearer
Request body: none
Operation ID: listAdvertisingMemberships

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/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/v1/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
Request body: AdvertisingMembershipScope
Operation ID: updateAdvertisingMembership

Parameters

Name	Send in	Required?	Description
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]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/v1/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/v1/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
Request body: none
Operation ID: revokeAdvertisingMembership

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: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/v1/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/v1/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
Request body: none
Operation ID: listAdvertisingJoinedNetworks

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/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/v1/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
Request body: none
Operation ID: listAdvertisingJoinedInventory

Parameters

Name	Send in	Required?	Description
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]' 'https://api.screenrig.ai/api/v1/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/v1/advertising/creatives¶

List Advertising Creatives

Authentication: projectBearer
Request body: none
Operation ID: listAdvertisingCreatives

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/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/v1/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
Request body: AdvertisingCreativeCreate
Operation ID: createAdvertisingCreative

Parameters

Name	Send in	Required?	Description
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]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/v1/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/v1/advertising/creatives/{id}¶

Get Advertising Creative

Authentication: projectBearer
Request body: none
Operation ID: getAdvertisingCreative

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: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/v1/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/v1/advertising/campaigns¶

List Advertising Campaigns

Authentication: projectBearer
Request body: none
Operation ID: listAdvertisingCampaigns

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/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/v1/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
Request body: AdvertisingCampaignDraft
Operation ID: createAdvertisingCampaign

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]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/v1/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/v1/advertising/campaigns/{id}¶

Get Advertising Campaign

Authentication: projectBearer
Request body: none
Operation ID: getAdvertisingCampaign

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: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/v1/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/v1/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
Request body: AdvertisingCampaignDraft
Operation ID: updateAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
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]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/v1/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/v1/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
Request body: none
Operation ID: quoteAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
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]' 'https://api.screenrig.ai/api/v1/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/v1/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
Request body: AdvertisingQuoteAccept
Operation ID: activateAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
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]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/v1/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/v1/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
Request body: none
Operation ID: pauseAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
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]' 'https://api.screenrig.ai/api/v1/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/v1/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
Request body: none
Operation ID: resumeAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
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]' 'https://api.screenrig.ai/api/v1/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/v1/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
Request body: AdvertisingQuoteAccept
Operation ID: acceptAdvertisingRates

Parameters

Name	Send in	Required?	Description
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]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/v1/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/v1/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
Request body: none
Operation ID: listAdvertisingReviews

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/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/v1/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.

Authentication: projectBearer
Request body: none
Operation ID: approveAdvertisingReview

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: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/v1/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/v1/advertising/reviews/{id}/reject¶

Reject Advertising Review

Authentication: projectBearer
Request body: AdvertisingReviewRejection
Operation ID: rejectAdvertisingReview

Parameters

Name	Send in	Required?	Description
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]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/v1/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/v1/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
Request body: none
Operation ID: getAdvertisingSpend

Parameters

Name	Send in	Required?	Description
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]' 'https://api.screenrig.ai/api/v1/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/v1/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.

Authentication: projectBearer
Request body: none
Operation ID: getAdvertisingDelivery

Parameters

Name	Send in	Required?	Description
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]' 'https://api.screenrig.ai/api/v1/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/v1/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
Request body: none
Operation ID: getAdvertisingReview

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: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/v1/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/v1/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.

Authentication: projectBearer
Request body: none
Operation ID: getAdvertisingReviewContent

Parameters

Name	Send in	Required?	Description
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 --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/v1/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
206	One standards-correct byte range.	no body; headers: 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/v1/advertising/reviews/{id}/content¶

Head Advertising Review Content

Authentication: projectBearer
Request body: none
Operation ID: headAdvertisingReviewContent

Parameters

Name	Send in	Required?	Description
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://api.screenrig.ai/api/v1/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)

Comments

GET/api/v1/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/v1 control-plane read; costs 1 credit.

Authentication: projectBearer
Request body: none
Operation ID: getScreenComments

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: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/v1/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/v1/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
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/v1/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/v1/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
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/v1/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/v1/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/v1 control-plane read; costs 1 credit.

Authentication: projectBearer
Request body: none
Operation ID: getPlaylistComments

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: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/v1/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/v1/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
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/v1/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/v1/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
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/v1/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/v1/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/v1 control-plane read; costs 1 credit.

Authentication: projectBearer
Request body: none
Operation ID: getPlaylistPageComments

Parameters

Name	Send in	Required?	Description
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/v1/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/v1/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
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/v1/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/v1/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
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/v1/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)

Application key/value storage

GET/api/v1/applications/{application_id}/kv¶

List KV

Authentication: projectBearer
Request body: none
Operation ID: listKV

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 --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/v1/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/v1/applications/{application_id}/kv/{key}¶

Get KV

Authentication: projectBearer
Request body: none
Operation ID: getKV

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 --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/v1/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/v1/applications/{application_id}/kv/{key}¶

Put KV

Authentication: projectBearer
Request body: KVWrite
Operation ID: putKV

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 --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/v1/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/v1/applications/{application_id}/kv/{key}¶

Delete KV

Authentication: projectBearer
Request body: none
Operation ID: deleteKV

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 --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/v1/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)

Durable project events

GET/api/v1/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.

Authentication: projectBearer
Request body: none
Operation ID: listEvents

Parameters

Name	Send in	Required?	Description
after	query	optional
limit	query	optional	Page size. A value outside 1-200 is refused with invalid_request and an errors[] member whose field is limit.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/events'

Responses

Status	Meaning	Body and headers
200	Durable events	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/api/v1/events/stream¶

Stream Events

Replayable project listen 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.

Authentication: projectBearer
Request body: none
Operation ID: streamEvents

Parameters

Name	Send in	Required?	Description
after	query	optional
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]' 'https://api.screenrig.ai/api/v1/events/stream'

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/v1/webhooks¶

List Webhooks

Lists the project's webhooks, oldest first (at most 10). The signing secret is never returned here.

Authentication: projectBearer
Request body: none
Operation ID: listWebhooks

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/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/v1/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
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/v1/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://api.screenrig.ai/api/v1/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/v1/webhooks/{id}¶

Get Webhook

Authentication: projectBearer
Request body: none
Operation ID: getWebhook

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: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/v1/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/v1/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
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/v1/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://api.screenrig.ai/api/v1/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; Problem.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/v1/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
Request body: none
Operation ID: deleteWebhook

Parameters

Name	Send in	Required?	Description
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/v1/webhooks/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
204	Deleted.	no body; headers: Cache-Control
412	revision_conflict — If-Match is stale; Problem.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/v1/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
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/v1/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; Problem.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/v1/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
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/v1/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/v1/webhooks/{id}/deliveries¶

List Webhook Deliveries

The webhook's delivery log, newest event first. One row per (webhook, event); retries update the row. 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
Request body: none
Operation ID: listWebhookDeliveries

Parameters

Name	Send in	Required?	Description
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]' 'https://api.screenrig.ai/api/v1/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)

Playback aggregates

GET/api/v1/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
Request body: none
Operation ID: listPlaybackAggregates

Parameters

Name	Send in	Required?	Description
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]' 'https://api.screenrig.ai/api/v1/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/v1/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, and tag (a screen tag the screen carried when the play was received) filter.

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.

A later page never repeats or skips a row that existed when the earlier page was read. format=csv (or Accept text/csv without application/json) streams every play from cursor to the end of the range as CSV (PlaybackPlayCsv); 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, at least 30 days.

Authentication: projectBearer
Request body: none
Operation ID: listPlaybackPlays

Parameters

Name	Send in	Required?	Description
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
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.
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]' 'https://api.screenrig.ai/api/v1/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)

Feedback: bugs and feature requests

GET/api/v1/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

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/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/v1/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.

Never place credentials, cookies, Authorization headers, completion nonces, signed URLs, or object keys in title, body, or context; recognizable ScreenRig credential material is rejected with invalid_request and is not stored.

Authentication: projectBearer
Request body: FeedbackWrite
Operation ID: reportBug

Parameters

Name	Send in	Required?	Description
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/v1/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)
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/v1/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

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/v1/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/v1/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.

Authentication: projectBearer
Request body: FeedbackWrite
Operation ID: requestFeature

Parameters

Name	Send in	Required?	Description
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/v1/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)
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)

Homepage browser handoff

POST/api/v1/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
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/v1/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/runtime/v1/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/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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)

POST/runtime/v1/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/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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
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/runtime/v1/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/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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)
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/runtime/v1/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/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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/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/runtime/v1/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/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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/runtime/v1/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/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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/runtime/v1/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/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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)
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)
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/runtime/v1/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/runtime/v1/sessions'

Responses

Status	Meaning	Body and headers
201	Read-only runtime session cookie	RuntimeSession (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/runtime/v1/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/runtime/v1/device-sessions'

Responses

Status	Meaning	Body and headers
201	Paired runtime session	RuntimeSession (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/runtime/v1/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.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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
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/runtime/v1/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/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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)
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/runtime/v1/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/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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)
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
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/runtime/v1/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/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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)
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/runtime/v1/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 24-hour ScreenRig-Session. 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/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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)
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
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/runtime/v1/native/identity/reset¶

Reset Native Identity

The on-player reset, invoked by an explicit confirmed operator action on the device. 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. A fresh signed reset safely retries a lost response. No project bearer.

Cookies are neither accepted nor set. A missing local key or network error is not a reset (docs/player-compatibility.md §5.1).

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/runtime/v1/native/identity/reset'

Responses

Status	Meaning	Body and headers
204	Reset recorded: the bound screen archived with the key kept, or the 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; no Set-Cookie.	no body; 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)
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)

Runtime manifest, reports, and events

POST/runtime/v1/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/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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/runtime/v1/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 /runtime/v1/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/runtime/v1/chrome'

Responses

Status	Meaning	Body and headers
200	Runtime chrome	RuntimeChrome (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/runtime/v1/manifest¶

Get Runtime Manifest

Resolved player manifest. Projection is fail-safe; invalid pages and primitives are omitted and listed in diagnostics. 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/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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/runtime/v1/events¶

Stream Runtime Events

Authentication: runtimeCookie OR nativeSessionAuthorization
Request body: none
Operation ID: streamRuntimeEvents

Parameters

Name	Send in	Required?	Description
after	query	optional
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/runtime/v1/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. Audience-only gaps emit payload-free stream.cursor frames.

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, and the per-screen commands player.reboot and player.display (docs/player-compatibility.md §6.5), never delivered past details.expires_at.

Every other type stops at the scan, and stream.cursor advances the cursor past it. 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 retry: 3000; 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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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/runtime/v1/reports¶

Create Runtime Report

Authentication: pairedRuntimeCookie OR nativeSessionAuthorization
Request body: RuntimeReport
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/runtime/v1/reports'

Responses

Status	Meaning	Body and headers
202	Accepted. manifest.activated is committed before this response and is idempotent for the current active revision. playback.media_started upserts the daily aggregate for an image or video start and stores one per-play record (GET /api/v1/playback/plays) in the same transaction before this response; playback.video_started reports a video start using the same aggregation and play record. playback.application_started verifies the reported page, primitive, and release as the exact application primitive of the session screen's current grant at the reported manifest revision, stores one per-play record (GET /api/v1/playback/plays) for the application start, and advances the release's last_used_at in the same transaction. 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	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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/runtime/v1/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/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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)
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)

GET/runtime/v2/manifest¶

Get Runtime Manifest V2

Versioned runtime manifest that may carry adslot pages. Requires the declared adslot-v1 capability. schemaVersion is 3. The root keys stay camelCase; adslot page keys stay id, type, adslot_id and optional snake_case visibility.

Authentication: pairedRuntimeCookie OR nativeSessionAuthorization
Request body: none
Operation ID: getRuntimeManifestV2

Parameters

Name	Send in	Required?	Description
manifest_revision	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://play.screenrig.ai/runtime/v2/manifest'

Responses

Status	Meaning	Body and headers
200	Resolved player manifest.	RuntimeManifestV2 (application/json)
403	forbidden - the session lacks the adslot capability.	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/runtime/v1/adslots/resolve¶

Resolve Adslots

Resolves up to 16 server-verified page occurrences. A fresh candidate is atomically priced, budget-checked and reserved against the campaign-wide pricing fence. No eligible or affordable campaign is a successful empty result with no content and no debit; it is never a payment challenge.

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/runtime/v1/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.	Problem (application/problem+json)
409	resource_conflict - a candidate was reused with a different request hash.	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/runtime/v1/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/runtime/v1/adslots/events'

Responses

Status	Meaning	Body and headers
200	Per-event outcomes.	RuntimeAdslotEventResponse (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/runtime/v1/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) 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/v1/screens until the first accepted report. ScreenPatch cannot write it.

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/runtime/v1/observation'

Responses

Status	Meaning	Body and headers
204	Observation stored as the current surfaces array.	no body; 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)
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)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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/runtime/v1/health¶

Put Runtime Health

Reports device health for the paired session's screen. Send one on session start and every five minutes.

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 /runtime/v1/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/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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)
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)

PUT/runtime/v1/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 /runtime/v1/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/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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)
409	resource_conflict - manifest_revision is not the screen's desired or active revision. The report is not stored.	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)

PUT/runtime/v1/screen-label¶

Put Runtime Screen Label

Renames the screen bound to the paired runtime session. It is the same rename as PATCH /api/v1/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 /runtime/v1/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/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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)
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/runtime/v1/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 /runtime/v1/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/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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)

POST/runtime/v1/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/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Runtime application K/V

GET/runtime/v1/apps/{application_id}/kv¶

List Runtime KV

Lists metadata for the application primitive named by the current manifest. Requires the HttpOnly runtime session and the parent-only ScreenRig-Primitive-Capability handle issued on the application primitive.

Handles expire after five minutes and are refreshed by fetching the current runtime manifest; uploaded frames never receive the handle and must use the validated parent SDK bridge.

Authentication: runtimeCookie + primitiveCapability OR nativeSessionAuthorization + primitiveCapability
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 --header 'ScreenRig-Primitive-Capability: PRIMITIVE_CAPABILITY' --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/runtime/v1/apps/APPLICATION_ID/kv'

Responses

Status	Meaning	Body and headers
200	Manifest-authorized application KV	RuntimeKVList (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/runtime/v1/apps/{application_id}/kv/{key}¶

Get Runtime KV

Authentication: runtimeCookie + primitiveCapability OR nativeSessionAuthorization + primitiveCapability
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 --header 'ScreenRig-Primitive-Capability: PRIMITIVE_CAPABILITY' --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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/runtime/v1/apps/{application_id}/kv/{key}¶

Put Runtime KV

Authentication: pairedRuntimeCookie + primitiveCapability OR nativeSessionAuthorization + primitiveCapability
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 --header 'ScreenRig-Primitive-Capability: PRIMITIVE_CAPABILITY' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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/runtime/v1/apps/{application_id}/kv/{key}¶

Delete Runtime KV

Authentication: pairedRuntimeCookie + primitiveCapability OR nativeSessionAuthorization + primitiveCapability
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 --header 'ScreenRig-Primitive-Capability: PRIMITIVE_CAPABILITY' --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/runtime/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

Protected content and release assets

GET/content/v1/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/content/v1/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.	Problem (application/problem+json)
410	decision expired or otherwise not servable.	Problem (application/problem+json)
416	invalid_range.	Problem (application/problem+json); headers: Content-Range, Accept-Ranges
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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/content/v1/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/content/v1/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. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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/content/v1/manifests/{manifest_revision}/media/{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/content/v1/manifests/MANIFEST_REVISION/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.	Problem (application/problem+json); headers: Content-Range, Accept-Ranges
429	Per-client, screen, or project protected-media egress limit exceeded.	Problem (application/problem+json); headers: Retry-After
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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/content/v1/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/content/v1/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.	Problem (application/problem+json); headers: Content-Range, Accept-Ranges
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)

HEAD/content/v1/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/content/v1/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. 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/{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

GET/dashboard/v1/invitations¶

List Dashboard Invitations

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardInvitations

Parameters

Name	Send in	Required?
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 --cookie cookies.txt --cookie-jar cookies.txt 'https://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/invitations¶

Create Dashboard Invitations

Authentication: dashboardSession
Request body: InvitationCreate
Operation ID: createDashboardInvitations

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/invitations/{id}/revoke¶

Revoke Dashboard Invitation

Revokes an outstanding invitation. An accepted invitation returns invitation_consumed.

Authentication: dashboardSession
Request body: none
Operation ID: revokeDashboardInvitation

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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/sign-in-resets¶

Request Dashboard Sign In Reset

Authentication: none
Request body: SignInResetRequest
Operation ID: requestDashboardSignInReset

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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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.

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)

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/session/project¶

Switch Dashboard Project

Switches to one of the person’s projects and updates its last-used time. A project outside the person’s memberships 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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/projects¶

List Dashboard Projects

Lists the person’s project memberships.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardProjects

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/projects'

Responses

Status	Meaning	Body and headers
200	Lists the person’s project memberships..	DashboardProjectList (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/dashboard/v1/members¶

List Dashboard Members

Lists members of the current project without their private email addresses. Every member has equal authority; member removal is not available.

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://dashboard.screenrig.ai/dashboard/v1/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)

GET/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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 /dashboard/v1/me/reauthentications). Without a current reauthentication the answer is reauthentication_required.

On success the response is 204 and the dashboard session cookie is cleared.

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://dashboard.screenrig.ai/dashboard/v1/me'

Responses

Status	Meaning	Body and headers
204	Person deleted and dashboard session cookie cleared.	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/dashboard/v1/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"
subject_id (optional, string)	The subject the reauthentication binds to. kind account_delete requires the signed-in person's user id. 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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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.

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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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)

GET/dashboard/v1/advertising/reviews/{id}¶

Get Dashboard Advertising Review

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardAdvertisingReview

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://dashboard.screenrig.ai/dashboard/v1/advertising/reviews/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Review and its creative.	AdvertisingReviewDetail (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/dashboard/v1/advertising/reviews/{id}/content¶

Get Dashboard Advertising Review Content

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardAdvertisingReviewContent

Parameters

Name	Send in	Required?	Description
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://dashboard.screenrig.ai/dashboard/v1/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
206	One standards-correct byte range.	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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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.

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://dashboard.screenrig.ai/dashboard/v1/logout'

Responses

Status	Meaning	Body and headers
204	Session row deleted and session cookie expired.	no body; headers: Cache-Control, Set-Cookie
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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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 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.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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 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.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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 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.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/project¶

Get Dashboard Project

Returns the current project’s name, status, unverified contact address, usage, limits, retention, and available credit snapshot. The contact address is not a login credential. No current project returns no_project.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardProject

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/project'

Responses

Status	Meaning	Body and headers
200	Project status, unverified contact address, enforced limits, usage, retention, and public whole-credit state.	DashboardProject (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)

PATCH/dashboard/v1/project¶

Update Dashboard Project

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

Authentication: dashboardSession
Request body: ProjectPatch
Operation ID: updateDashboardProject

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://dashboard.screenrig.ai/dashboard/v1/project'

Responses

Status	Meaning	Body and headers
200	Renames the current project.	DashboardProject (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/dashboard/v1/project/capabilities¶

Get Dashboard Capabilities

The session project's plan, independent advertiser/screens flags with their revision, and the derived effective capability set. Identical body to the project-bearer route.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardCapabilities

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/project/capabilities'

Responses

Status	Meaning	Body and headers
200	Project capabilities.	ProjectCapabilities (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/dashboard/v1/billing/balance¶

Get Dashboard Billing Balance

Source-aware balance snapshot for the session project. All millicredit amounts are canonical decimal strings. It is a snapshot, not authority to pay.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardBillingBalance

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/billing/statement¶

Get Dashboard Billing Statement

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardBillingStatement

Parameters

Name	Send in	Required?	Description
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://dashboard.screenrig.ai/dashboard/v1/billing/statement'

Responses

Status	Meaning	Body and headers
200	Statement page.	BillingStatement (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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/billing/topups¶

Create Dashboard Topup

Unavailable. Card checkout, tax collection and cash movement are not shipped; the route answers billing_unavailable 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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/billing/topups/{id}/checkout¶

Checkout Dashboard Topup

Unavailable. 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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/billing/withdrawal-quotes¶

Create Dashboard Withdrawal Quote

Unavailable. Cash withdrawal is not shipped.

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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/billing/withdrawals¶

Create Dashboard Withdrawal

Unavailable. Cash withdrawal is not shipped; 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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/billing/payout-onboarding¶

Start Dashboard Payout Onboarding

Unavailable. 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://dashboard.screenrig.ai/dashboard/v1/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)

GET/dashboard/v1/advertising/network¶

Get Dashboard Advertising Network

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardAdvertisingNetwork

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/advertising/network¶

Create Dashboard Advertising Network

Authentication: dashboardSession
Request body: AdvertisingNetworkCreate
Operation ID: createDashboardAdvertisingNetwork

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 --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/advertising/network/rate¶

Set Dashboard Advertising Default Rate

Authentication: dashboardSession
Request body: AdvertisingRate
Operation ID: setDashboardAdvertisingDefaultRate

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://dashboard.screenrig.ai/dashboard/v1/advertising/network/rate'

Responses

Status	Meaning	Body and headers
200	Updated 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)

GET/dashboard/v1/advertising/inventory¶

List Dashboard Advertising Inventory

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardAdvertisingInventory

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/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)

POST/dashboard/v1/advertising/inventory/{screen_id}¶

Put Dashboard Advertising Inventory

Authentication: dashboardSession
Request body: AdvertisingInventoryWrite
Operation ID: putDashboardAdvertisingInventory

Parameters

Name	Send in	Required?	Description
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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/advertising/slots¶

List Dashboard Advertising Slots

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardAdvertisingSlots

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/advertising/slots¶

Create Dashboard Advertising Slot

Authentication: dashboardSession
Request body: AdvertisingSlotWrite
Operation ID: createDashboardAdvertisingSlot

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 --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://dashboard.screenrig.ai/dashboard/v1/advertising/slots'

Responses

Status	Meaning	Body and headers
201	Slot.	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/dashboard/v1/advertising/slots/{id}¶

Update Dashboard Advertising Slot

Authentication: dashboardSession
Request body: AdvertisingSlotWrite
Operation ID: updateDashboardAdvertisingSlot

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://dashboard.screenrig.ai/dashboard/v1/advertising/slots/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Updated slot.	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)

GET/dashboard/v1/advertising/memberships¶

List Dashboard Advertising Memberships

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardAdvertisingMemberships

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/advertising/memberships/{id}¶

Update Dashboard Advertising Membership

Authentication: dashboardSession
Request body: AdvertisingMembershipScope
Operation ID: updateDashboardAdvertisingMembership

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://dashboard.screenrig.ai/dashboard/v1/advertising/memberships/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Updated 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)

POST/dashboard/v1/advertising/memberships/{id}/revoke¶

Revoke Dashboard Advertising Membership

Authentication: dashboardSession
Request body: none
Operation ID: revokeDashboardAdvertisingMembership

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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/advertising/networks¶

List Dashboard Advertising Joined Networks

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardAdvertisingJoinedNetworks

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/advertising/networks'

Responses

Status	Meaning	Body and headers
200	Joined networks.	AdvertisingJoinedNetworkList (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/dashboard/v1/advertising/networks/{seller_project_id}/inventory¶

List Dashboard Advertising Joined Inventory

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardAdvertisingJoinedInventory

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt 'https://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/advertising/creatives¶

List Dashboard Advertising Creatives

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardAdvertisingCreatives

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/advertising/creatives¶

Create Dashboard Advertising Creative

Authentication: dashboardSession
Request body: AdvertisingCreativeCreate
Operation ID: createDashboardAdvertisingCreative

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 --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/advertising/creatives/{id}¶

Get Dashboard Advertising Creative

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardAdvertisingCreative

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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/advertising/campaigns¶

List Dashboard Advertising Campaigns

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardAdvertisingCampaigns

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/advertising/campaigns¶

Create Dashboard Advertising Campaign

Authentication: dashboardSession
Request body: AdvertisingCampaignDraft
Operation ID: createDashboardAdvertisingCampaign

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 --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/advertising/campaigns/{id}¶

Get Dashboard Advertising Campaign

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardAdvertisingCampaign

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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/advertising/campaigns/{id}¶

Update Dashboard Advertising Campaign

Authentication: dashboardSession
Request body: AdvertisingCampaignDraft
Operation ID: updateDashboardAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://dashboard.screenrig.ai/dashboard/v1/advertising/campaigns/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Updated 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/dashboard/v1/advertising/campaigns/{id}/quote¶

Quote Dashboard Advertising Campaign

Authentication: dashboardSession
Request body: none
Operation ID: quoteDashboardAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt 'https://dashboard.screenrig.ai/dashboard/v1/advertising/campaigns/RESOURCE_ID/quote'

Responses

Status	Meaning	Body and headers
201	Quote.	AdvertisingQuote (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/dashboard/v1/advertising/campaigns/{id}/activate¶

Activate Dashboard Advertising Campaign

Authentication: dashboardSession
Request body: AdvertisingQuoteAccept
Operation ID: activateDashboardAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://dashboard.screenrig.ai/dashboard/v1/advertising/campaigns/RESOURCE_ID/activate'

Responses

Status	Meaning	Body and headers
200	Active or pending-review 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/dashboard/v1/advertising/campaigns/{id}/pause¶

Pause Dashboard Advertising Campaign

Authentication: dashboardSession
Request body: none
Operation ID: pauseDashboardAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt 'https://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/advertising/campaigns/{id}/resume¶

Resume Dashboard Advertising Campaign

Authentication: dashboardSession
Request body: none
Operation ID: resumeDashboardAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt 'https://dashboard.screenrig.ai/dashboard/v1/advertising/campaigns/RESOURCE_ID/resume'

Responses

Status	Meaning	Body and headers
200	Resumed campaign.	AdvertisingCampaign (application/json)
409	price_change_pending.	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/dashboard/v1/advertising/campaigns/{id}/accept-rates¶

Accept Dashboard Advertising Rates

Authentication: dashboardSession
Request body: AdvertisingQuoteAccept
Operation ID: acceptDashboardAdvertisingRates

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/advertising/reviews¶

List Dashboard Advertising Reviews

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardAdvertisingReviews

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/advertising/reviews/{id}/approve¶

Approve Dashboard Advertising Review

Authentication: dashboardSession
Request body: none
Operation ID: approveDashboardAdvertisingReview

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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/advertising/reviews/{id}/reject¶

Reject Dashboard Advertising Review

Authentication: dashboardSession
Request body: AdvertisingReviewRejection
Operation ID: rejectDashboardAdvertisingReview

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/advertising/reports/spend¶

Get Dashboard Advertising Spend

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardAdvertisingSpend

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt 'https://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/advertising/reports/delivery¶

Get Dashboard Advertising Delivery

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardAdvertisingDelivery

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt 'https://dashboard.screenrig.ai/dashboard/v1/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)

POST/dashboard/v1/media/uploads¶

Create Dashboard Media Upload

Same-origin cookie media upload session. upload_url is omitted; bytes are PUT to /dashboard/v1/media/uploads/{id}/content. Media upload does not require screens capability.

Authentication: dashboardSession
Request body: MediaUploadDeclaration
Operation ID: createDashboardMediaUpload

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 --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://dashboard.screenrig.ai/dashboard/v1/media/uploads'

Responses

Status	Meaning	Body and headers
201	Upload session without a signed URL.	MediaUploadSession (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/dashboard/v1/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://dashboard.screenrig.ai/dashboard/v1/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)

POST/dashboard/v1/media/uploads/{id}/commit¶

Commit Dashboard Media Upload

Authentication: dashboardSession
Request body: MediaCommit
Operation ID: commitDashboardMediaUpload

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
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 --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://dashboard.screenrig.ai/dashboard/v1/media/uploads/RESOURCE_ID/commit'

Responses

Status	Meaning	Body and headers
202	Commit accepted.	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/dashboard/v1/media/generations¶

Create Dashboard Media Generation

Cookie twin of the project media generation request. The same media service and credit pricing apply; screens capability is not required.

Authentication: dashboardSession
Request body: MediaGenerationRequest
Operation ID: createDashboardMediaGeneration

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 --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://dashboard.screenrig.ai/dashboard/v1/media/generations'

Responses

Status	Meaning	Body and headers
201	Generation accepted.	MediaGeneration (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/dashboard/v1/operations/{id}¶

Get Dashboard Operation

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardOperation

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://dashboard.screenrig.ai/dashboard/v1/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)

GET/dashboard/v1/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/v1/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://dashboard.screenrig.ai/dashboard/v1/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)

GET/dashboard/v1/screens¶

List Dashboard Screens

Default list returns pairing_pending and active screens of the session's project. Pass state=archived to list archived screens only. Pass tag to list only screens whose tags contain that exact tag. Tags are read-only on the dashboard.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardScreens

Parameters

Name	Send in	Required?	Description
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.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/screens'

Responses

Status	Meaning	Body and headers
200	Screens	ScreenList (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/dashboard/v1/screens/{id}¶

Get Dashboard Screen

Returns one pairing_pending, active, or archived screen. Authority is the session's project owning the screen; the identifier is not authorization. A screen of any other project is not_found. Deleted screens are not found. There is no dashboard screen create or patch; the dashboard reads, lists, and deletes screens.

Authoring stays in the agent conversation and the CLI.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardScreen

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://dashboard.screenrig.ai/dashboard/v1/screens/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Screen	Screen (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)

DELETE/dashboard/v1/screens/{id}¶

Delete Dashboard Screen

The dashboard twin of DELETE /api/v1/screens/{id} for the session's project. The same revision and idempotency fences apply. Cookie credentials and grants are revoked immediately; the tombstoned row remains for at least 90 days. Native identity-bound screens return screen_archive_required and must be archived instead.

An unknown or other-project screen is not_found.

Authentication: dashboardSession
Request body: none
Operation ID: deleteDashboardScreen

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt 'https://dashboard.screenrig.ai/dashboard/v1/screens/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
204	Screen soft-deleted; its tombstone is retained for at least 90 days.	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)
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)

GET/dashboard/v1/screens/{id}/screenshot¶

Get Dashboard Screen Screenshot

Returns the current ready still WebP for the named screen as first-party same-origin bytes. There is no signed URL and no object key anywhere on this path: a signed URL reaching the dashboard is a defect. Optional capture_id must match the current ready slot.

A named capture_id that elapsed with no upload is screenshot_unavailable, and one replaced by a later request is resource_conflict. Range is not accepted.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardScreenScreenshot

Parameters

Name	Send in	Required?	Description
id	path	required
capture_id	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://dashboard.screenrig.ai/dashboard/v1/screens/RESOURCE_ID/screenshot'

Responses

Status	Meaning	Body and headers
200	Current ready still WebP.	string (image/webp); headers: Content-Type, Content-Length, ETag, Cache-Control, Content-Disposition
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/dashboard/v1/screens/{id}/screenshot¶

Request Dashboard Screen Screenshot

Requests one still screenshot of the named active screen owned by the session's project. It is the cookie sibling of POST /api/v1/screens/{id}/screenshot and shares one server-side slot and one state machine with it.

This route is pending-safe: a request that is not an exact idempotent retry and is made while the slot is pending returns that in-flight capture_id with its expiry unchanged, and starts no second capture.

An exact idempotent retry is answered from its own idempotency record instead, so it returns the capture_id that key first received whatever the slot now holds, and the 202 is the authority on that.

There is one in-flight capture per screen, so concurrent dashboard viewers converge on the same capture instead of competing for the slot, and a repeated request cannot restart the expiry clock. Outside a replay, the idle, ready, and timed_out states each start a fresh capture.

The shared slot machine is unchanged and stays latest-wins for the bearer route; this route reads status first and never takes that replacement path. The current ready slot is kept until a later upload succeeds. The server status machine is the arbiter of the one-in-flight rule. Image bytes never appear on any event stream.

Authentication: dashboardSession
Request body: none
Operation ID: requestDashboardScreenScreenshot

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt --header 'Idempotency-Key: REQUEST_ID' 'https://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/screens/{id}/screenshot/status¶

Get Dashboard Screen Screenshot Status

Returns the screenshot state machine for the named screen owned by the session's project.

It reads the same slot as GET /api/v1/screens/{id}/screenshot/status. 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 identifier reached expires_at with no upload; a client renders screenshot_unavailable inline and backs off.

Timeout is lazy, and a timed-out request does not delete an older ready slot.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardScreenScreenshotStatus

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://dashboard.screenrig.ai/dashboard/v1/screens/RESOURCE_ID/screenshot/status'

Responses

Status	Meaning	Body and headers
200	Screenshot status for this session 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)

POST/dashboard/v1/screens/{id}/reload¶

Reload Dashboard Screen

The dashboard twin of POST /api/v1/screens/{id}/reload: same project fence, same player.reload event, same problems, and the same 202 body.

Authentication: dashboardSession
Request body: none
Operation ID: reloadDashboardScreen

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt 'https://dashboard.screenrig.ai/dashboard/v1/screens/RESOURCE_ID/reload'

Responses

Status	Meaning	Body and headers
202	Accepted. 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)

POST/dashboard/v1/screens/{id}/reboot¶

Reboot Dashboard Screen

The dashboard twin of POST /api/v1/screens/{id}/reboot: same project fence, player.reboot and screen.reboot_requested, reboot_unsupported refusal, budgets, and 202 body.

Authentication: dashboardSession
Request body: none
Operation ID: rebootDashboardScreen

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt 'https://dashboard.screenrig.ai/dashboard/v1/screens/RESOURCE_ID/reboot'

Responses

Status	Meaning	Body and headers
202	Accepted. 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/dashboard/v1/screens/{id}/display¶

Set Dashboard Screen Display

The dashboard twin of POST /api/v1/screens/{id}/display (display on or off now, optional until): same rules, events, budgets, and Screen body. The display schedule stays agent- and CLI-authored.

Authentication: dashboardSession
Request body: ScreenDisplayWrite
Operation ID: setDashboardScreenDisplay

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://dashboard.screenrig.ai/dashboard/v1/screens/RESOURCE_ID/display'

Responses

Status	Meaning	Body and headers
200	Screen with its display state.	Screen (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)

DELETE/dashboard/v1/screens/{id}/display¶

Clear Dashboard Screen Display

The dashboard twin of DELETE /api/v1/screens/{id}/display.

Authentication: dashboardSession
Request body: none
Operation ID: clearDashboardScreenDisplay

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt 'https://dashboard.screenrig.ai/dashboard/v1/screens/RESOURCE_ID/display'

Responses

Status	Meaning	Body and headers
200	Screen with its display state.	Screen (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/dashboard/v1/screens/{id}/archive¶

Archive Dashboard Screen

Hides the screen from the default list and darkens the live glass. It does not unbind the player public key, and it releases screen_count quota. Archive is the only screen removal the dashboard offers: hard screen delete stays blocked by player identity, so DELETE is absent from this path family rather than answering screen_archive_required.

The durable project event carries the acting dashboard user as actor.

Authentication: dashboardSession
Request body: none
Operation ID: archiveDashboardScreen

Parameters

Name	Send in	Required?	Description
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

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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' 'https://dashboard.screenrig.ai/dashboard/v1/screens/RESOURCE_ID/archive'

Responses

Status	Meaning	Body and headers
200	Screen archived.	Screen (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)
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/dashboard/v1/screens/{id}/recovery/confirm¶

Confirm Dashboard Screen Recovery

Cookie-side twin of POST /api/v1/screens/{id}/recovery/confirm for the dashboard, which cannot call /api/v1. Confirms the pending recovery recorded when a native pairing start presented this screen's host duid or serial under a different bound key. The host object is a hint, never a credential; nothing is rebound until this confirmation.

Completes the pending native pairing onto the EXISTING screen, retires the previous key with a fifteen-minute grace window, preserves playlists, label, schedules, and history, and emits screen.recovered with the acting dashboard user as actor. Same project only.

If-Match is optional. recovery_not_offered, recovery_expired, and recovery_ambiguous are the stable problems; none echoes a device identifier.

Authentication: dashboardSession
Request body: none
Operation ID: confirmDashboardScreenRecovery

Parameters

Name	Send in	Required?	Description
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	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 --header 'Idempotency-Key: REQUEST_ID' 'https://dashboard.screenrig.ai/dashboard/v1/screens/RESOURCE_ID/recovery/confirm'

Responses

Status	Meaning	Body and headers
200	Screen recovered onto the pairing device's key.	Screen (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)
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/dashboard/v1/screens/{id}/unarchive¶

Unarchive Dashboard Screen

Restores an archived screen to the default list and remints a normal manifest. It must pass screen admission and it does not change the bound public key. The durable project event carries the acting dashboard user as actor.

Authentication: dashboardSession
Request body: none
Operation ID: unarchiveDashboardScreen

Parameters

Name	Send in	Required?	Description
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

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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' 'https://dashboard.screenrig.ai/dashboard/v1/screens/RESOURCE_ID/unarchive'

Responses

Status	Meaning	Body and headers
200	Screen unarchived.	Screen (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)
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)

GET/dashboard/v1/media¶

List Dashboard Media

Lists ready media of the session's project. The backend holds one rendition per object and publishes no thumbnail.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardMedia

Parameters

Name	Send in	Required?	Description
tag	query	optional	Exact media tag. Untagged objects are omitted when this filter is present.
primitive	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://dashboard.screenrig.ai/dashboard/v1/media'

Responses

Status	Meaning	Body and headers
200	Media	MediaList (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/dashboard/v1/media/{id}¶

Get Dashboard Media

Returns metadata for one ready media object owned by the session's project. The identifier is not authorization; an object of any other project is not_found. There is no dashboard media upload or patch.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardMedia

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://dashboard.screenrig.ai/dashboard/v1/media/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Ready private media metadata.	Media (application/json); headers: ETag, 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)

DELETE/dashboard/v1/media/{id}¶

Delete Dashboard Media

Tombstones one media object owned by the session's project. An object a desired or active grant still references cannot be deleted. The durable project event carries the acting dashboard user as actor.

Authentication: dashboardSession
Request body: none
Operation ID: deleteDashboardMedia

Parameters

Name	Send in	Required?	Description
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

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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 'Idempotency-Key: REQUEST_ID' 'https://dashboard.screenrig.ai/dashboard/v1/media/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
204	Tombstoned. Referenced desired or active grants cannot be deleted.	no body; 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)
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)

GET/dashboard/v1/media/{id}/content¶

Get Dashboard Media Content

Streams the original rendition of one media object owned by the session's project as first-party same-origin bytes. Authority is the session cookie plus project ownership; the identifier and the object path are never authorization, and no signed URL or object key is ever published here. Range is accepted so that a plain video element can seek.

This is not a runtime content grant: it does not read a manifest revision, it does not accept a runtime or release cookie, and it does not accept any ScreenRig-* Authorization header. V1 accepts one byte range only.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardMediaContent

Parameters

Name	Send in	Required?	Description
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://dashboard.screenrig.ai/dashboard/v1/media/RESOURCE_ID/content'

Responses

Status	Meaning	Body and headers
200	Complete original rendition.	no body; headers: Accept-Ranges, Content-Length, Content-Type, ETag, Cache-Control, Content-Disposition, X-Content-Type-Options
206	One standards-correct byte range.	no body; headers: Accept-Ranges, Content-Range, Content-Length, Content-Type, ETag, Cache-Control, X-Content-Type-Options
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)
416	Unsatisfiable, multiple, or malformed range.	Problem (application/problem+json); headers: Content-Range, Accept-Ranges
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/dashboard/v1/playlists¶

List Dashboard Playlists

Lists playlists of the session's project. This family is read-only: the dashboard shows what a screen is playing and never authors it, so there is no create, update, or delete here and there must not be. Authoring stays in the agent conversation and the CLI. (User ruling 2026-08-22.)

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardPlaylists

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/playlists'

Responses

Status	Meaning	Body and headers
200	Playlists	PlaylistList (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/dashboard/v1/playlists/{id}¶

Get Dashboard Playlist

Returns one playlist owned by the session's project, with its pages and their primitives. Authority is the session's project owning the playlist; the identifier is not authorization, so a playlist of any other project is not_found. There is no dashboard playlist write of any kind.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardPlaylist

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://dashboard.screenrig.ai/dashboard/v1/playlists/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Playlist	Playlist (application/json); headers: ETag, 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/dashboard/v1/applications¶

List Dashboard Applications

Lists applications of the session's project. The interface calls them web apps; the contract name stays applications.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardApplications

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/applications'

Responses

Status	Meaning	Body and headers
200	Applications	ApplicationList (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/dashboard/v1/applications/{id}¶

Get Dashboard Application

Returns one application owned by the session's project. The identifier is not authorization; an application of any other project is not_found. There is no dashboard application upload.

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardApplication

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://dashboard.screenrig.ai/dashboard/v1/applications/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Application	Application (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)

DELETE/dashboard/v1/applications/{id}¶

Delete Dashboard Application

Tombstones one application of the session's project together with its releases. It returns application_in_use while a live manifest still references any of those releases; the caller must first remove the primitive through the authoring surface. The durable project event carries the acting dashboard user as actor.

Authentication: dashboardSession
Request body: none
Operation ID: deleteDashboardApplication

Parameters

Name	Send in	Required?	Description
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

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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 'Idempotency-Key: REQUEST_ID' 'https://dashboard.screenrig.ai/dashboard/v1/applications/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
204	Application and its releases tombstoned.	no body; 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)
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/dashboard/v1/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 the existing exact release host. 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://dashboard.screenrig.ai/dashboard/v1/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/dashboard/v1/events¶

List Dashboard Events

Lists durable project events for the session's project. Dashboard mutations carry an actor naming the acting dashboard user. Events an agent or the CLI produced carry no actor.

Paging matches GET /api/v1/events: pass next_cursor back as after, next_cursor is null at the end of the history, and limit accepts 1-200 (default 50) or is refused with invalid_request.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardEvents

Parameters

Name	Send in	Required?	Description
after	query	optional
limit	query	optional	Page size. A value outside 1-200 is refused with invalid_request and an errors[] member whose field is limit.

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/events'

Responses

Status	Meaning	Body and headers
200	Durable events	EventList (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/dashboard/v1/events/stream¶

Stream Dashboard Events

Replayable project event stream for the session's project, used for the live activity log and for screen presence changes. The query cursor takes precedence over Last-Event-ID. Invalid, future, and pre-retention cursors receive stream.resync_required at the current head and close. Screenshot image bytes and media bytes never appear on this stream.

Authentication: dashboardSession
Request body: none
Operation ID: streamDashboardEvents

Parameters

Name	Send in	Required?	Description
after	query	optional
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://dashboard.screenrig.ai/dashboard/v1/events/stream'

Responses

Status	Meaning	Body and headers
200	Replayable SSE stream. Arriving billable events debit 1 whole credit each under the same meter and exemption set as GET /api/v1/events/stream; heartbeats and the retry preamble never charge. An unpaid billable event is not written and closes the stream; GET /dashboard/v1/balance remains available at zero. No ScreenRig-Credits-* headers.	string (text/event-stream); headers: Cache-Control, X-Accel-Buffering
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/dashboard/v1/webhooks¶

List Dashboard Webhooks

Read-only list of the session project's webhooks. Creating, editing, testing, and rotating secrets are agent (project API) operations.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardWebhooks

Request template and responses

Replace uppercase placeholders with your values. For a JSON request, save 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://dashboard.screenrig.ai/dashboard/v1/webhooks'

Responses

Status	Meaning	Body and headers
200	The project's webhooks.	WebhookList (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/dashboard/v1/webhooks/{id}¶

Get Dashboard Webhook

Authentication: dashboardSession
Request body: none
Operation ID: getDashboardWebhook

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://dashboard.screenrig.ai/dashboard/v1/webhooks/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	One webhook.	Webhook (application/json); headers: ETag, 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)

DELETE/dashboard/v1/webhooks/{id}¶

Delete Dashboard Webhook

Deletes one of the session project's webhooks, exactly like DELETE /api/v1/webhooks/{id}. The durable webhook.deleted event carries the acting dashboard user as actor.

Authentication: dashboardSession
Request body: none
Operation ID: deleteDashboardWebhook

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt 'https://dashboard.screenrig.ai/dashboard/v1/webhooks/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
204	Deleted.	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)
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	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready 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/dashboard/v1/webhooks/{id}/deliveries¶

List Dashboard Webhook Deliveries

Read-only delivery log of one of the session project's webhooks, newest event first.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardWebhookDeliveries

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt 'https://dashboard.screenrig.ai/dashboard/v1/webhooks/RESOURCE_ID/deliveries'

Responses

Status	Meaning	Body and headers
200	One page of deliveries.	WebhookDeliveryList (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/dashboard/v1/playback¶

List Dashboard Playback Aggregates

Daily playback aggregates for the session's project. One row per screen, media, and UTC day, newest days first.

Identifiers filter the session project's own rows and are never a cross-project lookup. format=csv streams every matching row inside day_from to day_to (default the last 31 days, at most 366), as GET /api/v1/playback; only the CSV form spends the playback-export budgets.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardPlaybackAggregates

Parameters

Name	Send in	Required?	Description
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 --cookie cookies.txt --cookie-jar cookies.txt 'https://dashboard.screenrig.ai/dashboard/v1/playback'

Responses

Status	Meaning	Body and headers
200	Daily playback aggregates for the session's project.	PlaybackAggregateList (application/json), PlaybackAggregateCsv (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/dashboard/v1/playback/plays¶

List Dashboard Playback Plays

The dashboard twin of GET /api/v1/playback/plays for the session's project: the same filters, range bound and settle lag, cursor, JSON page, CSV stream (the export button), abort on a mid-stream failure, and playback-export budgets. Dashboard reads are not metered.

Authentication: dashboardSession
Request body: none
Operation ID: listDashboardPlaybackPlays

Parameters

Name	Send in	Required?	Description
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
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.
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 --cookie cookies.txt --cookie-jar cookies.txt 'https://dashboard.screenrig.ai/dashboard/v1/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)

API lifecycle, deprecations, and rate limits

Versioned URL families are /api/v1, /api/v2, /runtime/v1, /runtime/v2, /content/v1, /dashboard/v1. 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.

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

forbidden

403 · Request is not allowed

type: https://screenrig.ai/problems/forbidden

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

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

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

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

webhook_url_rejected

400 · Webhook URL must be HTTPS on a public Internet host

type: https://screenrig.ai/problems/webhook-url-rejected

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.

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
AdvertisingDaypart — required: start, end
AdvertisingDeliveryReport — required: gross_mcr, fee_mcr, net_mcr, completed, interrupted, unbillable, rows
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
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
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
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
BillingBalance — required: wallet_revision, remaining_mcr, reserved_mcr, available_mcr, sources, withdrawal
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
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
CLIEnrollmentRequest — required: client_id, email
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
Comments — required: comments
CommentsWrite — required: comments
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 15 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
DashboardMemberList — required: items
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
Person session. Identifiers are descriptive; the session cookie establishes authority. A person with no projects has project: null.
DashboardSummary — required: screens, media, applications
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, sequence, 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
HLSStreamSource — required: protocol, url
HealthResponse — required: status
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
KVSummary — required: application_id, key, content_type, bytes, sha256, revision
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 a manifest revision, read from the exact matching durable grant: the desired grant for desired_playlist and the acknowledged (active) grant for active_playlist, never the screen's current assignment. 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 grant is null, never a fabricated revision.
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.
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.
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
MediaTagPatch — required: tag
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: the server 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 209715200 bytes, 200 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
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
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
Operation — required: id, kind, state, created_at, updated_at
OperationAccepted — required: id, release_id, operation_id
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 reported page, primitive, and release must be the exact application primitive of the session screen's current grant at the reported manifest revision, and the release must still be a ready release of the calling project, or the report is rejected.
Stores one per-play record (GET /api/v1/playback/plays) carrying the release identity and advances the release's last_used_at in the same transaction. 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 /runtime/v2/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 media must be on the session screen's grant at the reported manifest revision, and context.primitive must match the ready media's primitive or the report is rejected. Upserts the daily PlaybackAggregate for the screen, media, and UTC day.
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 visible start of an image or video. playlist_id is the playlist of the granted manifest revision the page came from (the effective playlist at play time). primitive is server-resolved from the ready media. primitive_id and started_at are present only when the Player reported them; started_at is player time 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 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
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.
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
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
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
PlaylistMediaSelectorByID — required: by, media_id
PlaylistMediaSelectorByIDs — required: by, media_ids
PlaylistMediaSelectorByTag — required: by, tag
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: type, title, status, detail, instance, code, request_id, errors
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
ProjectCapabilities — required: project_id, plan_id, features, feature_revision, capabilities
ProjectFeatures — required: advertiser, screens
ProjectName — required: none
Trimmed printable project name. Rejects controls, URL-looking text, @, www., and ://.
ProjectPatch — required: name
ProvisionScreen — required: none
ReadyResponse — required: status, degraded
ReleaseLaunch — required: launch_url, expires_at
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
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, capabilityHandle, capabilityExpiresAt
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
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 /runtime/v1/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.
RuntimeManifestDiagnostic — required: level, code, detail
One fail-safe runtime projection omission. Players and the CLI may show these; they are never authorization.
RuntimeManifestV2 — required: schemaVersion, manifestRevision, grantId, contentGeneration, screenId, playlistId, playlistRevision, generatedAt, pages
RuntimeMediaSelector — required: none
RuntimeMediaSelectorByAll — required: by, oneAtATime
RuntimeMediaSelectorByID — required: by, mediaId, oneAtATime
RuntimeMediaSelectorByIDs — required: by, mediaIds, oneAtATime
RuntimeMediaSelectorByTag — required: by, tag, oneAtATime
RuntimeObservationSurfaceWrite — required: id, width, height, pixel_ratio, presentation
RuntimeObservationWrite — required: observed_at, surfaces
The PUT /runtime/v1/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
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 /runtime/v1/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).
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 /runtime/v1/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
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/v1/screens/{id}/display); a screen without one is ok and unchanged.
ScreenActionReboot — required: type
POST /api/v1/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. More than 500 matches is invalid_request.
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 15 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 /runtime/v1/health), sanitized, with server reported_at. A member the Player did not send is absent. stale is true when reported_at is more than 15 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.
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 the screen's desired manifest revision, 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.
The nested playlist objects are hydrated from the exact matching durable grants.
ScreenObservation — required: observed_at, surfaces
Player-reported playback surface. Absent on Screen until the first accepted PUT /runtime/v1/observation. Read-only on the project API; ScreenPatch, PairScreen, pairing bodies, session bodies, canvas, runtime manifest, and POST /runtime/v1/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/v1/screens/{id}/playlist-schedule.
ScreenPlaylistScheduleView — required: entries
ScreenPlaylistScheduleWrite — required: entries
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/v1/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 /runtime/v1/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. 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 /runtime/v1/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 /runtime/v1/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
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.
SignInResetAccepted — required: status
Identical for known and unknown addresses; no address, credential, project, or delivery status is returned.
SignInResetRequest — required: email
StreamSource — required: none
UDPStreamSource — required: protocol, group, port
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.
VersionResponse — required: version, commit, api_version, protocol_version
Webhook — required: id, url, event_types, enabled, revision, status, created_at, updated_at
A project webhook. Each matching project event is POSTed to url as the same JSON object GET /api/v1/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
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/v1/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