ScreenRig API reference

Five-minute agent workflow

Build the checkout CLI and start the stack from the verified quickstart.

shell · CLI with REST routes

screenrig account create --email agent-owner@example.com --json  # POST /api/v1/accounts
screenrig app upload ./built-webapp --json                       # POST /api/v1/applications
screenrig playlist create ./playlist.json --json                # POST /api/v1/playlists
screenrig screen pair --code ABCDEF --label "Lobby" --json      # POST /api/v1/screens/pair
screenrig screen assign scr_example --playlist-id pl_example --if-match 1 --json
screenrig events follow --json                                   # GET /api/v1/events/stream

Expected: mutations return revisioned resources or durable operations; event follow emits opaque cursors. Values are placeholders.

Base URLs and credential realms

https://screenrig.ai serves the live, HTTPS-verified public marketing and documentation site. https://api.screenrig.ai and https://play.screenrig.ai are architectural service origins only; the API, Player, release hosts, and protected content are not deployed or verified there. Verified local service equivalents are http://api.screenrig.localhost:8088 and http://play.screenrig.localhost:8088.

accountBearer: Account API only; never runtime/content/release authority.
pairing, device, runtime cookies: Trusted Player origin only, with distinct profiles.
placementCapability: Short-lived, placement-scoped K/V authority.
launch ticket, release grant: Single-use launch and exact release-host delivery.
operatorBearer: Separate operator realm.

Status: /.health, /.ready, /.version. Limits: /api/v1/capabilities.

Common request semantics

Idempotency: retry only the same mutation with the same key; mismatch returns 409 idempotency_mismatch.
Revisions: changes require If-Match; 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: use capabilities; rate limiting returns 429 rate_limited.

Do not put bearer tokens in browser storage. Use the CLI or a secure direct REST client.

Upload lifecycles

Applications

Submit an already-built deterministic archive and wait for validation, extraction, and immutable publication. The service does not build or execute uploaded source.

Media

Declare exact type, size, and hash; follow the signed raw PUT method and headers verbatim; commit and wait. Never log or reconstruct signed URLs or headers.

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.

ScreenRig is not public file hosting. Release, media, and K/V access derives from current screen-manifest authority. IDs and object keys are not authorization.

RFC 9457 problems

Errors use application/problem+json. Branch on status and stable code, never detail. 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

account_exists

409 · Account already exists

type: https://screenrig.ai/problems/account-exists

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 · Account content quota is exceeded

type: https://screenrig.ai/problems/quota-exceeded

rate_limited

429 · Request rate is too high

type: https://screenrig.ai/problems/rate-limited

dependency_unavailable

503 · Required dependency is unavailable

type: https://screenrig.ai/problems/dependency-unavailable

schema_incompatible

503 · Database schema is incompatible

type: https://screenrig.ai/problems/schema-incompatible

not_ready

503 · Service is not ready

type: https://screenrig.ai/problems/not-ready

Versioning and troubleshooting

OpenAPI contract: 0.2.0. Run screenrig doctor --json; use doctor --repair-config for config permissions and curl --noproxy '*' if a proxy intercepts .localhost. Redact secrets, cookies, signed URLs, object keys, and customer content.

Complete endpoint inventory

50 operations generated from api/openapi.yaml. Examples are contract-generated localhost templates, not a browser console.

Service status and capabilities

GET/.health¶

Get health

operation: getHealth
auth: none
headers: none
parameters: none
request: none
responses: 200: HealthResponse (application/json)

shell · contract-generated request shape

curl --noproxy '*' --request GET 'http://api.screenrig.localhost:8088/.health'

GET/.ready¶

Get readiness

operation: getReadiness
auth: none
headers: none
parameters: none
request: none
responses: 200: ReadyResponse (application/json) · 503: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request GET 'http://api.screenrig.localhost:8088/.ready'

GET/.version¶

Get version

operation: getVersion
auth: none
headers: none
parameters: none
request: none
responses: 200: VersionResponse (application/json)

shell · contract-generated request shape

curl --noproxy '*' --request GET 'http://api.screenrig.localhost:8088/.version'

GET/api/v1/capabilities¶

Get capabilities

operation: getCapabilities
auth: none
headers: none
parameters: none
request: none
responses: 200: Capabilities (application/json)

shell · contract-generated request shape

curl --noproxy '*' --request GET 'http://api.screenrig.localhost:8088/api/v1/capabilities'

Accounts and credentials

POST/api/v1/accounts¶

Create account

operation: createAccount
auth: none
headers: Idempotency-Key
parameters: Idempotency-Key (header, required)
request: AccountCreate
responses: 201: AccountCreated (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request POST --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'http://api.screenrig.localhost:8088/api/v1/accounts'

json · schema-generated request body

{
  "email": "string"
}

GET/api/v1/account¶

Get account

operation: getAccount
auth: accountBearer
headers: none
parameters: none
request: none
responses: 200: Account (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --header 'Authorization: Bearer SCREENRIG_TOKEN' 'http://api.screenrig.localhost:8088/api/v1/account'

POST/api/v1/account/credential-issuances/{id}/ack¶

Acknowledge credential issuance

operation: acknowledgeCredentialIssuance
auth: accountBearer
headers: none
parameters: id (path, required)
request: none
responses: 204: no body · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request POST --header 'Authorization: Bearer SCREENRIG_TOKEN' 'http://api.screenrig.localhost:8088/api/v1/account/credential-issuances/RESOURCE_ID/ack'

Applications and operations

GET/api/v1/applications¶

List applications

operation: listApplications
auth: accountBearer
headers: none
parameters: none
request: none
responses: 200: ApplicationList (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --header 'Authorization: Bearer SCREENRIG_TOKEN' 'http://api.screenrig.localhost:8088/api/v1/applications'

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.

operation: uploadApplication
auth: accountBearer
headers: Idempotency-Key, ScreenRig-Archive-SHA256, ScreenRig-Expanded-Bytes, ScreenRig-File-Count, ScreenRig-SDK-Version, ScreenRig-Application-Name
parameters: Idempotency-Key (header, required), ScreenRig-Archive-SHA256 (header, required), ScreenRig-Expanded-Bytes (header, required), ScreenRig-File-Count (header, required), ScreenRig-SDK-Version (header), ScreenRig-Application-Name (header)
request: string
responses: 202: OperationAccepted (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --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/json' --data '@request.json' 'http://api.screenrig.localhost:8088/api/v1/applications'

json · schema-generated request body

"string"

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

Get application

operation: getApplication
auth: accountBearer
headers: none
parameters: id (path, required)
request: none
responses: 200: Application (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --header 'Authorization: Bearer SCREENRIG_TOKEN' 'http://api.screenrig.localhost:8088/api/v1/applications/RESOURCE_ID'

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

Get operation

operation: getOperation
auth: accountBearer
headers: none
parameters: id (path, required)
request: none
responses: 200: Operation (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --header 'Authorization: Bearer SCREENRIG_TOKEN' 'http://api.screenrig.localhost:8088/api/v1/operations/RESOURCE_ID'

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

Cancel operation

operation: cancelOperation
auth: accountBearer
headers: Idempotency-Key
parameters: id (path, required), Idempotency-Key (header, required)
request: none
responses: 200: Operation (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request POST --header 'Authorization: Bearer SCREENRIG_TOKEN' --header 'Idempotency-Key: REQUEST_ID' 'http://api.screenrig.localhost:8088/api/v1/operations/RESOURCE_ID/cancel'

Media uploads

GET/api/v1/media¶

List media

operation: listMedia
auth: accountBearer
headers: none
parameters: none
request: none
responses: 200: MediaList (application/json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --header 'Authorization: Bearer SCREENRIG_TOKEN' 'http://api.screenrig.localhost:8088/api/v1/media'

POST/api/v1/media/uploads¶

Create media upload

operation: createMediaUpload
auth: accountBearer
headers: Idempotency-Key
parameters: Idempotency-Key (header, required)
request: MediaUploadDeclaration
responses: 201: MediaUploadSession (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request POST --header 'Authorization: Bearer SCREENRIG_TOKEN' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'http://api.screenrig.localhost:8088/api/v1/media/uploads'

json · schema-generated request body

{
  "filename": "string",
  "content_type": "image/png",
  "bytes": 1,
  "sha256": "string"
}

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

Commit media upload

operation: commitMediaUpload
auth: accountBearer
headers: Idempotency-Key
parameters: id (path, required), Idempotency-Key (header, required)
request: MediaCommit
responses: 202: Operation (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request POST --header 'Authorization: Bearer SCREENRIG_TOKEN' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'http://api.screenrig.localhost:8088/api/v1/media/uploads/RESOURCE_ID/commit'

json · schema-generated request body

{
  "content_type": "image/png",
  "bytes": 1,
  "sha256": "string"
}

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

Get media

operation: getMedia
auth: accountBearer
headers: none
parameters: id (path, required)
request: none
responses: 200: Media (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --header 'Authorization: Bearer SCREENRIG_TOKEN' 'http://api.screenrig.localhost:8088/api/v1/media/RESOURCE_ID'

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

Delete media

operation: deleteMedia
auth: accountBearer
headers: If-Match, Idempotency-Key
parameters: id (path, required), If-Match (header, required), Idempotency-Key (header, required)
request: none
responses: 204: no body · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request DELETE --header 'Authorization: Bearer SCREENRIG_TOKEN' --header 'If-Match: "1"' --header 'Idempotency-Key: REQUEST_ID' 'http://api.screenrig.localhost:8088/api/v1/media/RESOURCE_ID'

Playlists

GET/api/v1/playlists¶

List playlists

operation: listPlaylists
auth: accountBearer
headers: none
parameters: none
request: none
responses: 200: PlaylistList (application/json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --header 'Authorization: Bearer SCREENRIG_TOKEN' 'http://api.screenrig.localhost:8088/api/v1/playlists'

POST/api/v1/playlists¶

Create playlist

operation: createPlaylist
auth: accountBearer
headers: Idempotency-Key
parameters: Idempotency-Key (header, required)
request: PlaylistWrite
responses: 201: Playlist (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request POST --header 'Authorization: Bearer SCREENRIG_TOKEN' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'http://api.screenrig.localhost:8088/api/v1/playlists'

json · schema-generated request body

{
  "name": "string",
  "pages": [
    {}
  ]
}

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

Get playlist

operation: getPlaylist
auth: accountBearer
headers: none
parameters: id (path, required)
request: none
responses: 200: Playlist (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --header 'Authorization: Bearer SCREENRIG_TOKEN' 'http://api.screenrig.localhost:8088/api/v1/playlists/RESOURCE_ID'

PUT/api/v1/playlists/{id}¶

Update playlist

operation: updatePlaylist
auth: accountBearer
headers: If-Match, Idempotency-Key
parameters: id (path, required), If-Match (header, required), Idempotency-Key (header, required)
request: PlaylistWrite
responses: 200: Playlist (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request PUT --header 'Authorization: Bearer SCREENRIG_TOKEN' --header 'If-Match: "1"' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'http://api.screenrig.localhost:8088/api/v1/playlists/RESOURCE_ID'

json · schema-generated request body

{
  "name": "string",
  "pages": [
    {}
  ]
}

DELETE/api/v1/playlists/{id}¶

Delete playlist

operation: deletePlaylist
auth: accountBearer
headers: If-Match, Idempotency-Key
parameters: id (path, required), If-Match (header, required), Idempotency-Key (header, required)
request: none
responses: 204: no body · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request DELETE --header 'Authorization: Bearer SCREENRIG_TOKEN' --header 'If-Match: "1"' --header 'Idempotency-Key: REQUEST_ID' 'http://api.screenrig.localhost:8088/api/v1/playlists/RESOURCE_ID'

Screens and control-plane pairing

GET/api/v1/screens¶

List screens

operation: listScreens
auth: accountBearer
headers: none
parameters: none
request: none
responses: 200: ScreenList (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --header 'Authorization: Bearer SCREENRIG_TOKEN' 'http://api.screenrig.localhost:8088/api/v1/screens'

POST/api/v1/screens/pair¶

Pair screen

operation: pairScreen
auth: accountBearer
headers: Idempotency-Key
parameters: Idempotency-Key (header, required)
request: PairScreen
responses: 201: PairingClaim (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request POST --header 'Authorization: Bearer SCREENRIG_TOKEN' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'http://api.screenrig.localhost:8088/api/v1/screens/pair'

json · schema-generated request body

{
  "code": "string",
  "label": "string"
}

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

Get screen

operation: getScreen
auth: accountBearer
headers: none
parameters: id (path, required)
request: none
responses: 200: Screen (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --header 'Authorization: Bearer SCREENRIG_TOKEN' 'http://api.screenrig.localhost:8088/api/v1/screens/RESOURCE_ID'

PATCH/api/v1/screens/{id}¶

Update screen

operation: updateScreen
auth: accountBearer
headers: If-Match, Idempotency-Key
parameters: id (path, required), If-Match (header, required), Idempotency-Key (header, required)
request: ScreenPatch
responses: 200: Screen (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request PATCH --header 'Authorization: Bearer SCREENRIG_TOKEN' --header 'If-Match: "1"' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'http://api.screenrig.localhost:8088/api/v1/screens/RESOURCE_ID'

json · schema-generated request body

{
  "name": "string",
  "playlist_id": "string"
}

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

Delete screen

operation: deleteScreen
auth: accountBearer
headers: If-Match, Idempotency-Key
parameters: id (path, required), If-Match (header, required), Idempotency-Key (header, required)
request: none
responses: 204: no body · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request DELETE --header 'Authorization: Bearer SCREENRIG_TOKEN' --header 'If-Match: "1"' --header 'Idempotency-Key: REQUEST_ID' 'http://api.screenrig.localhost:8088/api/v1/screens/RESOURCE_ID'

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

Rotate screen public id

operation: rotateScreenPublicId
auth: accountBearer
headers: If-Match, Idempotency-Key
parameters: id (path, required), If-Match (header, required), Idempotency-Key (header, required)
request: none
responses: 200: Screen (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request POST --header 'Authorization: Bearer SCREENRIG_TOKEN' --header 'If-Match: "1"' --header 'Idempotency-Key: REQUEST_ID' 'http://api.screenrig.localhost:8088/api/v1/screens/RESOURCE_ID/public-id/rotate'

POST/api/v1/screens/{id}/credential/revoke¶

Revoke screen credential

operation: revokeScreenCredential
auth: accountBearer
headers: If-Match, Idempotency-Key
parameters: id (path, required), If-Match (header, required), Idempotency-Key (header, required)
request: none
responses: 200: Screen (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request POST --header 'Authorization: Bearer SCREENRIG_TOKEN' --header 'If-Match: "1"' --header 'Idempotency-Key: REQUEST_ID' 'http://api.screenrig.localhost:8088/api/v1/screens/RESOURCE_ID/credential/revoke'

Application K/V for owners

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

List k v

operation: listKV
auth: accountBearer
headers: none
parameters: application_id (path, required)
request: none
responses: 200: KVList (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --header 'Authorization: Bearer SCREENRIG_TOKEN' 'http://api.screenrig.localhost:8088/api/v1/applications/APPLICATION_ID/kv'

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

Get k v

operation: getKV
auth: accountBearer
headers: none
parameters: application_id (path, required), key (path, required)
request: none
responses: 200: KVEntry (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --header 'Authorization: Bearer SCREENRIG_TOKEN' 'http://api.screenrig.localhost:8088/api/v1/applications/APPLICATION_ID/kv/KEY'

PUT/api/v1/applications/{application_id}/kv/{key}¶

Put k v

operation: putKV
auth: accountBearer
headers: If-Match, Idempotency-Key
parameters: application_id (path, required), key (path, required), If-Match (header), Idempotency-Key (header, required)
request: KVWrite
responses: 200: KVEntry (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request PUT --header 'Authorization: Bearer SCREENRIG_TOKEN' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'http://api.screenrig.localhost:8088/api/v1/applications/APPLICATION_ID/kv/KEY'

json · schema-generated request body

{
  "value_base64": "string",
  "content_type": "string"
}

DELETE/api/v1/applications/{application_id}/kv/{key}¶

Delete k v

operation: deleteKV
auth: accountBearer
headers: If-Match, Idempotency-Key
parameters: application_id (path, required), key (path, required), If-Match (header, required), Idempotency-Key (header, required)
request: none
responses: 204: no body · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request DELETE --header 'Authorization: Bearer SCREENRIG_TOKEN' --header 'If-Match: "1"' --header 'Idempotency-Key: REQUEST_ID' 'http://api.screenrig.localhost:8088/api/v1/applications/APPLICATION_ID/kv/KEY'

Durable account events

GET/api/v1/events¶

List events

operation: listEvents
auth: accountBearer
headers: none
parameters: after (query)
request: none
responses: 200: EventList (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --header 'Authorization: Bearer SCREENRIG_TOKEN' 'http://api.screenrig.localhost:8088/api/v1/events'

GET/api/v1/events/stream¶

Stream events

operation: streamEvents
auth: accountBearer
headers: Last-Event-ID
parameters: after (query), Last-Event-ID (header)
request: none
responses: 200: string (text/event-stream) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --header 'Authorization: Bearer SCREENRIG_TOKEN' 'http://api.screenrig.localhost:8088/api/v1/events/stream'

Player pairing and sessions

POST/runtime/v1/pairing-sessions¶

Start pairing session

operation: startPairingSession
auth: none
headers: none
parameters: none
request: none
responses: 201: PairingSession (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request POST 'http://play.screenrig.localhost:8088/runtime/v1/pairing-sessions'

GET/runtime/v1/pairing-events¶

Stream pairing events

operation: streamPairingEvents
auth: pairingCookie
headers: none
parameters: none
request: none
responses: 200: string (text/event-stream) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --cookie 'SCREENRIG_COOKIE=SESSION' 'http://play.screenrig.localhost:8088/runtime/v1/pairing-events'

POST/runtime/v1/pairing-sessions/complete¶

Complete pairing session

operation: completePairingSession
auth: pairingCookie
headers: none
parameters: none
request: PairingComplete
responses: 200: PairingCompletion (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request POST --cookie 'SCREENRIG_COOKIE=SESSION' --header 'Content-Type: application/json' --data '@request.json' 'http://play.screenrig.localhost:8088/runtime/v1/pairing-sessions/complete'

json · schema-generated request body

{
  "completion_nonce": "string"
}

POST/runtime/v1/sessions¶

Create anonymous runtime session

operation: createAnonymousRuntimeSession
auth: none
headers: none
parameters: none
request: RuntimeSessionRequest
responses: 201: RuntimeSession (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request POST --header 'Content-Type: application/json' --data '@request.json' 'http://play.screenrig.localhost:8088/runtime/v1/sessions'

json · schema-generated request body

{
  "public_id": "string"
}

POST/runtime/v1/device-sessions¶

Create device runtime session

operation: createDeviceRuntimeSession
auth: pairedDeviceCookie
headers: none
parameters: none
request: none
responses: 201: RuntimeSession (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request POST --cookie 'SCREENRIG_COOKIE=SESSION' 'http://play.screenrig.localhost:8088/runtime/v1/device-sessions'

Runtime manifest, reports, and events

GET/runtime/v1/manifest¶

Get runtime manifest

operation: getRuntimeManifest
auth: runtimeCookie
headers: none
parameters: none
request: none
responses: 200: RuntimeManifest (application/json) · 304: no body · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --cookie 'SCREENRIG_COOKIE=SESSION' 'http://play.screenrig.localhost:8088/runtime/v1/manifest'

GET/runtime/v1/events¶

Stream runtime events

operation: streamRuntimeEvents
auth: runtimeCookie
headers: Last-Event-ID
parameters: after (query), Last-Event-ID (header)
request: none
responses: 200: string (text/event-stream) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --cookie 'SCREENRIG_COOKIE=SESSION' 'http://play.screenrig.localhost:8088/runtime/v1/events'

POST/runtime/v1/reports¶

Create runtime report

operation: createRuntimeReport
auth: pairedRuntimeCookie
headers: none
parameters: none
request: RuntimeReport
responses: 202: no body · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request POST --cookie 'SCREENRIG_COOKIE=SESSION' --header 'Content-Type: application/json' --data '@request.json' 'http://play.screenrig.localhost:8088/runtime/v1/reports'

json · schema-generated request body

{
  "severity": "info",
  "code": "manifest.activated",
  "context": null
}

POST/runtime/v1/manifests/{manifest_revision}/releases/{release_id}/launch¶

Launch application release

operation: launchApplicationRelease
auth: runtimeCookie
headers: none
parameters: manifest_revision (path, required), release_id (path, required)
request: none
responses: 201: ReleaseLaunch (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request POST --cookie 'SCREENRIG_COOKIE=SESSION' 'http://play.screenrig.localhost:8088/runtime/v1/manifests/MANIFEST_REVISION/releases/RELEASE_ID/launch'

Runtime application K/V

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

List runtime k v

Lists metadata for the application placement named by the current manifest. Requires the HttpOnly runtime session and the parent-only ScreenRig-Placement-Capability handle issued on the application placement. 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.

operation: listRuntimeKV
auth: runtimeCookie + placementCapability
headers: none
parameters: application_id (path, required)
request: none
responses: 200: KVList (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --header 'ScreenRig-Placement-Capability: PLACEMENT_CAPABILITY' --cookie 'SCREENRIG_COOKIE=SESSION' 'http://play.screenrig.localhost:8088/runtime/v1/apps/APPLICATION_ID/kv'

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

Get runtime k v

operation: getRuntimeKV
auth: runtimeCookie + placementCapability
headers: none
parameters: application_id (path, required), key (path, required)
request: none
responses: 200: KVEntry (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --header 'ScreenRig-Placement-Capability: PLACEMENT_CAPABILITY' --cookie 'SCREENRIG_COOKIE=SESSION' 'http://play.screenrig.localhost:8088/runtime/v1/apps/APPLICATION_ID/kv/KEY'

PUT/runtime/v1/apps/{application_id}/kv/{key}¶

Put runtime k v

operation: putRuntimeKV
auth: pairedRuntimeCookie + placementCapability
headers: If-Match, Idempotency-Key
parameters: application_id (path, required), key (path, required), If-Match (header), Idempotency-Key (header, required)
request: KVWrite
responses: 200: KVEntry (application/json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request PUT --header 'ScreenRig-Placement-Capability: PLACEMENT_CAPABILITY' --cookie 'SCREENRIG_COOKIE=SESSION' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'http://play.screenrig.localhost:8088/runtime/v1/apps/APPLICATION_ID/kv/KEY'

json · schema-generated request body

{
  "value_base64": "string",
  "content_type": "string"
}

DELETE/runtime/v1/apps/{application_id}/kv/{key}¶

Delete runtime k v

operation: deleteRuntimeKV
auth: pairedRuntimeCookie + placementCapability
headers: If-Match, Idempotency-Key
parameters: application_id (path, required), key (path, required), If-Match (header, required), Idempotency-Key (header, required)
request: none
responses: 204: no body · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request DELETE --header 'ScreenRig-Placement-Capability: PLACEMENT_CAPABILITY' --cookie 'SCREENRIG_COOKIE=SESSION' --header 'If-Match: "1"' --header 'Idempotency-Key: REQUEST_ID' 'http://play.screenrig.localhost:8088/runtime/v1/apps/APPLICATION_ID/kv/KEY'

Protected content and release assets

GET/content/v1/manifests/{manifest_revision}/media/{media_id}¶

Get protected media

operation: getProtectedMedia
auth: runtimeCookie
headers: Range, Sec-Fetch-Site, Sec-Fetch-Mode, Sec-Fetch-Dest
parameters: manifest_revision (path, required), media_id (path, required), Range (header), Sec-Fetch-Site (header), Sec-Fetch-Mode (header), Sec-Fetch-Dest (header)
request: none
responses: 200: no body · 206: no body · 416: Problem (application/problem+json) · 429: Problem (application/problem+json) · default: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --cookie 'SCREENRIG_COOKIE=SESSION' 'http://play.screenrig.localhost:8088/content/v1/manifests/MANIFEST_REVISION/media/MEDIA_ID'

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/account/device cookies and account bearer tokens never authorize this operation.

operation: consumeLaunchTicketOrGetReleaseAsset
auth: releaseLaunchTicket OR releaseGrantCookie
headers: Sec-Fetch-Site, Sec-Fetch-Mode, Sec-Fetch-Dest
parameters: asset_path (path, required), Sec-Fetch-Site (header), Sec-Fetch-Mode (header), Sec-Fetch-Dest (header)
request: none
responses: 200: no body · 302: no body · 403: Problem (application/problem+json) · 404: Problem (application/problem+json)

shell · contract-generated request shape

curl --noproxy '*' --request GET --cookie 'SCREENRIG_COOKIE=SESSION' 'https://r-RELEASE_HOST.apps.screenrig.ai/index.html'

Schema index

Generated names and required fields; use raw OpenAPI for complete JSON Schema.

Account — required: id, email, revision, status, used_bytes, reserved_bytes, screen_count, content_limit_bytes, screen_limit
AccountCreate — required: email
AccountCreated — required: account, token, issuance_id
Application — required: id, name, revision, state
ApplicationList — required: items
Capabilities — required: api_version, protocol_version, application_compressed_bytes, application_expanded_bytes, application_file_count, application_file_bytes, application_path_depth, application_path_bytes, playlist_max_pages, playlist_max_items_per_page, transition_max_duration_ms, screens_per_account, account_content_bytes, features
Event — required: cursor, sequence, type, severity, message, at
EventList — required: items, next_cursor
HealthResponse — required: status
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, content_type
ManifestActivatedContext — required: manifest_revision
ManifestActivatedReport — required: severity, code, context
Media — required: id, filename, kind, content_type, operation_id, sha256, bytes, revision, state, created_at, updated_at
MediaCommit — required: content_type, bytes, sha256
MediaList — required: items
MediaUploadDeclaration — required: filename, content_type, bytes, sha256
MediaUploadSession — required: id, operation, upload_url, method, headers, expires_at
NextAction — required: command, reason
Operation — required: id, kind, state, created_at, updated_at
OperationAccepted — required: id, operation_id
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
Playlist — required: id, name, revision, pages
PlaylistList — required: items
PlaylistWrite — required: name, pages
Problem — required: type, title, status, detail, instance, code, request_id, errors
ProblemField — required: field, code, detail
ReadyResponse — required: status, degraded
ReleaseLaunch — required: launch_url, expires_at
RuntimeAdvance — required: mode
RuntimeApplicationContent — required: type, applicationId, releaseId, launchUrl, origin, protocol, grantId
RuntimeApplicationPlacement — required: id, content, gridStyle, layer, capabilityHandle, capabilityExpiresAt
RuntimeConditionReport — required: severity, code, context
RuntimeContent — required: none
RuntimeGrid — required: style
RuntimeIframeContent — required: type, src, title
RuntimeImageContent — required: type, mediaId, src, fit, allowUpscale, grantId, sha256, bytes, contentType
RuntimeManifest — required: schemaVersion, manifestRevision, grantId, contentGeneration, screenId, screenLabel, playlistRevision, generatedAt, pages
RuntimePage — required: id, grid, transition, advance, items
RuntimePassivePlacement — required: id, content, gridStyle, layer
RuntimePlacement — required: none
RuntimeReport — required: none
RuntimeSession — required: paired, capabilities, event_cursor, public_url
RuntimeSessionRequest — required: public_id
RuntimeTransition — required: type, durationMs
RuntimeVideoContent — required: type, mediaId, src, fit, muted, loop, grantId, sha256, bytes, contentType
Screen — required: id, public_id, label, revision, manifest_revision, content_access_generation, state, created_at, updated_at
ScreenList — required: items
ScreenPatch — required: none
VersionResponse — required: version, commit, api_version, protocol_version