OpenAPI YAMLOpenAPI JSONproblems YAMLAPI overview
This group has 24 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.
Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.
Runtime manifest, reports, and events
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.
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
curl --request POST --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/browser-provisioning/exchanges'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 201 | Paired-device cookie issued without a runtime cookie or credential in the body. | BrowserProvisioningCompletion (application/json); headers: Cache-Control, Referrer-Policy, RateLimit-Policy, RateLimit |
| 400 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 403 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 404 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 409 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 410 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 429 | Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures. | RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit |
| 500 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Get Runtime Chrome
Stage-chrome for the current runtime session. Not part of the runtime manifest. Auth is the same runtime cookie or ScreenRig-Session as GET /screen/manifest. Cache-Control is private, no-store. banner is always null.
Request template and responses
curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/chrome'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | Runtime chrome | RuntimeChrome (application/json); headers: Cache-Control |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Get Runtime Manifest
The one runtime manifest route, for every session. schemaVersion is 3. Resolved player manifest; projection is fail-safe, and invalid pages and primitives are omitted and listed in diagnostics.
Adslot pages are included only for a paired session granted adslot-v1; every other session, including an anonymous public-screen viewer, receives house content with no adslot page. The root keys stay camelCase; adslot page keys stay id, type, adslot_id and optional snake_case visibility.
Compatibility rule 4 — 200 with pages [] and non-empty diagnostics is a degraded projection (player keeps last-known-good); 200 with pages [] and no diagnostics is an authored empty assignment (docs/player-compatibility.md §1.4).
A suspended screen is served pages [] with no diagnostics, the suspension member and a manifest revision of its own, assigned a playlist or not (§6.9). An archived screen returns problem screen_archived and must not refresh last-known-good.
Parameters
| Name | Send in | Required? | Description |
|---|---|---|---|
| stream_transports | query | optional | Comma-separated supported stream transports (hls,udp-mpegts,rtsp). Omission projects streams to fallback images. Rendering negotiation only, never authorization. Advertise udp-mpegts only when locally enabled. |
Request template and responses
curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/manifest'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | Resolved player manifest. | RuntimeManifest (application/json) |
| 304 | Manifest unchanged | no body |
| 409 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Stream Runtime Events
Parameters
| Name | Send in | Required? | Description |
|---|---|---|---|
| after | query | optional | A cursor from a previous response: ev1_ for project events (and the event streams). The Player log (source=log) pages with lg1_ or ev1_ cursors by where the server keeps it; treat them as opaque and pass back the one a page returned. A cursor of another kind is refused with invalid_request. |
| Last-Event-ID | header | optional | Durable cursor used when after is absent. |
Request template and responses
curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/stream/events'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | Screen-scoped durable SSE. The query cursor takes precedence over Last-Event-ID; each event carries an id cursor suitable for reconnect. Served by the stream sidecar from Valkey (stream-valkey/v1); the stream carries no stream.cursor frames, and a cursor advances only with delivered events. Invalid, future, or pre-retention cursors receive stream.resync_required at the current head and close. screen.toast and screen.screenshot_requested are runtime audience events; scan never delivers either past details.expires_at. Screenshot image bytes are never on this stream. screen.archived and screen.unarchived are runtime audience events; they do not wipe credentials. screen.deleted is a runtime audience event delivered when signed identity reset tombstones the screen. No runtime event authorizes clearing local identity. Only successful signed reset initiated by a confirmed local player action permits local identity rotation. project.suspended and project.resumed are runtime audience hints when prepaid remaining hits zero or becomes positive. The runtime audience is an allowlist (docs/player-compatibility.md §7.1): screen.content_changed, screen.manifest_changed, screen.toast, screen.screenshot_requested, screen.archived, screen.unarchived, screen.deleted, screen.device_credential_revoked, project.suspended, project.resumed, player.reload, which reaches every runtime session, the per-screen commands player.reboot and player.display (docs/player-compatibility.md §6.5), player.play_page (§6.3.1) and player.identify (§6.3.2), never delivered past details.expires_at, and screen.card_data_changed (resource {type: card_data, key}, details {revision} or {deleted: true}), addressed only to screens whose current content reads that card data or feed key. Every other type is never published to the stream. Players ignore unknown event types, including the default message type, and unknown field names, and advance the cursor from every id. The stream opens with its own retry, drawn per connection between 3000 and 15000 ms so that streams dropped together do not reconnect together; a draining host sends each stream its own retry between 1000 and 30000 ms. The in-band problem frame (event: problem) has no id; its data is {code, detail, action?}, where action is present when the registry defines one, and the stream then closes (payment_required sets retry: 60000). The fleet player.reload control frame has no id and never moves the cursor. No frame carries more than 64 KiB of data. | string (text/event-stream); headers: X-Accel-Buffering |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Create Runtime Report
Request template and responses
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/reports'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 202 | Accepted after durable persistence. A telemetry batch is accepted or refused as a unit. It returns 202 only after its raw observations are durable and then its stream watermark has moved; it returns stream_id, sequence, accepted (report count), and duplicate. A batch that changes the latest health or observation state or the page-failure slot, or appends project events, commits its watermark with that state in one screen write, and appends its events in the same transaction. A batch that changes none of them, such as a steady batch of plays and condition reports, moves only its watermark, held in Valkey for 25 hours; while Valkey is unavailable or out of memory the screen write holds it instead. A refused batch (conflicting replay, full stream capacity, retired authority) stores nothing, except a new stream that loses the screen's last stream place to a concurrent new stream, which is refused after its raw observations are stored. A batch that was not acknowledged because of a server error or a lost connection can have stored some of its raw observations; replaying the same bytes stores each missing observation once, never stores one twice, and then acknowledges. A replay of an acknowledged batch returns 202 with duplicate true and changes nothing. A watermark held in Valkey can be lost or fall behind in a failover, never move ahead, so a sequence past the stream's watermark is accepted as the stream's next without a gap refusal, and a replay whose watermark was lost is accepted again with duplicate false; its plays are still stored once and its Player log records collapse on their identities. Individual reports retain their existing response. A runtime condition report (any other report code, such as player.page_skipped) is recorded in the Player log (GET /api/events?source=log), not in the project's events, and is acknowledged when the Player log queue accepts it; it is not on the event stream and not delivered to webhooks. manifest.activated is committed before this response and is idempotent for the current active revision. playback.media_started, legacy playback.video_started, and playback.application_started durably append one authenticated screen observation (GET /api/playback/plays) before this response; reported item, page, and manifest identities do not require current content membership and do not authorize content access. Daily counts, optional metadata, and project-owned resource last_used_at are updated by recoverable batches and can lag the raw observation. Ordinary playback-start responses omit optional credit-balance headers. playback.page_failed replaces the screen's latest page-failure slot and appends a project-only durable event in the same transaction without changing screen or manifest revision. manifest.upgrade stores the screen's one latest-wins manifest-upgrade slot behind its revision fences and appends a project-only durable event in the same transaction only when the derived state changes; a stale, superseded, or post-activation pre-activation report is accepted with no change, and no report ever promotes a grant. application.event appends a durable project event before this response. | no body; headers: RateLimit-Policy, RateLimit |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Put 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.
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
curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'ScreenRig-Capture-Id: VALUE' --header 'Content-Type: image/webp' --data-binary '@request.bin' 'https://play.screenrig.ai/screen/screenshot'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 204 | Still WebP stored as the current slot. | no body; headers: Cache-Control |
| 400 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 401 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 403 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 409 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Resolve Adslots
Resolves up to 16 server-verified page occurrences. A fresh candidate with a possible fill is atomically priced, budget-checked and reserved against the campaign-wide pricing fence. A fresh candidate with no possible fill returns empty without creating a decision or reservation.
No eligible or affordable campaign is a successful empty result with no content and no debit; it is never a payment challenge. Empty results may include a server-clock no-fill hint lasting at most 60 seconds and ending at an earlier known eligibility boundary.
Hints apply to the same screen, manifest, page, slot and eligibility context; they never authorize playback. A lease renewal reuses the same reservation and does not advance rotation, and is denied while the campaign requires price reacceptance.
Request body fields
| Field | Description |
|---|---|
| manifest_revision (required, string) | |
| candidates (required, array) |
Request template and responses
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/adslots/resolve'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | Per-candidate filled or empty results in request order. | RuntimeAdslotResolveResponse (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit |
| 400 | invalid_request - batch size, duplicate keys, or forecast window is invalid. | RuntimeProblem (application/problem+json) |
| 409 | resource_conflict - a candidate was reused with a different request hash. | RuntimeProblem (application/problem+json) |
| 429 | Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures. | RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
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.
Request body fields
| Field | Description |
|---|---|
| events (required, array) |
Request template and responses
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/adslots/events'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | Per-event outcomes. | RuntimeAdslotEventResponse (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit |
| 429 | Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures. | RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Put 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 one to twelve surfaces; a Player driving a video wall reports one per output, id = the output name.
Numbers are device-independent pixels and the device pixel ratio next to that layout surface, not canvas author size and not encoded screenshot size. They are range-checked only and are never proven hardware or authorization. Last write wins and replaces the whole surfaces array.
An identical surfaces tuple (id, width, height, pixel_ratio, presentation, rotation) does not emit screen.surface_changed; a later observed_at on the same tuple is ignored. Unpaired and anonymous public sessions are forbidden. Native cookies are rejected; browser must not adopt header profiles. Prepaid remaining credit is not a gate.
Observation is absent from GET /api/screens until the first accepted report. ScreenPatch cannot write it. An archived screen answers 409 screen_archived. At most 12 reports per minute per paired session (runtime-observation): a 429 means retry no sooner than Retry-After.
Request body fields
| Field | Description |
|---|---|
| observed_at (required, string) | format: "date-time" |
| surfaces (required, array) | One to twelve surfaces; a Player driving a video wall reports one per output, id = the output name. |
Request template and responses
curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/observation'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 204 | Observation stored as the current surfaces array. | no body; headers: Cache-Control, RateLimit-Policy, RateLimit |
| 400 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 401 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 403 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 409 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 429 | Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures. | RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Put Runtime Health
Reports device health for the paired session's screen. Send one on session start and every fifteen minutes, and one at once when the display connection or power changes.
Every member is optional and the body is read tolerantly (docs/player-compatibility.md §1.1): unknown members are ignored, a value out of range is dropped, and an unknown display.power or network.kind reads as unknown; only a member of the wrong JSON type is 400 (a number beyond float64 range is out of range: that member is dropped).
The stored value is the sanitized ScreenHealth plus server reported_at, replacing the previous report. At most one report per screen per minute (runtime-health): a 429 means drop this report and send the next one on schedule, never retry sooner than Retry-After (at least 1 second).
A 400 or a server error does not spend the minute; all sessions of one screen share it. Requires a paired session holding health.write (a paired session minted before health.write existed is admitted by runtime.report); unpaired and anonymous sessions are forbidden and an archived screen answers 409 screen_archived.
A report from a session older than the screen's current content access generation is refused 401. Archive and screen recovery clear Screen.health. A backend without this route answers 404: keep playing and stop reporting health for that session. Transitions append the project-only screen.health_changed (never on GET /screen/events).
Health is never authorization.
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) | |
| battery (optional, object) | The device's battery. Send it only when the device has one (Android BatteryManager with EXTRA_PRESENT). A change of source (plugged or unplugged) is reported at once, like a display change. |
| 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
curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/health'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 204 | Health report stored. | no body; headers: Cache-Control, RateLimit-Policy, RateLimit |
| 400 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 401 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 403 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 409 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 429 | Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures. | RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Put Runtime Storage
Reports native player storage, the player's storage plan, and transferred-byte accounting. Path does not name screen_id; the paired runtime session binds it. Unpaired and anonymous sessions are forbidden. Native cookies are rejected; browser must not adopt header profiles. Unknown members are ignored (docs/player-compatibility.md §1.1).
The stored value is the sanitized project ScreenStorage plus server received_at, not the raw body. manifest_revision must be the screen's desired or active revision, or the response is 409 resource_conflict and nothing is stored. Excluded page ids must exist in that revision.
An identical fit class does not emit screen.storage_shortfall or screen.storage_shortfall_cleared. Those events are project-only and are not delivered on GET /screen/events. Storage is never authorization or admission. ScreenPatch cannot write it. A report older than 24 hours by received_at is stale to consumers.
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
curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/storage'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 204 | Storage report stored. | no body; headers: Cache-Control, RateLimit-Policy, RateLimit |
| 400 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 401 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 403 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 409 | resource_conflict - manifest_revision is not the screen's desired or active revision. The report is not stored. | RuntimeProblem (application/problem+json) |
| 429 | Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures. | RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Put Runtime Status
Reports the status chip the paired Player shows on glass: the screenrig.overlay/v1 condition that wins its rank, or null when no chip shows. Path does not name screen_id; the paired runtime session binds it.
Body is JSON RuntimeStatusWrite {observed_at, chip}; unknown members are ignored (docs/player-compatibility.md §1.1). chip must be the id of a condition in the backend's catalogue (packages/overlay/overlay.json, the file Players vendor); the upgrade notice and the start messages are not chips.
A missing chip, a value of another type or an id the catalogue does not list is 400 invalid_request with errors[0].field chip, and nothing is stored. The stored value is the project ScreenStatus: level and icon are the catalogue's for chip, never the Player's, and received_at is the server receipt time. Last write wins and replaces the whole status.
A report that changes none of chip, level and icon is a no-op: it keeps the stored observed_at and received_at and appends nothing. A change appends the project-only screen.status_changed with details {chip, level, icon}, never delivered on GET /screen/events. Unpaired and anonymous public sessions are forbidden.
Native cookies are rejected; browser must not adopt header profiles. Prepaid remaining credit is not a gate. Status is absent from GET /api/screens until the first accepted report and is cleared on identity reset, unpair, and archive. ScreenPatch cannot write it. An archived screen answers 409 screen_archived.
At most 12 reports per minute per paired session (runtime-status): a 429 means retry no sooner than Retry-After. A backend without this route answers 404: keep playing and stop reporting status for that session. Status is never authorization or admission. The Player rules are docs/player-compatibility.md §9.5.
Request body fields
| Field | Description |
|---|---|
| observed_at (required, string) | Player clock when the chip last changed, or when the session started. format: "date-time" |
| chip (required, inline) | The id of the screenrig.overlay/v1 condition the Player shows (conditions[].id in packages/overlay/overlay.json), or null when it shows no chip, as on a suppressed surface (fatal, starting, pairing). Required. An id the backend's catalogue does not list is refused. |
Request template and responses
curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/status'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 204 | Status stored, or unchanged. | no body; headers: Cache-Control, RateLimit-Policy, RateLimit |
| 400 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 401 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 403 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 409 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 429 | Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures. | RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Put Runtime Screen Label
Renames the screen bound to the paired runtime session. It is the same rename as PATCH /api/screens/{id} name: the server trims screen_label and requires 1 to 120 characters without control characters, otherwise invalid_request.
The rename records the same screen events, and on an assigned screen it changes the manifest screen_label and emits screen.manifest_changed to the Player. Path and body do not name screen_id; the paired runtime session binds it. No If-Match or Idempotency-Key; last write wins. Auth is the runtime cookie or ScreenRig-Session, as GET /screen/chrome.
Anonymous and unpaired sessions are unauthorized. An archived screen is screen_archived. Prepaid remaining credit is not a gate. A Player that receives 404 treats the route as unsupported and keeps the name locally (docs/player-compatibility.md §2.5).
Request body fields
| Field | Description |
|---|---|
| screen_label (required, string) | minLength: 1 |
Request template and responses
curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/screen-label'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | Screen renamed. screen_label is the stored name. | RuntimeScreenLabel (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit |
| 400 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 401 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 403 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 409 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 429 | Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures. | RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Post Runtime Command Result
A paired Player reports how a command it was sent ended (docs/player-compatibility.md §6.5.1): done or failed, with a static cause token and an optional short detail. The command becomes done or failed in Screen.commands with done_at, cause and detail, and the project-only screen.command_result is appended.
Only a sent command of the session's screen takes a result: an id the screen does not list, or one not sent, is 404 not_found and the Player drops the report. An exact repeat of the recorded result is 202 and changes nothing; a different result for a finished command is 409 resource_conflict. A failed result requires cause.
The path and body do not name the screen; the paired runtime session binds it. Auth is the runtime cookie or ScreenRig-Session. Anonymous and unpaired sessions are unauthorized; an archived screen is screen_archived. Prepaid remaining credit is not a gate.
Parameters
| Name | Send in | Required? | Description |
|---|---|---|---|
| command_id | path | required |
Request body fields
| Field | Description |
|---|---|
| state (required, string) | Allowed: "done", "failed" |
| cause (optional, string) | A static token: required when failed (clear_failed, restart_failed, update_check_failed, download_failed, install_failed, no_update_channel), optional when done (cleared, restarted, up_to_date, updated). pattern: "^[a-z0-9_]{1,40}$" |
| detail (optional, string) | A short sentence without control characters; never a URL with credentials, a token or a private path. maxLength: 200 |
Request template and responses
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/commands/COMMAND_ID/result'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 202 | Stored, or an exact repeat of the stored result. | no body; headers: Cache-Control, RateLimit-Policy, RateLimit |
| 400 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 401 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 403 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 404 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 409 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 429 | Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures. | RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Join Runtime Live
A Player that received player.live_publish joins the session (docs/player-compatibility.md §6.10.2): it gets short-lived TURN ice_servers, the lease, the video limits it may publish and the heartbeat period. The live_id must be the screen's current session, else 410 live_session_ended (stop publishing, keep playing).
Auth is the paired runtime cookie or ScreenRig-Session.
Parameters
| Name | Send in | Required? | Description |
|---|---|---|---|
| live_id | path | required |
Request template and responses
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/live/LIVE_ID/join'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | The session the Player publishes to. | RuntimeLiveJoin (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit |
| 400 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 401 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 403 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 409 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 410 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 429 | Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures. | RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Offer Runtime Live
The Player sends its gathered sendonly offer: exactly one video m-section, ICE gathering complete or two seconds old, no separate candidates ever. The backend opens a fresh media relay session for it, replacing any earlier publisher of the session, and returns the relay's answer, which the Player applies with setRemoteDescription.
No video m-section, or two, is invalid_request. A relay failure is dependency_unavailable. 410 live_session_ended when the live_id is not the screen's current session.
Parameters
| Name | Send in | Required? | Description |
|---|---|---|---|
| live_id | path | required |
Request body fields
| Field | Description |
|---|---|
| sdp (required, string) | One sendonly video m-section; ICE gathering complete or two seconds old. |
Request template and responses
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/live/LIVE_ID/offer'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | The relay''s answer. | RuntimeLiveOffer (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit |
| 400 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 401 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 403 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 409 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 410 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 429 | Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures. | RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Heartbeat Runtime Live
The Player reports its connection state and what its encoder sends every 20 seconds. The answer carries the lease; a lapsed lease or max_until ends the session here with 410 live_session_ended, and the Player stops publishing. The report is the Player's own word and feeds publisher.connected on the project API.
Parameters
| Name | Send in | Required? | Description |
|---|---|---|---|
| live_id | path | required |
Request body fields
| Field | Description |
|---|---|
| connection (required, string) | Allowed: "new", "connecting", "connected", "disconnected", "failed", "closed" |
| video (optional, object) |
Request template and responses
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/live/LIVE_ID/heartbeat'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | The session is live; lease_until and max_until are its limits. | RuntimeLiveHeartbeatAnswer (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit |
| 400 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 401 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 403 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 409 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 410 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 429 | Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures. | RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Stopped Runtime Live
The Player reports it stopped publishing. The reason is an open enum (stopped, lease_ended, superseded, consent_denied, consent_timeout, projection_stopped, capture_failed, encoder_unavailable, connection_failed, relay_refused); a reason this server does not know reads player_stopped. 204 always, also for a live_id that is not the screen's current session.
Parameters
| Name | Send in | Required? | Description |
|---|---|---|---|
| live_id | path | required |
Request body fields
| Field | Description |
|---|---|
| reason (required, string) | stopped, lease_ended, superseded, consent_denied, consent_timeout, projection_stopped, capture_failed, encoder_unavailable, connection_failed or relay_refused. An open enum; an unknown reason reads player_stopped. |
Request template and responses
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/live/LIVE_ID/stopped'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 204 | Recorded. | no body; headers: Cache-Control, RateLimit-Policy, RateLimit |
| 400 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 401 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 403 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 409 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 410 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 429 | Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures. | RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Get Runtime Screen Playlists
Lists the playlists the paired Player's on-device settings menu offers for the screen: the live playlists of the screen's project that have an approved version, alphabetical by name without regard to case, then by id. At most 500 are returned; more is true when the project has further playlists.
The paired runtime session binds the project; the path names none. Auth is the runtime cookie or ScreenRig-Session, as GET /screen/chrome. Anonymous and unpaired sessions are unauthorized. An archived screen is screen_archived. Cache-Control is private, no-store.
A Player that receives 404 treats the route as unsupported and reports it like any other failure to load the list (docs/player-compatibility.md §2.6).
Request template and responses
curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/playlists'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | The project's assignable playlists. | RuntimeScreenPlaylists (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit |
| 401 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 403 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 409 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 429 | Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures. | RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Put Runtime Screen Playlist
Assigns a playlist to the screen bound to the paired runtime session. It is the same assignment as PATCH /api/screens/{id} playlist_id, made by the person at the device: no review is opened.
The playlist must belong to the screen's project and have an approved version (playlist_not_approved otherwise); a playlist that does not exist in the project is invalid_request. The assignment records the same screen events and emits screen.manifest_changed to the Player.
It sets the screen's assigned playlist; an active takeover or a matching playlist schedule entry still decides what plays. Path and body do not name screen_id; the paired runtime session binds it. No If-Match or Idempotency-Key; last write wins. Auth is the runtime cookie or ScreenRig-Session, as GET /screen/chrome.
Anonymous and unpaired sessions are unauthorized. An archived screen is screen_archived. A Player that receives 404 treats the route as unsupported and reports it like any other failure to change the playlist (docs/player-compatibility.md §2.6).
Request body fields
| Field | Description |
|---|---|
| playlist_id (required, string) | minLength: 1 |
Request template and responses
curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/playlist'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | Playlist assigned. playlist_id is the screen's assigned playlist. | RuntimeScreenPlaylist (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit |
| 400 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 401 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 403 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 409 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 429 | Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures. | RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Unpair Runtime
Cookie-only unpair. Archives a cookie-paired screen that has no player public-key enrollment, with archive_reason device_unpair. The device credential stays bound: a browser that still holds it mints an archived session (dark glass), and unarchive resumes it with no re-pairing (docs/player-compatibility.md §5.1).
A screen that is already archived, or already gone, is success. Identity-enrolled screens return screen_archive_required; those players reset only via POST /screen/native/identity/reset. Path and body do not name screen_id; the paired runtime session binds it. No If-Match or Idempotency-Key. Browser 204 expires the runtime, device, and pairing host cookies.
Native identity-bound calls never 204. Anonymous or unpaired sessions are forbidden. Prepaid remaining credit is not a gate.
Request template and responses
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/unpair'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 204 | Cookie-paired screen archived with its credential kept. Browser pairing cookies expired. | no body; headers: Cache-Control, RateLimit-Policy, RateLimit |
| 401 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 403 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 409 | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
| 429 | Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures. | RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Launch Application Release
Mints the single-use ticket for one application release of the screen's current manifest. launch_url is the release host's index page with ticket first and then the application's params (the primitive's params, filled with this screen's facts, percent-encoded, at most 4096 characters together), so the application reads them from location.search.
Only the web Player and the Players that run it call this route; the Qt, Android, Apple and Windows Players load the application from their local package and receive no params. The release host passes them on to the page and adds its own policy marker.
A screen that lacks a value a param reads, or whose values fill into more than the limit, has no such application in its manifest (diagnostic screen_fact_missing or screen_fact_invalid), and a launch for its release is refused.
Params are not bound to the ticket: an application treats them as untrusted hints and reads the screen's identity from context.screen_id.
Parameters
| Name | Send in | Required? | Description |
|---|---|---|---|
| manifest_revision | path | required | |
| release_id | path | required |
Request template and responses
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/manifests/MANIFEST_REVISION/releases/RELEASE_ID/launch'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 201 | Single-use 30-second exact-release-host launch ticket | ReleaseLaunch (application/json); headers: Referrer-Policy, RateLimit-Policy, RateLimit |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Resolve all dynamic media selectors for one playlist loop
Uses the authenticated screen's assigned playlist and its manifest revision. Returns a fixed snapshot in filename order; Players retain cursor and shuffle state across loops. Uploads and tag changes never rewrite this manifest. Empty matches are valid.
Selected media are authorized by the screen's runtime grant independently of the immutable manifest definition.
Parameters
| Name | Send in | Required? | Description |
|---|---|---|---|
| manifest_revision | path | required |
Request template and responses
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/screen/manifests/MANIFEST_REVISION/selectors/resolve'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | Resolved loop snapshot, including item metadata and media_end safety deadlines. | RuntimeSelectorSnapshot (application/json) |
| 401 | Runtime session invalid or expired | RuntimeProblem (application/problem+json) |
| 403 | Runtime capability denied | RuntimeProblem (application/problem+json) |
| 503 | Manifest projection pending or selector snapshot degraded; retain the current loop and retry | RuntimeProblem (application/problem+json) |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |
Get Runtime Card Data
Returns a card data or feed document, the card data or feed key of a card primitive in the screen's current manifest, or the key of a page's visibility.data condition. A key is readable only while a desired, active, or transition-grace grant of the session's screen lists it; knowing a key is never enough.
Feed keys start with feed: and read the system feed namespace (screenrig.weather/v1 and the other feed schemas), as do the weather conditions keys that start with feed.conditions.v1: (a page's {screen.weather} condition, filled in each screen's manifest); every other key reads the card data of the screen's project. The body is the document itself.
ETag is the sha256 of its bytes and If-None-Match answers 304; keep the last good document for offline playback and refetch on screen.card_data_changed for the key. 404 means no document is stored yet; keep the card hidden.
Parameters
| Name | Send in | Required? | Description |
|---|---|---|---|
| key | path | required | |
| If-None-Match | header | optional |
Request template and responses
curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/card-data/KEY'Responses
| Status | Meaning | Body and headers |
|---|---|---|
| 200 | The document | object (application/json); headers: ETag |
| 304 | Not modified | no body |
| default | Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value. | RuntimeProblem (application/problem+json) |