Pairing & sessions API Reference: Endpoints and Examples

OpenAPI YAML OpenAPI JSON problems YAML API overview

This group has 12 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.

Player pairing and sessions

POST/screen/pairing-sessions¶

Start Pairing Session

Creates one fleet-global expiring pairing session and sets the temporary HttpOnly Secure SameSite=Strict pairing cookie. An untrusted Origin or cross-site browser request is rejected with forbidden before rate-limit or pairing state is created.

Authentication: none
Request body: none
Operation ID: startPairingSession

Request template and responses

shell · request template

curl --request POST 'https://play.screenrig.ai/screen/pairing-sessions'

Responses

Status	Meaning	Body and headers
201	Exact six-character pairing code and expiry.	PairingSession (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

GET/stream/pairing-events¶

Stream Pairing Events

Authentication: pairingCookie
Request body: none
Operation ID: streamPairingEvents

Request template and responses

shell · request template

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/stream/pairing-events'

Responses

Status	Meaning	Body and headers
200	Authenticated temporary pairing SSE. The terminal pairing.claimed data is PairingClaimedEvent and contains only a non-secret completion nonce.	string (text/event-stream); headers: Cache-Control, X-Accel-Buffering
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/pairing-sessions/complete¶

Complete Pairing Session

Authentication: pairingCookie
Request body: PairingComplete
Operation ID: completePairingSession

Request body fields

Field	Description
completion_nonce (required, string)	pattern: "^[A-Za-z0-9_-]{43}$"

Request template and responses

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/pairing-sessions/complete'

Responses

Status	Meaning	Body and headers
200	Paired-device cookie issued; the Player next creates the ordinary paired runtime session.	PairingCompletion (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
404	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/sessions¶

Create Anonymous Runtime Session

Authentication: none
Request body: RuntimeSessionRequest
Operation ID: createAnonymousRuntimeSession

Request body fields

Field	Description
public_id (required, string)
playback (optional, PlaybackHandshake)	Optional playback handshake a Player declares at mint. It is a hint that selects behavior, never authorization: unknown members and entries of the wrong type are ignored, and a value that is not an object negotiates nothing. The mint response echoes the supported intersection as PlaybackGrant. adslot-v1 is granted only to paired sessions.
player (optional, PlayerIdentity)	Player self-identification, sent only on the three mint routes (docs/player-compatibility.md §3.1). It is a hint and never authorization, and it is not covered by the native proof. It is read tolerantly: unknown members are ignored, an invalid optional member is dropped on its own, and a player that is not an object or has no valid kind declares nothing. It is never a 400. A paired mint stores it on the screen for the operator fleet histogram.

Field

Description

public_id (required, string)

playback (optional, PlaybackHandshake)

Optional playback handshake a Player declares at mint. It is a hint that selects behavior, never authorization: unknown members and entries of the wrong type are ignored, and a value that is not an object negotiates nothing. The mint response echoes the supported intersection as PlaybackGrant. adslot-v1 is granted only to paired sessions.

player (optional, PlayerIdentity)

Player self-identification, sent only on the three mint routes (docs/player-compatibility.md §3.1). It is a hint and never authorization, and it is not covered by the native proof. It is read tolerantly: unknown members are ignored, an invalid optional member is dropped on its own, and a player that is not an object or has no valid kind declares nothing.

It is never a 400. A paired mint stores it on the screen for the operator fleet histogram.

Request template and responses

shell · request template

curl --request POST --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/sessions'

Responses

Status	Meaning	Body and headers
201	Read-only runtime session cookie	RuntimeSession (application/json); headers: RateLimit-Policy, RateLimit
404	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/device-sessions¶

Create Device Runtime Session

Authentication: pairedDeviceCookie
Request body: DeviceSessionRequest
Operation ID: createDeviceRuntimeSession

Request body fields

Field	Description
public_id (optional, string)	minLength: 1
playback (optional, PlaybackHandshake)	Optional playback handshake a Player declares at mint. It is a hint that selects behavior, never authorization: unknown members and entries of the wrong type are ignored, and a value that is not an object negotiates nothing. The mint response echoes the supported intersection as PlaybackGrant. adslot-v1 is granted only to paired sessions.
player (optional, PlayerIdentity)	Player self-identification, sent only on the three mint routes (docs/player-compatibility.md §3.1). It is a hint and never authorization, and it is not covered by the native proof. It is read tolerantly: unknown members are ignored, an invalid optional member is dropped on its own, and a player that is not an object or has no valid kind declares nothing. It is never a 400. A paired mint stores it on the screen for the operator fleet histogram.

Field

Description

public_id (optional, string)

minLength: 1

playback (optional, PlaybackHandshake)

player (optional, PlayerIdentity)

It is never a 400. A paired mint stores it on the screen for the operator fleet histogram.

Request template and responses

shell · request template

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/device-sessions'

Responses

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

POST/screen/native/pairing-sessions¶

Start Native Pairing Session

Creates a native-only pairing session from a player Ed25519 public key. Unclaimed native pairing lasts seventy-two hours. A successful claim reserves a screen and stores durable encrypted delivery independently of the locator expiry. It does not bind the public key to a project until signed completion for that exact pairing credential and nonce.

Cookies, query credentials, cross-site origins, and Authorization are rejected. Exact Idempotency-Key replay precedes new abuse admission. The response never sets a cookie. An already-bound or explicitly retired public key returns enrollment_bound.

Authentication: none
Request body: NativePairingStart
Operation ID: startNativePairingSession

Parameters

Name	Send in	Required?	Description
Idempotency-Key	header	required

Request body fields

Field	Description
kid (required, string)	pattern: "^[A-Za-z0-9_-]{43}$"
public_key (required, PlayerPublicKey)
signature (required, string)	minLength: 80 maxLength: 4096
host (optional, RuntimeHostHint)	The optional native host hint on pairing start, pairing completion, and identity session mint. It names a device and is never authorization. It is read tolerantly (docs/player-compatibility.md §1.1.1): unknown members are ignored, a malformed field or capabilities entry is dropped, at most 32 capabilities are kept, and a value that is not an object or a platform outside the pattern drops the whole hint. None of these refuses the request. A Player still sends only the registered platform values and the members below, because a pre-contract backend refuses anything else.
fleet_link (optional, string)	Optional fleet link secret from the Player URL fragment (#fleet=). A valid, enabled link that has not expired claims this pairing session for its project at once, or recovers the device's earlier screen; the answer's fleet_link reports which. Like host, it is read tolerantly: a malformed or unknown value never refuses the start. pattern: "^srfl_[A-Za-z0-9_-]{43}$"

Request template and responses

shell · request template

curl --request POST --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/native/pairing-sessions'

Responses

Status	Meaning	Body and headers
201	Native pairing code plus temporary ScreenRig-Pairing credential; no Set-Cookie.	NativePairingSession (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
409	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

GET/stream/native/pairing-events¶

Stream Native Pairing Events

Native-only pairing SSE authenticated by exactly one ScreenRig-Pairing Authorization header. Cookies and query credentials are rejected. The terminal event contains only the non-secret completion nonce.

Authentication: nativePairingAuthorization
Request body: none
Operation ID: streamNativePairingEvents

Request template and responses

shell · request template

curl --request GET --header 'Authorization: ScreenRig-Pairing PAIRING' 'https://play.screenrig.ai/stream/native/pairing-events'

Responses

Status	Meaning	Body and headers
200	Authenticated native pairing SSE whose terminal data is PairingClaimedEvent.	string (text/event-stream); headers: Cache-Control, X-Accel-Buffering
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
404	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/native/pairing-sessions/complete¶

Complete Native Pairing Session

Completes native pairing with a completion nonce and an EdDSA compact JWS (op=pairing.complete) whose request_hash binds the exact pairing credential and completion nonce. No cookie is accepted or set. No ScreenRig-Device credential is issued. The player next mints ScreenRig-Session from a possession proof.

Authentication: nativePairingAuthorization
Request body: NativePairingComplete
Operation ID: completeNativePairingSession

Request body fields

Field	Description
kid (optional, string)	pattern: "^[A-Za-z0-9_-]{43}$"
completion_nonce (required, string)	pattern: "^[A-Za-z0-9_-]{43}$"
public_key (required, PlayerPublicKey)
signature (required, string)	Compact EdDSA JWS with op=pairing.complete and request_hash binding the exact pairing credential and completion nonce. minLength: 80 maxLength: 4096
host (optional, RuntimeHostHint)	The optional native host hint on pairing start, pairing completion, and identity session mint. It names a device and is never authorization. It is read tolerantly (docs/player-compatibility.md §1.1.1): unknown members are ignored, a malformed field or capabilities entry is dropped, at most 32 capabilities are kept, and a value that is not an object or a platform outside the pattern drops the whole hint. None of these refuses the request. A Player still sends only the registered platform values and the members below, because a pre-contract backend refuses anything else.

Request template and responses

shell · request template

curl --request POST --header 'Authorization: ScreenRig-Pairing PAIRING' --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/native/pairing-sessions/complete'

Responses

Status	Meaning	Body and headers
200	Native pairing completion; no Set-Cookie and no device credential.	NativePairingCompletion (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
404	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
409	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/native/identity/challenges¶

Create Native Identity Challenge

Issues a short-lived nonce bound to one player public-key thumbprint. Cookies, query credentials, and Authorization are rejected.

Authentication: none
Request body: NativeIdentityChallengeRequest
Operation ID: createNativeIdentityChallenge

Request body fields

Field	Description
kid (required, string)	RFC 7638 SHA-256 JWK thumbprint. pattern: "^[A-Za-z0-9_-]{43}$"
public_key (optional, PlayerPublicKey)
op (required, string)	Allowed: "pairing.start", "pairing.complete", "session.mint", "identity.reset"
request_hash (required, string)	pattern: "^[0-9a-f]{64}$"

Request template and responses

shell · request template

curl --request POST --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/native/identity/challenges'

Responses

Status	Meaning	Body and headers
201	Challenge nonce for an EdDSA compact JWS proof; no Set-Cookie.	NativeIdentityChallenge (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
404	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/native/identity/sessions¶

Create Native Identity Runtime Session

Verifies an EdDSA compact JWS (op=session.mint) against the enrolled public key and returns a signed seven-day ScreenRig-Session. Paired Players renew after one day with jitter through this same signed mint; renewal replaces the credential without closing an existing runtime stream. Renewal metadata is optional to readers and does not require a Player update.

Cookies are neither accepted nor set. Exact Idempotency-Key replay precedes new abuse admission. An archived screen still mints a session so the player can show the archived glass. Session mint requires the exact durable project and screen binding established by signed completion; pending claim offers have no session authority.

Exact replay rechecks that binding and rejects retired identities.

Authentication: none
Request body: NativeIdentitySessionRequest
Operation ID: createNativeIdentityRuntimeSession

Parameters

Name	Send in	Required?	Description
Idempotency-Key	header	required

Request body fields

Field	Description
kid (required, string)	pattern: "^[A-Za-z0-9_-]{43}$"
public_key (required, PlayerPublicKey)
signature (required, string)	Compact EdDSA JWS with op=session.mint. minLength: 80 maxLength: 4096
host (optional, RuntimeHostHint)	The optional native host hint on pairing start, pairing completion, and identity session mint. It names a device and is never authorization. It is read tolerantly (docs/player-compatibility.md §1.1.1): unknown members are ignored, a malformed field or capabilities entry is dropped, at most 32 capabilities are kept, and a value that is not an object or a platform outside the pattern drops the whole hint. None of these refuses the request. A Player still sends only the registered platform values and the members below, because a pre-contract backend refuses anything else.
playback (optional, PlaybackHandshake)	Optional playback handshake a Player declares at mint. It is a hint that selects behavior, never authorization: unknown members and entries of the wrong type are ignored, and a value that is not an object negotiates nothing. The mint response echoes the supported intersection as PlaybackGrant. adslot-v1 is granted only to paired sessions.
player (optional, PlayerIdentity)	Player self-identification, sent only on the three mint routes (docs/player-compatibility.md §3.1). It is a hint and never authorization, and it is not covered by the native proof. It is read tolerantly: unknown members are ignored, an invalid optional member is dropped on its own, and a player that is not an object or has no valid kind declares nothing. It is never a 400. A paired mint stores it on the screen for the operator fleet histogram.

Request template and responses

shell · request template

curl --request POST --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/native/identity/sessions'

Responses

Status	Meaning	Body and headers
201	Paired native runtime session; no Set-Cookie.	NativeRuntimeSession (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
404	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
409	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/link-sessions¶

Create Screen Link Runtime Session

Mints a seven-day ScreenRig-Session from the screen link secret in the Player's address (the srsl_ value after #screen= in https://play.<domain>/player/#screen=…), for a browser that keeps no storage. The Player sends the secret on every load and again to renew; it holds no key and no pairing.

The session's device-key claim carries the link's id, so replacing or deleting the link ends it at the API and at the edge at once. Cookies are neither accepted nor set. Exact Idempotency-Key replay precedes new abuse admission. An archived screen still mints so the Player can show the archived glass.

A replaced, deleted or unknown link is screen_link_invalid (401, action clear_lkg). A present host replaces the stored host hint; player replaces the stored player.

Authentication: none
Request body: ScreenLinkSessionRequest
Operation ID: createScreenLinkRuntimeSession

Parameters

Name	Send in	Required?	Description
Idempotency-Key	header	required

Request body fields

Field	Description
screen_link (required, string)	pattern: "^srsl_[A-Za-z0-9_-]{43}$"
host (optional, RuntimeHostHint)	The optional native host hint on pairing start, pairing completion, and identity session mint. It names a device and is never authorization. It is read tolerantly (docs/player-compatibility.md §1.1.1): unknown members are ignored, a malformed field or capabilities entry is dropped, at most 32 capabilities are kept, and a value that is not an object or a platform outside the pattern drops the whole hint. None of these refuses the request. A Player still sends only the registered platform values and the members below, because a pre-contract backend refuses anything else.
playback (optional, PlaybackHandshake)	Optional playback handshake a Player declares at mint. It is a hint that selects behavior, never authorization: unknown members and entries of the wrong type are ignored, and a value that is not an object negotiates nothing. The mint response echoes the supported intersection as PlaybackGrant. adslot-v1 is granted only to paired sessions.
player (optional, PlayerIdentity)	Player self-identification, sent only on the three mint routes (docs/player-compatibility.md §3.1). It is a hint and never authorization, and it is not covered by the native proof. It is read tolerantly: unknown members are ignored, an invalid optional member is dropped on its own, and a player that is not an object or has no valid kind declares nothing. It is never a 400. A paired mint stores it on the screen for the operator fleet histogram.

Request template and responses

shell · request template

curl --request POST --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/link-sessions'

Responses

Status	Meaning	Body and headers
201	Paired native runtime session; no Set-Cookie.	NativeRuntimeSession (application/json); headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
403	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
409	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)

POST/screen/native/identity/reset¶

Reset Native Identity

The on-player reset, invoked only by an explicit confirmed operator action on the device. Failed pairing, session minting, or network access never automatically invokes this operation or clears the Player's local key. The endpoint verifies an EdDSA compact JWS (op=identity.reset).

The screen bound to this key is archived with archive_reason device_reset (already archived: unchanged), and the key stays bound to it: a device that still holds the key mints an archived session (dark glass) and resumes on unarchive with no re-pairing, and the key cannot start a new pairing (enrollment_bound).

Pending native claim offers for the key are withdrawn. A key that never bound a screen, or a key already retired by screen recovery, becomes terminal instead: it cannot pair or mint sessions again, and resetting a retired key never touches the screen its successor owns.

If the enrolled project has been deleted, signed reset makes the orphaned key terminal without archiving another screen, so the device can pair anew. After a lost response, the Player keeps its local key and can retry with a new challenge and fresh signed proof.

A network error alone does not confirm a reset or authorize clearing that key (docs/player-compatibility.md §5.1). No project bearer. Cookies are neither accepted nor set.

Authentication: none
Request body: NativeIdentityProof
Operation ID: resetNativeIdentity

Request body fields

Field	Description
kid (required, string)	pattern: "^[A-Za-z0-9_-]{43}$"
public_key (required, PlayerPublicKey)
signature (required, string)	Compact EdDSA JWS. minLength: 80 maxLength: 4096

Request template and responses

shell · request template

curl --request POST --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/native/identity/reset'

Responses

Status	Meaning	Body and headers
204	Reset recorded: a live-project bound screen archived with the key kept; a deleted-project, unbound, or retired key made terminal; or an unknown key answered as an idempotent no-op that archives nothing. An authenticated retry of any of these also succeeds. No Set-Cookie.	no body; headers: Cache-Control, RateLimit-Policy, RateLimit
400	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
401	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
404	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
429	Stable rate_limited problem on a Player-facing runtime or content route, in the runtime document shape (RuntimeProblem). Retry only after the authoritative Retry-After interval. Fixed-window denials also include the applicable RateLimit-Policy and RateLimit members; concurrency and byte-budget denials omit those optional disclosures.	RuntimeProblem (application/problem+json); headers: Retry-After, RateLimit-Policy, RateLimit
500	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)
default	Stable RFC 9457 problem response on a Player-facing runtime, content, or probe route, in the runtime document shape (RuntimeProblem). A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	RuntimeProblem (application/problem+json)