screenRIG
登录开始使用

API 参考

键值存储 API

应用键值存储

HTTP 参考。 由后端契约生成。浏览以下端点或下载 OpenAPI。

OpenAPI YAMLOpenAPI JSON问题 YAMLAPI 概览

此分组有 9 个操作，由 api/openapi.yaml 生成。可按路径、操作或认证筛选。每个端点都会列出其输入；展开后可查看请求模板和响应代码。模板需要您自己的值和符合架构的请求体。

用你的值替换大写占位符。对于JSON请求，请保存符合request.json模式的请求体。Cookie示例使用经过身份验证会话的本地Cookie存储。

应用键值存储

GET/api/applications/{application_id}/kv

列出 KV

返回最多 200 条按键升序排列的条目。next_cursor 是最后返回的键；传回作为 after 以获取下一页。无更多条目时 next_cursor 为 null。控制台会话在此读取其项目的条目，用于网页应用预览；控制台没有 KV 写入。

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
listKV

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
application_id路径必填
after查询可选
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv'

响应

状态含义正文和头部
200KV 条目KVList（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/applications/{application_id}/kv/{key}

获取 KV

身份验证
projectBearer 或 dashboardSession
请求主体
无
操作 ID
getKV

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
application_id路径必填
key路径必填
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv/KEY'

响应

状态含义正文和头部
200KV 条目KVEntry（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
PUT/api/applications/{application_id}/kv/{key}

放置 KV

身份验证
projectBearer
请求主体
KV写入
操作 ID
putKV

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
application_id路径必填
key路径必填
If-Matchheader可选可选正资源修订。省略则创建或覆盖键；提供的过期修订为 revision_conflict。
Idempotency-Keyheader可选省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段描述
value_base64（必填，字符串）maxLength：1398104
content_type（可选，字符串）默认：“application/octet-stream” minLength：1 maxLength：127
请求模板和响应
shell · 请求模板
curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv/KEY'

响应

状态含义正文和头部
200KV 条目KVEntry（application/json）
429

稳定的 rate_limited 问题。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。

问题 (application/problem+json)；头部：Retry-After，RateLimit-Policy，RateLimit
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
删除/api/applications/{application_id}/kv/{key}

删除 KV

身份验证
projectBearer
请求主体
无
操作 ID
deleteKV

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
application_id路径必填
key路径必填
If-Matchheader可选可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。
Idempotency-Keyheader可选省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。
请求模板和响应
shell · 请求模板
curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv/KEY'

响应

状态含义正文和头部
204已删除无正文
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
GET/api/applications/{application_id}/kv-webhooks

列出 KVWebhook

列出应用程序的传入键值 webhook，最旧优先（最多 20 个），每个包含其写入的键、摄取 URL 及写入后的 last_used_at。秘密永不在此返回。

身份验证
projectBearer
请求主体
无
操作 ID
listKVWebhooks

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
application_id路径必填
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv-webhooks'

响应

状态含义正文和头部
200应用的键值 webhook。KVWebhook列表（application/json）
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/applications/{application_id}/kv-webhooks

创建 KVWebhook

创建一个传入键值 webhook：一个 URL 写入此应用的一个键，因此外部系统（Zapier、Make、销售点、定时任务、curl）通过一次 HTTP POST 推送数据到屏幕；见 POST /api/applications/{application_id}/kv-webhooks/{webhook_id}/write.。该键可以尚不存在。

响应是密钥唯一出现的地方（与轮换响应一起）：请立即存储于发送系统；服务器保留摘要。应用最多可有 20 个 webhook（kv_webhook_limit_reached）。附加 kv_webhook.created。使用相同 Idempotency-Key 的完全重试在 24 小时内返回相同响应，包括密钥。

身份验证
projectBearer
请求主体
KVWebhook创建
操作 ID
createKVWebhook

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
application_id路径必填
Idempotency-Keyheader可选省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段描述
key（必填，字符串）minLength：1 maxLength：256 模式：“^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$”
描述（可选，字符串）发送给它的内容，供查看列表的人使用。修剪；不得包含凭证。maxLength：200
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv-webhooks'

响应

状态含义正文和头部
201已创建，含其网址和密钥。KVWebhook带密钥（application/json）；头部：Cache-Control
400invalid_request，包括格式错误的键或包含凭据的描述。问题 (application/problem+json)
404not_found — 应用不在此项目中。问题 (application/problem+json)
409kv_webhook_limit_reached 或 idempotency_mismatch。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
删除/api/applications/{application_id}/kv-webhooks/{webhook_id}

删除 KVWebhook

删除 webhook。其 URL 立即停止工作；其写入的密钥保持原值。附加 kv_webhook.deleted。

身份验证
projectBearer
请求主体
无
操作 ID
deleteKVWebhook

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
application_id路径必填
webhook_id路径必填某个应用的键值 webhook 的 ID。
Idempotency-Keyheader可选省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。
请求模板和响应
shell · 请求模板
curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv-webhooks/WEBHOOK_ID'

响应

状态含义正文和头部
204已删除。无正文
404not_found — webhook 不在此应用中。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/applications/{application_id}/kv-webhooks/{webhook_id}/rotate-secret

轮换 KVWebhook 密钥

替换webhook的密钥并返回新的密钥，仅一次。旧密钥立即失效；请更新发送系统。附加kv_webhook.secret_rotated。使用相同Idempotency-Key的精确重试在24小时内返回相同答案，包括密钥。

身份验证
projectBearer
请求主体
无
操作 ID
rotateKVWebhookSecret

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
application_id路径必填
webhook_id路径必填某个应用的键值 webhook 的 ID。
Idempotency-Keyheader可选省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv-webhooks/WEBHOOK_ID/rotate-secret'

响应

状态含义正文和头部
200带有新密钥的 webhook。KVWebhook带密钥（application/json）；头部：Cache-Control
404not_found — webhook 不在此应用中。问题 (application/problem+json)
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)
POST/api/applications/{application_id}/kv-webhooks/{webhook_id}/write

接收 KVWebhook

外部系统向此 URL 发送一个密钥的新值。仅通过 Authorization 头使用 webhook 自身密钥认证：Bearer <secret>，或使用 HTTP Basic，用户名为 webhook ID，密码为密钥。URL 或查询中的密钥绝不接受。

未知webhook、其他应用的webhook和错误密钥均返回相同的401。最多1 MiB的原始主体成为webhook的键值，Content-Type头为其content_type（缺失时为application/octet-stream；非单一媒体类型的头为invalid_request）。

写入为 PUT /api/applications/{application_id}/kv/{key}，无 If-Match：替换值，修订号递增，计量和配额检查如同任何 K/V 写入，为一次计费 API 请求且绝不会因余额而被拒绝，并追加 kv.updated。

Idempotency-Key（8 到 200 个字符）用于对发送方在 24 小时内对同一写入的重试去重，且相同键但请求体或内容类型不同则为 idempotency_mismatch；无此键每次 POST 都是新写入。响应为键的新元数据，绝不返回其值。

每个 webhook 每分钟最多 120 次写入；每次写入同时计入组织和该键的写入速率（PUT /api/card-data/{key}）。

身份验证
kvWebhookBearer 或 kvWebhookBasic
请求主体
string
操作 ID
receiveKVWebhook

参数

名称发送必需？描述
application_id路径必填
webhook_id路径必填某个应用的键值 webhook 的 ID。
Idempotency-Keyheader可选省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。
请求模板和响应
shell · 请求模板
curl --request POST --header 'Content-Type: */*' --data-binary '@request.bin' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv-webhooks/WEBHOOK_ID/write'

响应

状态含义正文和头部
200键的新元数据。KVWebhook写入结果（application/json）；头部：RateLimit-Policy，RateLimit，Cache-Control
400invalid_request — 请求体大于 1 MiB，Content-Type 不是单一媒体类型，或 Idempotency-Key 格式错误。问题 (application/problem+json)
401未授权 — 缺少或错误的凭据，或未知 webhook。WWW-Authenticate 指定 Bearer 和 Basic 领域。问题 (application/problem+json)
409idempotency_mismatch — Idempotency-Key 用于另一个请求体或内容类型。问题 (application/problem+json)
429

稳定的 rate_limited 问题。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。

问题 (application/problem+json)；头部：Retry-After，RateLimit-Policy，RateLimit
默认

稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。

问题 (application/problem+json)