# ScreenRig documentation full context

> ScreenRig is an agent-operated digital-signage service: an agent uses the CLI and REST API to upload content, assemble a looping playlist, pair a browser screen, and observe the result.

Last-reviewed: 2026-08-14. Phase: prerelease localhost v1. OpenAPI: 0.2.0. Canonical docs representation: https://screenrig.ai/docs.md

This is the stable consolidated documentation context. It avoids duplicating every schema property: use https://screenrig.ai/docs/api/openapi.yaml for authoritative HTTP structure and https://screenrig.ai/docs/api.md for the generated inventory.

## Start here

Follow https://screenrig.ai/index.md. Build the SDK and CLI from source, start and smoke the private stack, create an account against `http://api.screenrig.localhost:8088`, open `http://play.screenrig.localhost:8088`, pair its code, upload an already-built application, create/assign a playlist, and follow events. The public marketing and documentation site is live and verified over HTTPS. No ScreenRig service API, Player, release host, or protected-content production endpoint is deployed or verified, and npm packages remain unpublished.

## Authentication realms

- `accountBearer`: CLI/account control API only.
- `pairingCookie`: short-lived browser pairing session.
- `pairedDeviceCookie`: long-lived paired browser device.
- `runtimeCookie` / `pairedRuntimeCookie`: trusted Player runtime, with mutation profile only when paired.
- `placementCapability`: short-lived header for one placement's allowed application K/V operations.
- `releaseLaunchTicket` / `releaseGrantCookie`: single-use launch and exact-host immutable release delivery.
- `operatorBearer`: separate operator surface.

Credentials are not interchangeable. Never put account bearers in URLs, Player/application state, logs, or events.

## Idempotency and revisions

Authenticated mutations accept or require `Idempotency-Key`. Retry a lost response with the same key and identical request. A different request with the same key returns `409 idempotency_mismatch`.

Mutable resources use integer revisions and ETags. Conditional writes require `If-Match`; stale writes return `412 revision_conflict`. Refetch and retry intentionally with the current revision.

## Durable operations and events

Application uploads may begin in `receiving`; long work then uses `queued`, `running`, `succeeded`, `failed`, or `cancelled`. Events are persisted before fan-out. Treat SSE cursors as opaque and resume from the last cursor or `Last-Event-ID`. On `stream.resync_required`, refetch authoritative state and resume at the supplied head cursor.

## Uploads

Application upload packages an already-built static directory, validates/extracts it in a sandbox, and publishes immutable release identity through a durable operation. Media upload declares exact size/hash/type, follows the server's signed raw PUT method and headers verbatim, commits, and waits for a durable operation. Never log or reconstruct signed URLs/headers.

## Player and protected content

A browser Player starts a pairing session and shows a six-character code. Account control claims that code. Runtime manifests are complete and revisioned. Release assets and manifest-bound media require current grants. Runtime/application K/V additionally requires placement capability. Knowledge of an ID or object key is never authority. ScreenRig is not public file hosting.

## Problems and recovery

Errors use RFC 9457 `application/problem+json`. Branch on `status` and `code`, not `detail`. Stable codes are listed at https://screenrig.ai/docs/api/problems.yaml. Use `screenrig doctor --json`, wait/retry durable operations, refetch on revision conflict, and resume streams from the last durable cursor.

## Runtime status and boundaries

Use `GET /.health`, `GET /.ready`, `GET /.version`, and `GET /api/v1/capabilities` on the relevant local origin. The static https://screenrig.ai/status/status.json is implementation readiness, not live uptime. The public marketing and documentation site is live and verified over HTTPS; the service API, Player, release hosts, protected content delivery, and full production application stack remain undeployed and unverified. Android `standard`, `managed`, and `amazon` source and its native offline-resilience contract are implemented and build-tested; instrumentation/hardware/store publication and a general offline guarantee remain unproven. Deferred: MCP, billing/payments, screenshots, email recovery, and dashboard.

## Primary representations

- https://screenrig.ai/docs.md
- https://screenrig.ai/docs/api.md
- https://screenrig.ai/docs/api/openapi.yaml
- https://screenrig.ai/docs/api/openapi.json
- https://screenrig.ai/docs/api/problems.yaml
- https://screenrig.ai/skill/SKILL.md
- https://screenrig.ai/skill.md
- https://screenrig.ai/status.md
- https://screenrig.ai/sitemap.md