screenRIG
登录开始使用

API 参考

应用 API

应用和操作

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

OpenAPI YAMLOpenAPI JSON问题 YAMLAPI 概览

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

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

应用和操作

GET/api/applications

列出应用

列出应用程序，最新优先，每页最多 500 条。名称为标签，无需唯一；通过 ID 访问应用程序。next_cursor 是最后返回行的位置，若还有更多行；将其作为 after 传回，配合同样的筛选条件，用于下一页。最后一页时 next_cursor 为 null。

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

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
after查询可选同一列表上一页的 next_cursor，使用相同过滤条件。省略时从最新行开始。非此类游标值为 invalid_request。
请求模板和响应
shell · 请求模板
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/applications'

响应

状态含义正文和头部
200应用ApplicationList（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

上传应用

将 CLI 生成的 tar.gz 直接流入有界持久暂存。元数据载于头部，服务器不进行 base64 包装或 JSON 实现。

API 前面的代理会终止约 100 s 内未响应的请求，因此慢速上行链路上的大归档在此失败；POST /api/applications/uploads 改为将归档直接发送到对象存储。

身份验证
projectBearer
请求主体
string
操作 ID
uploadApplication

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
Idempotency-Keyheader必填
ScreenRig-Archive-SHA256header必填
ScreenRig-Expanded-Bytesheader必填
ScreenRig-File-Countheader必填
ScreenRig-SDK-Versionheader可选
ScreenRig-Application-Nameheader可选

ASCII 应用名；与 ScreenRig-Application-Name* 互斥。前后空白被修剪。控制字符和重复头值被拒绝。解码名称限制为 120 个 Unicode 标量值。

ScreenRig-Application-Name*header可选

Unicode应用名称编码为RFC 8187 UTF-8''，后跟百分号编码的UTF-8字节（空语言，精确UTF-8字符集）。与ScreenRig-Application-Name互斥。拒绝无效转义、无效UTF-8、控制字符和重复头部值。

前后空白会被修剪；解码后的名称限制为120个Unicode标量值。两个名称头都不能重命名发布更新。这避免了HTTP头值中的原始Unicode。

请求模板和响应
shell · 请求模板
curl --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/gzip' --data-binary '@request.bin' 'https://screenrig.ai/api/applications'

响应

状态含义正文和头部
202上传已接受操作已接受（application/json）；头部：RateLimit-Policy，RateLimit
默认

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

问题 (application/problem+json)
POST/api/applications/{id}/releases

上传应用发布

使用相同的绑定 tar.gz 上传流程发布不可变的新版本所有权应用。If-Match 保护应用修订；接受时递增，成功发布时在 latest_ready_release 变更时再次递增。保留名称和应用身份。现有播放列表发布固定不变。

相同的幂等重试即使在修订更改后也会返回原始操作。API 前面的代理会终止约 100 s 内未响应的请求，因此慢速上行链路上的大归档在此失败；POST /api/applications/{id}/uploads 改为将归档直接发送到对象存储。

身份验证
projectBearer
请求主体
string
操作 ID
uploadApplicationRelease

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
If-Matchheader可选可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。
Idempotency-Keyheader必填
ScreenRig-Archive-SHA256header必填
ScreenRig-Expanded-Bytesheader必填
ScreenRig-File-Countheader必填
ScreenRig-SDK-Versionheader可选
请求模板和响应
shell · 请求模板
curl --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/gzip' --data-binary '@request.bin' 'https://api.screenrig.ai/api/applications/RESOURCE_ID/releases'

响应

状态含义正文和头部
202上传已接受操作已接受（application/json）；头部：RateLimit-Policy，RateLimit
默认

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

问题 (application/problem+json)
POST/api/applications/uploads

创建应用程序上传

声明直接上传一个由 CLI 生成的 tar.gz，该文件创建一个新应用程序。响应是对归档的恰好一次对象 PUT 的签名授权，因此字节直接进入对象存储，从不经过 API；API 的代理会终止约 100 s 内未响应的请求。

将归档 PUT 到 upload_url，然后用 POST /api/applications/uploads/{id}/commit 提交并等待操作。应用程序、其版本和接收操作从此响应起存在，如同在 POST /api/applications 之后。24 小时内未提交的上传失败，从未发布版本的应用程序会被删除。

相同的 Idempotency-Key 和主体以新签名的 URL 返回相同的上传。GET /api/capabilities 在提供这些路由的地方设置 features.application_direct_uploads。

身份验证
projectBearer
请求主体
ApplicationUploadDeclaration
操作 ID
createApplicationUpload

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
Idempotency-Keyheader必填

请求主体字段

字段描述
名称（可选，字符串）

新应用程序的名称，已修剪；最多 120 个 Unicode 字符且无控制字符。省略或为空则选择生成的名称。版本声明（POST /api/applications/{id}/uploads）不得携带名称。maxLength: 120

sha256（必填，字符串）归档字节的 SHA-256。pattern: "^[0-9a-f]{64}$"
compressed_bytes（必填，整数）归档大小（字节）。最小值：1 最大值：104857600
expanded_bytes（必填，整数）最小值：1 最大值：262144000
file_count（必填，整数）最小值：1 最大值：5000
sdk_version（可选，字符串）maxLength：64
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/applications/uploads'

响应

状态含义正文和头部
201对归档的恰好一次对象 PUT 的签名授权。原样发送返回的方法和每个返回的头信息；PUT 必须在 expires_at 之前开始，即声明后两小时。ApplicationUploadSession（application/json）；头信息：Cache-Control、RateLimit-Policy、RateLimit
默认

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

问题 (application/problem+json)
POST/api/applications/{id}/uploads

创建应用程序版本上传

声明直接上传所拥有应用程序的新不可变版本，响应方式与 POST /api/applications/uploads 相同。If-Match 如在 POST /api/applications/{id}/releases 上一样保护应用程序修订，接受后将其递增。主体不携带名称；版本保留其应用程序的名称。现有播放列表版本固定不变。

身份验证
projectBearer
请求主体
ApplicationUploadDeclaration
操作 ID
createApplicationReleaseUpload

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
If-Matchheader可选可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。
Idempotency-Keyheader必填

请求主体字段

字段描述
名称（可选，字符串）

新应用程序的名称，已修剪；最多 120 个 Unicode 字符且无控制字符。省略或为空则选择生成的名称。版本声明（POST /api/applications/{id}/uploads）不得携带名称。maxLength: 120

sha256（必填，字符串）归档字节的 SHA-256。pattern: "^[0-9a-f]{64}$"
compressed_bytes（必填，整数）归档大小（字节）。最小值：1 最大值：104857600
expanded_bytes（必填，整数）最小值：1 最大值：262144000
file_count（必填，整数）最小值：1 最大值：5000
sdk_version（可选，字符串）maxLength：64
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/applications/RESOURCE_ID/uploads'

响应

状态含义正文和头部
201对归档的恰好一次对象 PUT 的签名授权。原样发送返回的方法和每个返回的头信息；PUT 必须在 expires_at 之前开始，即声明后两小时。ApplicationUploadSession（application/json）；头信息：Cache-Control、RateLimit-Policy、RateLimit
默认

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

问题 (application/problem+json)
POST/api/applications/uploads/{id}/commit

提交应用程序上传

直接应用程序上传在其 PUT 完成后提交。服务器根据声明检查已暂存的归档（其大小和对象存储随 PUT 取得的 SHA-256 校验和），将其复制到自己的上传暂存区并将发布排队。

如在 POST /api/applications 之后一样，用 GET /api/operations/{id} 等待返回的 Operation，直到其 succeeded 或 failed。PUT 完成前的提交以 invalid_request 响应且不更改任何内容，因此可再次发送；与声明不同的已暂存字节使上传失败。重复提交返回相同的操作。

身份验证
projectBearer
请求主体
ApplicationUploadCommit
操作 ID
commitApplicationUpload

参数

名称发送必需？描述
ScreenRig-Projectheader可选已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
id路径必填
Idempotency-Keyheader必填

请求主体字段

字段描述
sha256（必填，字符串）模式："^[0-9a-f]{64}$"
compressed_bytes（必填，整数）最小值：1 最大值：104857600
请求模板和响应
shell · 请求模板
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/applications/uploads/RESOURCE_ID/commit'

响应

状态含义正文和头部
202归档已暂存，其发布已排队。操作（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/{id}

获取应用程序

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

参数

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

响应

状态含义正文和头部
200应用应用（application/json）
默认

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

问题 (application/problem+json)
PATCH/api/applications/{id}

重命名应用

更改经过身份验证项目拥有的应用显示名称。名称会被修剪，包含 1 到 120 个无控制字符的 Unicode 字符，项目内可重复。保留应用身份、发布、K/V 数据和播放列表发布锁定。

名称更改会推进应用修订版本并触发 application.updated；相同名称则无操作。If-Match 可选地保护修订版本。相同的幂等重试在后续元数据更改后返回原始响应。

身份验证
projectBearer
请求主体
ApplicationRename
操作 ID
renameApplication

参数

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

请求主体字段

字段描述
名称（必填，字符串）修剪后的显示名称；拒绝控制字符和空名称。minLength：1 maxLength：120
请求模板和响应
shell · 请求模板
curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/applications/RESOURCE_ID'

响应

状态含义正文和头部
200应用已重命名。应用（application/json）；头部：ETag
412revision_conflict — If-Match 已过期；错误的 current_revision 包含当前版本。问题 (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/{id}

删除应用

删除一个由认证项目拥有的应用及其所有版本。项目持有者具有权威；未知或其他项目ID为not_found。If-Match保护应用版本。活动清单引用会以application_in_use阻止删除；无强制删除路径。

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

参数

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

响应

状态含义正文和头部
204应用及发布已标记为删除。无正文
409application_in_use — 有一个活动清单仍引用该应用的某个版本。问题 (application/problem+json)
412revision_conflict — If-Match 已过期；错误的 current_revision 包含当前版本。问题 (application/problem+json)
默认

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

问题 (application/problem+json)
GET/api/operations/{id}

获取操作

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

参数

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

响应

状态含义正文和头部
200操作操作（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/operations/{id}/cancel

取消操作

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

参数

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

响应

状态含义正文和头部
200已取消持久操作。当前工作者围栏无法再完成它。操作（application/json）
默认

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

问题 (application/problem+json)