# Application storage API reference

> Canonical HTML: https://screenrig.ai/docs/api/runtime-kv
> Source SHA-256: e0c997a2ab813502f0d99a41d2ed1d3d6b26dbaf1a3d7e514c1cce0278ff8422

Runtime application K/V. This group has 4 operations, each with its authentication, parameters, request body fields, request template and responses. The [API overview](https://screenrig.ai/docs/api.md) covers services, authentication, requests and retries, problem codes and versioning.

Replace uppercase placeholders. Save a schema-valid JSON body in request.json when required. Cookie examples use a local cookie jar from an authenticated session.

## Runtime application K/V

### GET /screen/apps/{application_id}/kv

**List Runtime KV**

Returns at most 200 entries in ascending key order and does not page; a namespace with more keys is only partly listed. Lists metadata for an application the screen's current content holds.

Runtime KV is authorized by the Player's runtime session (kv.read, and kv.write for writes) and the screen's current grant, which must hold a ready release of the application; a ScreenRig-Primitive-Capability header is ignored. Uploaded frames never call these routes and must use the validated parent SDK bridge.


Operation: listRuntimeKV.

- Authentication: runtimeCookie OR nativeSessionAuthorization
- Request body: none

#### Parameters

| Name | Send in | Required? | Description |
| --- | --- | --- | --- |
| application_id | path | required |  |

#### Request template

~~~sh
curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/apps/APPLICATION_ID/kv'
~~~

#### Responses

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

**Get Runtime KV**


Operation: getRuntimeKV.

- Authentication: runtimeCookie OR nativeSessionAuthorization
- Request body: none

#### Parameters

| Name | Send in | Required? | Description |
| --- | --- | --- | --- |
| application_id | path | required |  |
| key | path | required |  |

#### Request template

~~~sh
curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/apps/APPLICATION_ID/kv/KEY'
~~~

#### Responses

| Status | Meaning | Body and headers |
| --- | --- | --- |
| 200 | Manifest-authorized application KV value | RuntimeKVEntry (application/json) |
| default | Stable RFC 9457 problem response 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 /screen/apps/{application_id}/kv/{key}

**Put Runtime KV**


Operation: putRuntimeKV.

- Authentication: pairedRuntimeCookie OR nativeSessionAuthorization
- Request body: RuntimeKVWrite

#### Parameters

| Name | Send in | Required? | Description |
| --- | --- | --- | --- |
| application_id | path | required |  |
| key | path | required |  |
| If-Match | header | optional | Optional positive resource revision. Omit to create or overwrite a key; a supplied stale revision is revision_conflict. |
| Idempotency-Key | header | optional | Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically. |

#### Request body fields

| Field | Required? | Type | Description |
| --- | --- | --- | --- |
| value_base64 | required | string | maxLength: 1398104 |
| content_type | optional | string | default: "application/octet-stream" minLength: 1 maxLength: 127 |

#### Request template

~~~sh
curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://play.screenrig.ai/screen/apps/APPLICATION_ID/kv/KEY'
~~~

#### Responses

| Status | Meaning | Body and headers |
| --- | --- | --- |
| 200 | Paired-device KV mutation | RuntimeKVEntry (application/json); headers: RateLimit-Policy, RateLimit |
| default | Stable RFC 9457 problem response 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) |

### DELETE /screen/apps/{application_id}/kv/{key}

**Delete Runtime KV**


Operation: deleteRuntimeKV.

- Authentication: pairedRuntimeCookie OR nativeSessionAuthorization
- Request body: none

#### Parameters

| Name | Send in | Required? | Description |
| --- | --- | --- | --- |
| application_id | path | required |  |
| key | path | required |  |
| If-Match | header | optional | Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict. |
| Idempotency-Key | header | optional | Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically. |

#### Request template

~~~sh
curl --request DELETE --cookie cookies.txt --cookie-jar cookies.txt 'https://play.screenrig.ai/screen/apps/APPLICATION_ID/kv/KEY'
~~~

#### Responses

| Status | Meaning | Body and headers |
| --- | --- | --- |
| 204 | Paired-device KV deletion | no body; headers: RateLimit-Policy, RateLimit |
| default | Stable RFC 9457 problem response 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) |


## Sitemap

See the [public documentation sitemap](https://screenrig.ai/sitemap.md).