screenRIG
登录开始使用

API 参考

服务客户端 API

服务客户端

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

OpenAPI YAMLOpenAPI JSON问题 YAMLAPI 概览

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

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

服务客户端

GET/api/service-clients

列出服务客户端

项目服务客户端（规范：客户的服务器、脚本或 CI 任务，由项目拥有），最新优先，包含在线和已撤销，含其公钥、秘密 ID 和使用情况；绝不包含秘密或其摘要。需要项目权限。

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

参数

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

响应

状态含义正文和头部
200服务客户端。ServiceClientList（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/service-clients

创建服务客户端

创建一个由项目拥有的服务客户端，包含名称、权限（省略表示全部六项；每项必须是管理员拥有的，否则返回 403）、访问权限（默认读取或管理）及公钥 JWK（OKP Ed25519、EC P-256 或至少 2048 位 RSA）和/或密钥。密钥仅返回一次，仅此处。每个组织最多 50 个活跃客户端。

智能体需要身份范围、实时身份管理、其自身的项目能力管理授权和实时组织管理员角色；人员使用带有 project_id 的仪表盘会话和正文中带有新证明（类型 service_client_change，主题为客户端 ID，或创建时为项目 ID）。服务令牌被拒绝 403。

限定屏幕范围的成员不能连接智能体、签发凭据或管理项目的人员：outside_screen_scope（请询问项目所有者）。

身份验证
agentIdentityBearer 或 dashboardSession
请求主体
ServiceClientChange
操作 ID
createServiceClient

参数

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

请求主体字段

字段描述
project_id（可选，字符串）仅限控制台会话。
proof（可选，DashboardProof）
名称（可选，字符串）minLength：1 maxLength：80
功能（可选，数组）
access（可选，字符串）管理需要有权批准审核的人（403 approver_required）。允许的权限：“读取”、“提议”、“管理”。
key（可选，对象）公共 JWK：OKP Ed25519、EC P-256 或至少 2048 位的 RSA。
secret（可选，布尔值）生成密钥（仅创建）。
upload_scope（可选，UploadScope）

上传者可以使用的内容（docs/uploaders.md）：其可更改页面的播放列表，以及可上传到的媒体文件夹。文件夹仅限所列出的那些，不包括其子文件夹。写入时不指向项目有效对象的 id 会在其所在位置返回 invalid_request；之后被删除的对象会留下一个失效 id，它不授予任何权限。

范围在每次请求时读取，因此更改会在下一次请求时生效。

请求模板和响应
shell · 请求模板
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients'

响应

状态含义正文和头部
201服务客户端。ServiceClientResult（application/json）
402

feature_not_in_plan — 上传范围会使其成为上传者，而项目的计划不包含上传者；required_plan 指明包含上传者的计划。缩小范围以及移除范围始终允许。

问题 (application/problem+json)
403

outside_screen_scope - 调用方限定于屏幕，且请求所指明或涉及的屏幕、屏幕文件夹、选择器或受众超出了这些屏幕（docs/screen-scope.md）。范围之外的 ID 和不存在的 ID 得到相同的答复；errors[0].screen_scope 携带调用方的范围，写入会被整体拒绝，绝不会被缩小范围。

问题 (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/service-clients/{id}

获取服务客户端

项目的一个服务客户端。需要项目能力。

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

参数

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

响应

状态含义正文和头部
200服务客户端。ServiceClient（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/service-clients/{id}

更新服务客户端

重命名服务客户端或更改其权限（在管理员权限范围内）或访问权限。权限收窄会在几秒内使客户端当前令牌失效。

智能体需要身份范围、实时身份管理、其自身的项目能力管理授权和实时组织管理员角色；人员使用带有 project_id 的仪表盘会话和正文中带有新证明（类型 service_client_change，主题为客户端 ID，或创建时为项目 ID）。服务令牌被拒绝 403。

限定屏幕范围的成员不能连接智能体、签发凭据或管理项目的人员：outside_screen_scope（请询问项目所有者）。

身份验证
agentIdentityBearer 或 dashboardSession
请求主体
ServiceClientChange
操作 ID
updateServiceClient

参数

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

请求主体字段

字段描述
project_id（可选，字符串）仅限控制台会话。
proof（可选，DashboardProof）
名称（可选，字符串）minLength：1 maxLength：80
功能（可选，数组）
access（可选，字符串）管理需要有权批准审核的人（403 approver_required）。允许的权限：“读取”、“提议”、“管理”。
key（可选，对象）公共 JWK：OKP Ed25519、EC P-256 或至少 2048 位的 RSA。
secret（可选，布尔值）生成密钥（仅创建）。
upload_scope（可选，UploadScope）

上传者可以使用的内容（docs/uploaders.md）：其可更改页面的播放列表，以及可上传到的媒体文件夹。文件夹仅限所列出的那些，不包括其子文件夹。写入时不指向项目有效对象的 id 会在其所在位置返回 invalid_request；之后被删除的对象会留下一个失效 id，它不授予任何权限。

范围在每次请求时读取，因此更改会在下一次请求时生效。

请求模板和响应
shell · 请求模板
curl --request PATCH --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients/RESOURCE_ID'

响应

状态含义正文和头部
200服务客户端。ServiceClientResult（application/json）
402

feature_not_in_plan — 上传范围会使其成为上传者，而项目的计划不包含上传者；required_plan 指明包含上传者的计划。缩小范围以及移除范围始终允许。

问题 (application/problem+json)
403

outside_screen_scope - 调用方限定于屏幕，且请求所指明或涉及的屏幕、屏幕文件夹、选择器或受众超出了这些屏幕（docs/screen-scope.md）。范围之外的 ID 和不存在的 ID 得到相同的答复；errors[0].screen_scope 携带调用方的范围，写入会被整体拒绝，绝不会被缩小范围。

问题 (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/service-clients/{id}/keys

添加服务客户端密钥

注册第二个公钥 JWK（主体中的密钥）以实现零停机轮换；客户端最多持有两个。

智能体需要身份范围、实时身份管理、其自身的项目能力管理授权和实时组织管理员角色；人员使用带有 project_id 的仪表盘会话和正文中带有新证明（类型 service_client_change，主题为客户端 ID，或创建时为项目 ID）。服务令牌被拒绝 403。

限定屏幕范围的成员不能连接智能体、签发凭据或管理项目的人员：outside_screen_scope（请询问项目所有者）。

身份验证
agentIdentityBearer 或 dashboardSession
请求主体
ServiceClientChange
操作 ID
addServiceClientKey

参数

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

请求主体字段

字段描述
project_id（可选，字符串）仅限控制台会话。
proof（可选，DashboardProof）
名称（可选，字符串）minLength：1 maxLength：80
功能（可选，数组）
access（可选，字符串）管理需要有权批准审核的人（403 approver_required）。允许的权限：“读取”、“提议”、“管理”。
key（可选，对象）公共 JWK：OKP Ed25519、EC P-256 或至少 2048 位的 RSA。
secret（可选，布尔值）生成密钥（仅创建）。
upload_scope（可选，UploadScope）

上传者可以使用的内容（docs/uploaders.md）：其可更改页面的播放列表，以及可上传到的媒体文件夹。文件夹仅限所列出的那些，不包括其子文件夹。写入时不指向项目有效对象的 id 会在其所在位置返回 invalid_request；之后被删除的对象会留下一个失效 id，它不授予任何权限。

范围在每次请求时读取，因此更改会在下一次请求时生效。

请求模板和响应
shell · 请求模板
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients/RESOURCE_ID/keys'

响应

状态含义正文和头部
200服务客户端。ServiceClientResult（application/json）
403

outside_screen_scope - 调用方限定于屏幕，且请求所指明或涉及的屏幕、屏幕文件夹、选择器或受众超出了这些屏幕（docs/screen-scope.md）。范围之外的 ID 和不存在的 ID 得到相同的答复；errors[0].screen_scope 携带调用方的范围，写入会被整体拒绝，绝不会被缩小范围。

问题 (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/service-clients/{id}/keys/{kid}/remove

移除服务客户端密钥

移除密钥；客户端当前令牌将在几秒内结束。客户端至少保留一个密钥或秘密。

智能体需要身份范围、实时身份管理、其自身的项目能力管理授权和实时组织管理员角色；人员使用带有 project_id 的仪表盘会话和正文中带有新证明（类型 service_client_change，主题为客户端 ID，或创建时为项目 ID）。服务令牌被拒绝 403。

限定屏幕范围的成员不能连接智能体、签发凭据或管理项目的人员：outside_screen_scope（请询问项目所有者）。

身份验证
agentIdentityBearer 或 dashboardSession
请求主体
ServiceClientChange
操作 ID
removeServiceClientKey

参数

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

请求主体字段

字段描述
project_id（可选，字符串）仅限控制台会话。
proof（可选，DashboardProof）
名称（可选，字符串）minLength：1 maxLength：80
功能（可选，数组）
access（可选，字符串）管理需要有权批准审核的人（403 approver_required）。允许的权限：“读取”、“提议”、“管理”。
key（可选，对象）公共 JWK：OKP Ed25519、EC P-256 或至少 2048 位的 RSA。
secret（可选，布尔值）生成密钥（仅创建）。
upload_scope（可选，UploadScope）

上传者可以使用的内容（docs/uploaders.md）：其可更改页面的播放列表，以及可上传到的媒体文件夹。文件夹仅限所列出的那些，不包括其子文件夹。写入时不指向项目有效对象的 id 会在其所在位置返回 invalid_request；之后被删除的对象会留下一个失效 id，它不授予任何权限。

范围在每次请求时读取，因此更改会在下一次请求时生效。

请求模板和响应
shell · 请求模板
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients/RESOURCE_ID/keys/KID/remove'

响应

状态含义正文和头部
200服务客户端。ServiceClientResult（application/json）
403

outside_screen_scope - 调用方限定于屏幕，且请求所指明或涉及的屏幕、屏幕文件夹、选择器或受众超出了这些屏幕（docs/screen-scope.md）。范围之外的 ID 和不存在的 ID 得到相同的答复；errors[0].screen_scope 携带调用方的范围，写入会被整体拒绝，绝不会被缩小范围。

问题 (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/service-clients/{id}/secrets

添加服务客户端密钥秘密

生成第二个密钥，返回一次，用于零停机轮换；客户端最多持有两个。

智能体需要身份范围、实时身份管理、其自身的项目能力管理授权和实时组织管理员角色；人员使用带有 project_id 的仪表盘会话和正文中带有新证明（类型 service_client_change，主题为客户端 ID，或创建时为项目 ID）。服务令牌被拒绝 403。

限定屏幕范围的成员不能连接智能体、签发凭据或管理项目的人员：outside_screen_scope（请询问项目所有者）。

身份验证
agentIdentityBearer 或 dashboardSession
请求主体
ServiceClientChange
操作 ID
addServiceClientSecret

参数

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

请求主体字段

字段描述
project_id（可选，字符串）仅限控制台会话。
proof（可选，DashboardProof）
名称（可选，字符串）minLength：1 maxLength：80
功能（可选，数组）
access（可选，字符串）管理需要有权批准审核的人（403 approver_required）。允许的权限：“读取”、“提议”、“管理”。
key（可选，对象）公共 JWK：OKP Ed25519、EC P-256 或至少 2048 位的 RSA。
secret（可选，布尔值）生成密钥（仅创建）。
upload_scope（可选，UploadScope）

上传者可以使用的内容（docs/uploaders.md）：其可更改页面的播放列表，以及可上传到的媒体文件夹。文件夹仅限所列出的那些，不包括其子文件夹。写入时不指向项目有效对象的 id 会在其所在位置返回 invalid_request；之后被删除的对象会留下一个失效 id，它不授予任何权限。

范围在每次请求时读取，因此更改会在下一次请求时生效。

请求模板和响应
shell · 请求模板
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients/RESOURCE_ID/secrets'

响应

状态含义正文和头部
200服务客户端。ServiceClientResult（application/json）
403

outside_screen_scope - 调用方限定于屏幕，且请求所指明或涉及的屏幕、屏幕文件夹、选择器或受众超出了这些屏幕（docs/screen-scope.md）。范围之外的 ID 和不存在的 ID 得到相同的答复；errors[0].screen_scope 携带调用方的范围，写入会被整体拒绝，绝不会被缩小范围。

问题 (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/service-clients/{id}/secrets/{secret_id}/remove

移除服务客户端密钥秘密

移除密钥秘密；客户端当前令牌将在几秒内结束。

智能体需要身份范围、实时身份管理、其自身的项目能力管理授权和实时组织管理员角色；人员使用带有 project_id 的仪表盘会话和正文中带有新证明（类型 service_client_change，主题为客户端 ID，或创建时为项目 ID）。服务令牌被拒绝 403。

限定屏幕范围的成员不能连接智能体、签发凭据或管理项目的人员：outside_screen_scope（请询问项目所有者）。

身份验证
agentIdentityBearer 或 dashboardSession
请求主体
ServiceClientChange
操作 ID
removeServiceClientSecret

参数

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

请求主体字段

字段描述
project_id（可选，字符串）仅限控制台会话。
proof（可选，DashboardProof）
名称（可选，字符串）minLength：1 maxLength：80
功能（可选，数组）
access（可选，字符串）管理需要有权批准审核的人（403 approver_required）。允许的权限：“读取”、“提议”、“管理”。
key（可选，对象）公共 JWK：OKP Ed25519、EC P-256 或至少 2048 位的 RSA。
secret（可选，布尔值）生成密钥（仅创建）。
upload_scope（可选，UploadScope）

上传者可以使用的内容（docs/uploaders.md）：其可更改页面的播放列表，以及可上传到的媒体文件夹。文件夹仅限所列出的那些，不包括其子文件夹。写入时不指向项目有效对象的 id 会在其所在位置返回 invalid_request；之后被删除的对象会留下一个失效 id，它不授予任何权限。

范围在每次请求时读取，因此更改会在下一次请求时生效。

请求模板和响应
shell · 请求模板
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients/RESOURCE_ID/secrets/SECRET_ID/remove'

响应

状态含义正文和头部
200服务客户端。ServiceClientResult（application/json）
403

outside_screen_scope - 调用方限定于屏幕，且请求所指明或涉及的屏幕、屏幕文件夹、选择器或受众超出了这些屏幕（docs/screen-scope.md）。范围之外的 ID 和不存在的 ID 得到相同的答复；errors[0].screen_scope 携带调用方的范围，写入会被整体拒绝，绝不会被缩小范围。

问题 (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/service-clients/{id}/revoke

撤销服务客户端

永久撤销服务客户端：其密钥和秘密摘要被删除，记录保留以供审计，令牌在几秒内失效（传播已应用或待处理）。

智能体需要身份范围、实时身份管理、其自身的项目能力管理授权和实时组织管理员角色；人员使用带有 project_id 的仪表盘会话和正文中带有新证明（类型 service_client_change，主题为客户端 ID，或创建时为项目 ID）。服务令牌被拒绝 403。

限定屏幕范围的成员不能连接智能体、签发凭据或管理项目的人员：outside_screen_scope（请询问项目所有者）。

身份验证
agentIdentityBearer 或 dashboardSession
请求主体
ServiceClientChange
操作 ID
revokeServiceClient

参数

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

请求主体字段

字段描述
project_id（可选，字符串）仅限控制台会话。
proof（可选，DashboardProof）
名称（可选，字符串）minLength：1 maxLength：80
功能（可选，数组）
access（可选，字符串）管理需要有权批准审核的人（403 approver_required）。允许的权限：“读取”、“提议”、“管理”。
key（可选，对象）公共 JWK：OKP Ed25519、EC P-256 或至少 2048 位的 RSA。
secret（可选，布尔值）生成密钥（仅创建）。
upload_scope（可选，UploadScope）

上传者可以使用的内容（docs/uploaders.md）：其可更改页面的播放列表，以及可上传到的媒体文件夹。文件夹仅限所列出的那些，不包括其子文件夹。写入时不指向项目有效对象的 id 会在其所在位置返回 invalid_request；之后被删除的对象会留下一个失效 id，它不授予任何权限。

范围在每次请求时读取，因此更改会在下一次请求时生效。

请求模板和响应
shell · 请求模板
curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/service-clients/RESOURCE_ID/revoke'

响应

状态含义正文和头部
200服务客户端。ServiceClientResult（application/json）
403

outside_screen_scope - 调用方限定于屏幕，且请求所指明或涉及的屏幕、屏幕文件夹、选择器或受众超出了这些屏幕（docs/screen-scope.md）。范围之外的 ID 和不存在的 ID 得到相同的答复；errors[0].screen_scope 携带调用方的范围，写入会被整体拒绝，绝不会被缩小范围。

问题 (application/problem+json)
默认

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

问题 (application/problem+json)