项目 API 参考：端点与示例

OpenAPI YAML OpenAPI JSON 问题 YAML API 概览

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

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

项目、邀请和登录

GET/api/project/deletion-preview¶

预览项目删除代理

返回当前确认详情、删除阻塞项和将断开连接的归档设备。当调用者无权删除项目（仅所有者或组织管理员有权；智能体为其负责人）或存在阻塞时，allowed 为 false 并附带原因。

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

参数

名称	发送	必需？	描述
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
project_id	查询	可选	预期项目 ID；更改选择将被拒绝。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/project/deletion-preview'

响应

状态	含义	正文和头部
200	项目生命周期结果	ProjectDeletionPreview（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/project/owner¶

转移项目所有者智能体

所有者将所有权转让给已验证的现有项目成员；这不授予新的成员身份。新所有者的成员身份会离开任何 screen_scope 和 upload_scope，因此新所有者可触及整个项目。

项目所属组织中身为成员的管理员，其控制台会话以同样方式转让所有权，不论项目现由谁拥有；不是成员的组织管理员则使用 PUT /api/organizations/{org_id}/projects/{project_id}/owner.

身份验证: projectBearer 或 dashboardSession
请求主体: ProjectOwnerTransfer
操作 ID: transferProjectOwnerAgent

参数

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

请求主体字段

字段	描述
project_id（可选，字符串）	预期项目 ID。如果当前凭据或 cookie 会话针对其他项目，服务器拒绝该操作；浏览器客户端发送页面的项目 ID。minLength: 1 maxLength: 200
user_id（必填，字符串）	minLength：1 maxLength：200

请求模板和响应

shell · 请求模板

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/project/owner'

响应

状态	含义	正文和头部
200	项目生命周期结果	ProjectContext（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/project/move¶

移动项目代理

所有者授权的移动将屏幕占用和新使用原子地转移到目标付款方；历史费用保持其付款方。已有其套餐允许数量活跃项目的目标位置会返回 project_limit_reached，其 required_plan 指明有空位的套餐，Enterprise 中则没有。

身份验证: projectBearer 或 dashboardSession
请求主体: ProjectMove
操作 ID: moveProjectAgent

参数

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

请求主体字段

字段	描述
project_id（可选，字符串）	预期项目 ID。如果当前凭据或 cookie 会话针对其他项目，服务器拒绝该操作；浏览器客户端发送页面的项目 ID。minLength: 1 maxLength: 200
organization_id（必填，字符串）	minLength：1 maxLength：200

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/project/move'

响应

状态	含义	正文和头部
200	项目生命周期结果	ProjectContext（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/project/moves¶

允许项目移动智能体

列出所有者管理的目的地或其验证域与其验证电子邮件匹配的目的地。

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

参数

名称	发送	必需？	描述
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
project_id	查询	可选	预期项目 ID；更改选择将被拒绝。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/project/moves'

响应

状态	含义	正文和头部
200	项目生命周期结果	ProjectMoveDestinations（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/projects¶

列出智能体项目

列出身份的所有活动成员身份，含组织和所有者上下文，包括此令牌或其授权同意中省略的成员身份。每条记录标记 in_token；发现不增加权限且无 64 项目限制。

身份验证: agentIdentityBearer 或 dashboardSession
请求主体: 无
操作 ID: listAgentProjects

参数

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

请求模板和响应

shell · 请求模板

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/projects'

响应

状态	含义	正文和头部
200	项目生命周期结果	ProjectContextList（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/projects¶

创建智能体项目

创建一个由已验证负责人拥有的命名项目。若无组织名称，则归入该人员已验证域的组织，否则归入当前项目的组织，否则归入该人员最近管理或拥有的免费组织，否则创建新组织。

组织名称精确匹配一个可见项，否则创建新组织。人员持有一个免费 Standard 组织；超出则为 free_organization_limit，并命名其持有的组织。

一个组织最多拥有其套餐允许数量的活跃项目（Standard 1 个，Plus 3 个，Premium 10 个，Education 50 个，Enterprise 100 个，可由其 featureset 扩大）；再多一个就是 project_limit_reached，其 required_plan 指明有空位的套餐，Enterprise 中则没有（请联系支持）。

精确幂等重试在 10 分钟内重新传递其密封的成员凭证。注册不受限制限制。

使用代理访问 JWT（身份范围，access:manage，拥有身份访问 Manage 的授权）时不发放项目令牌；项目加入拥有 Manage 和所有权限的授权，使用其 project_id 刷新返回对应令牌。

身份验证: agentIdentityBearer 或 dashboardSession
请求主体: ProjectCreate
操作 ID: createAgentProject

参数

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

请求主体字段

字段	描述
名称（必填，ProjectName）	修剪后的可打印项目名称。拒绝控制字符、类似URL的文本、@、www.及://。minLength：1 maxLength：60
organization_id（可选，字符串）	minLength：1 maxLength：200
organization_name（可选，ProjectName）	修剪后的可打印项目名称。拒绝控制字符、类似URL的文本、@、www.及://。minLength：1 maxLength：60

请求模板和响应

shell · 请求模板

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/projects'

响应

状态	含义	正文和头部
201	项目生命周期结果	已创建项目（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/invitations¶

列出邀请

列出当前项目的邀请生命周期记录，不包括登录重置。接收地址对拥有项目可见，项目提供了这些地址。令牌和凭证 URL 永不列出。

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

参数

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

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/invitations'

响应

状态	含义	正文和头部
200	列出当前项目的邀请生命周期记录，不包括登录重置。	InvitationList（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/invitations¶

创建邀请

创建成员或广告买家邀请。邮件投递不返回凭据。链接投递仅限成员，返回一个 URL，包括 24 小时内的幂等重放。邮件邀请七天后过期；链接 24 小时后过期。同类、同地址、同项目的未处理邮件邀请将被复用。

限定屏幕范围的成员不能邀请人员（outside_screen_scope）。

向将成为项目所属组织外部访客（该组织不是其主组织）的人员发送 project_member 邮件邀请时，须遵守该组织的访客策略；策略（allow、domains 或 none）不准许该地址时，返回 guest_not_allowed（403）。接受邀请时会再次检查。

员工和组织自己的管理员均获豁免。邀请上的 screen_scope 属于屏幕范围，Enterprise 计划包含该功能；计划不含该功能的项目会被拒绝并返回 feature_not_in_plan（402）。

身份验证: projectBearer 或 dashboardSession
请求主体: InvitationCreate
操作 ID: createInvitations

参数

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

请求主体字段

字段	描述
kind（必填，字符串）	允许值：“project_member”、“ad_buyer”
delivery（可选，字符串）	允许：“email”、“link”，默认：“email”
电子邮件（可选，数组）
advertising（可选，InvitationAdvertising）	卖方拥有的范围：至少一个屏幕或广告位。仅屏幕、仅广告位或两者皆可。
upload_scope（可选，UploadScope）	上传者可以使用的内容（docs/uploaders.md）：其可更改页面的播放列表，以及可上传到的媒体文件夹。文件夹仅限所列出的那些，不包括其子文件夹。写入时不指向项目有效对象的 id 会在其所在位置返回 invalid_request；之后被删除的对象会留下一个失效 id，它不授予任何权限。范围在每次请求时读取，因此更改会在下一次请求时生效。
screen_scope（可选，ScreenScope）	带范围的成员或智能体可以操作的内容（docs/screen-scope.md）：所列屏幕文件夹及其内部每个文件夹中的屏幕，以及所列屏幕。所有 ID 中至少一个。写入时不指向项目现存文件夹或屏幕的 ID，在其位置为 invalid_request；之后的删除会留下不授予任何权限的无效 ID。范围在每次请求时读取，因此更改会在下一次请求时生效。标签永远不是范围。

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/invitations'

响应

状态	含义	正文和头部
201	创建成员或广告买家邀请。	InvitationCreated（application/json）；头部：RateLimit-Policy，RateLimit
402	feature_not_in_plan — 屏幕范围需要 Enterprise，上传范围（上传者）需要 Plus；该问题指明功能、账户所在的计划和 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)
429	稳定的 rate_limited 问题。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。	问题 (application/problem+json)；头部：Retry-After，RateLimit-Policy，RateLimit

POST/api/invitations/{id}/revoke¶

撤销邀请

撤销未处理的邀请。已接受的邀请返回 invitation_consumed。限定屏幕范围的成员不能撤销邀请（outside_screen_scope）。

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

参数

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

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/invitations/RESOURCE_ID/revoke'

响应

状态	含义	正文和头部
204	撤销未完成的邀请。	无正文
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/sign-in-resets¶

请求登录重置

接受登录重置请求，但不透露该地址是否属于某人。

地址未验证的人员（例如自助注册的人员）同样会被找到，完成该重置（其所有者必须通过 replace_unverified_account 确认）会为该收件箱的所有者创建一个新账户（一个带有本次重置所设凭证的新人员，以及新的组织和项目），并删除未验证的人员，因为从未有人证明该地址属于此人。

重置链接在最后一次请求后一小时过期。在某人的链接仍有效且创建不到一天时，再次请求会重新发送同一链接（最多每十分钟一次），并将过期时间延至请求后一小时，因此请求不会让收件箱中已有的链接失效；否则由新链接替换。每个地址没有次数限制。

完成重置会删除此人的其他通行密钥（密码重置时删除所有通行密钥），在新凭据为通行密钥时删除密码，放弃待处理的邮箱变更，并结束所有会话。无论是否有此人，该请求还会重新发送最多十封寄往该邮箱的邀请，每封邀请每小时最多一次。

在联系邮箱匹配的最近十个未删除项目中，每个具有目录内套餐且注册所有权仍待认领的活跃项目都会重新收到注册邀请，即使该邀请已经过期，或收件人已经作为普通成员加入。

使用现有登录接受该注册邀请即可完成所有权认领；仅请求恢复不会改变所有权或凭据。发往具有目录内套餐的活跃项目的待处理成员和广告买家邮件邀请，以及发往有效组织的待处理组织管理员邀请，将按从新到旧的顺序占用剩余名额。

重新发送的邀请保留原 ID，并获得新的链接和有效期；旧链接失效，项目的待处理邀请数量保持不变。已过期的注册邀请会作为新邀请重新创建，再次占用一个邀请名额，因此计数增加一；如果项目已满，则跳过。

其他已过期的邀请，以及已撤销、已接受或通过链接共享的邀请，都不会重新发送。

身份验证: 无
请求主体: SignInResetRequest
操作 ID: requestSignInReset

参数

名称	发送	必需？	描述
Idempotency-Key	header	必填

请求主体字段

字段	描述
email（必填，字符串）	minLength：3 maxLength：254 格式：“email”

请求模板和响应

shell · 请求模板

curl --request POST --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/sign-in-resets'

响应

状态	含义	正文和头部
202	接受登录重置请求，但不透露该地址是否属于某人。	SignInResetAccepted（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)
429	稳定的 rate_limited 问题。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。	问题 (application/problem+json)；头部：Retry-After，RateLimit-Policy，RateLimit

POST/api/enrollments¶

注册 CLI

通过显式捆绑 CLI 注册创建新项目及其第一个智能体，即使联系邮箱已属于某人或项目。联系邮箱保持未验证且不授予权限；格式错误的地址返回 invalid_request。

在同一事务中排队一个注册邀请。project_name 是可选的；省略时使用可读的两个词名称。精确幂等重放优先于速率限制。在报告成功之前持久化永久凭证；其重放信封在 issuance_expires_at 过期，之后的重试返回 credential_issuance_expired。

幂等记录有效期为 24 小时。

身份验证: 无
请求主体: CLIEnrollmentRequest
操作 ID: enrollCLI

参数

名称	发送	必需？	描述
Idempotency-Key	header	必填

请求主体字段

字段	描述
credential_format（可选，字符串）	必须是 oauth，响应代理 JWT 配对（CLIEnrollmentOAuth）。legacy 或省略时响应 410 client_update_required，因为旧永久令牌已退役。不发放代理 JWT 的服务器响应 not_ready。允许值：“oauth”、“legacy”
intent（可选，字符串）	可选的注册目的。省略或 signage 保持 screens=true，advertiser=false。advertising 设置 advertiser=true，screens=false，且永不更改计费计划分配。允许值：“signage”、“advertising”
client_id（必填，字符串）	基于 32 字节 CSPRNG 生成并在首次请求前持久化的稳定匿名安装身份。它是速率限制材料，不是项目凭证。模式："^cli_[A-Za-z0-9_-]{43}$"
email（可选，字符串）	未验证的项目联系地址。必须恰好提供一个电子邮件或agentid_claim。注册总是创建新项目并排队其邀请；仅地址不授予权限。minLength：3 maxLength：254 格式：“email”
agentid_claim（可选，字符串）	来自 AgentID 登录页面的一次性 AgentID 认领码。必须提供 email 或 agentid_claim 中的一个。验证的 AgentID 所有者地址成为项目联系人和邀请接收者。模式："^agid_[A-Za-z0-9_-]{43}$"
beta_key（可选，字符串）	服务器配置了注册测试密钥时必填。服务器不限制注册时可省略。
名称（可选，字符串）	默认：“Agent” minLength：1 maxLength：80
agent_type（可选，字符串）	默认：“cli” 模式：“^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$”
平台（可选，字符串）	maxLength：80
version（可选，字符串）	maxLength：40
install_source（可选，字符串）	可选。集成的安装来源：主机，以及斜杠之后的市场（claude/screenrig, codex/screenrig, grok/screenrig），或单独的主机，例如 npm。该值由软件上报而非由人员提供，因此缺失或格式错误的值会被忽略，且绝不会导致注册失败。它只统计安装来自何处，不授予任何权限。pattern: "^[a-z][a-z0-9-]{0,31}(/[a-z0-9][a-z0-9._-]{0,63})?$"
project_name（可选，ProjectName）	修剪后的可打印项目名称。拒绝控制字符、类似URL的文本、@、www.及://。minLength：1 maxLength：60
setup_code（可选，字符串）	用户连同设置提示从网站复制的可选设置码（由四位字母数字组成的两组，忽略大小写和连字符）。它把新项目与该次网站访问关联起来；未知或已过期的设置码会被忽略，且绝不会导致注册失败。它不授予任何权限。 pattern: "^[0-9A-Za-z]{4}-?[0-9A-Za-z]{4}$"
组织（可选，ProjectName）	修剪后的可打印项目名称。拒绝控制字符、类似URL的文本、@、www.及://。minLength：1 maxLength：60

请求模板和响应

shell · 请求模板

curl --request POST --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/enrollments'

响应

状态	含义	正文和头部
201	新项目和永久承载凭证。项目携带其修剪后的未验证联系地址。持久化并验证令牌后报告注册成功。凭证无计划过期，但其加密的精确重试交付信封仅存在至 issuance_expires_at。	CLIEnrollmentOAuth（application/json）；头信息：Cache-Control，RateLimit-Policy，RateLimit
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
409	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
410	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
429	稳定的 rate_limited 问题。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。	问题 (application/problem+json)；头部：Retry-After，RateLimit-Policy，RateLimit
500	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (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/agentid/start¶

开始智能体 ID 登录

在从运行时公共源派生的 API 主机上启动 AgentID（OIDC）浏览器登录（https://play.<domain> -> https://api.<domain>）。设置一次性绑定 Cookie 并重定向到带有 PKCE S256 的 AgentID 授权端点。仅在 API 主机响应。

当依赖方没有客户端 ID 和密钥时，路由呈现一个简单的不可用页面，状态码为 503。

身份验证: 无
请求主体: 无
操作 ID: startAgentIDSignIn

请求模板和响应

shell · 请求模板

curl --request GET 'https://api.screenrig.ai/agentid/start'

响应

状态	含义	正文和头部
302	重定向到 AgentID 授权端点。	无正文
503	AgentID 登录不可用。	字符串（text/html）
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

GET/agentid/callback¶

完成Agent ID登录

在API主机上完成AgentID浏览器登录。要求iss等于配置的发行者，绑定cookie，且单次使用事务未过期。

使用 client_secret_basic 和 PKCE 交换代码，验证 ES256 id_token（iss、aud、exp 允许60秒偏差、nonce）与缓存 JWKS，调用 userinfo 并执行所有者规则，然后渲染一次性声明码页面。已绑定代理的主体渲染已注册页面。

此路由从不创建项目、身份或邀请。

身份验证: 无
请求主体: 无
操作 ID: completeAgentIDSignIn

参数

名称	发送	必需？
code	查询	可选
状态	查询	可选
iss	查询	可选
错误	查询	可选

请求模板和响应

shell · 请求模板

curl --request GET 'https://api.screenrig.ai/agentid/callback'

响应

状态	含义	正文和头部
200	带插件安装步骤的一次性 AgentID 认领码页面。	字符串（text/html）
409	AgentID 主题已注册。	字符串（text/html）
503	AgentID 登录不可用。	字符串（text/html）
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

GET/api/project¶

获取项目

调用项目。不扣除 1 额度 API 计量，因此额度为零的项目仍可读取剩余额度并恢复。成功的项目主体、认证的 /api JSON 和问题响应包含 ScreenRig-Credits-Remaining、ScreenRig-Credits-Reset 和 ScreenRig-Credits-Included，均为整数额度。

SSE、运行时、内容和未认证响应省略它们。

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

参数

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

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/project'

响应

状态	含义	正文和头部
200	项目	项目 (application/json)；头部：ScreenRig-Credits-Remaining，ScreenRig-Credits-Reset，ScreenRig-Credits-Included，ScreenRig-Credits-Low
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

PATCH/api/project¶

更新项目

重命名当前项目。名称包含1至60个可打印字符，不得包含类似URL的文本。

身份验证: projectBearer 或 dashboardSession
请求主体: ProjectPatch
操作 ID: updateProject

参数

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

请求主体字段

字段	描述
project_id（可选，字符串）	预期项目 ID。如果当前凭据或 cookie 会话针对其他项目，服务器拒绝该操作；浏览器客户端发送页面的项目 ID。minLength: 1 maxLength: 200
名称（必填，ProjectName）	修剪后的可打印项目名称。拒绝控制字符、类似URL的文本、@、www.及://。minLength：1 maxLength：60

请求模板和响应

shell · 请求模板

curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/project'

响应

状态	含义	正文和头部
200	重命名当前项目。	项目 (application/json)
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

删除/api/project¶

删除项目智能体

仅项目所有者或其组织管理员可删除；其他调用者拒绝，返回 forbidden。人员必须是项目成员。

代理需要目标成员项目能力并为其负责人删除，负责人必须是所有者或组织管理员；无负责人的代理无法删除，除非是项目注册时无人接受注册的代理。

还需要当前名称和修订版本，零个非归档屏幕，钱包中无额度、预订或欠款。免费或启动条款下产生的负余额不会阻止；删除时通过 project_delete_writeoff 账目冲销。排队成员通知并使用不可逆的墓碑。

身份验证: projectBearer 或 dashboardSession
请求主体: ProjectDeleteConfirmation
操作 ID: deleteProjectAgent

参数

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

请求主体字段

字段	描述
project_id（可选，字符串）	预期项目 ID。如果当前凭据或 cookie 会话针对其他项目，服务器拒绝该操作；浏览器客户端发送页面的项目 ID。minLength: 1 maxLength: 200
empty_only（可选，布尔值）	删除事务中要求 Screens 项目为空，包括内容、其他智能体或成员、工作和通信。CLI 还要求其保存的注册来源后才使用此清理保护。省略则保留显式成员删除。
名称（必填，ProjectName）	修剪后的可打印项目名称。拒绝控制字符、类似URL的文本、@、www.及://。minLength：1 maxLength：60
revision（必填，整数）	最小值：1

请求模板和响应

shell · 请求模板

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/project'

响应

状态	含义	正文和头部
200	项目生命周期结果	DeletedProject（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/project/capabilities¶

获取项目功能

调用项目的计划、独立广告主/屏幕标志及其版本、派生的有效能力集、其拥有的计划功能（plan_features）以及其限制（limits）。绝不反映客户端声明；未知计划拒绝访问。

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

参数

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

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/project/capabilities'

响应

状态	含义	正文和头部
200	项目功能。	ProjectCapabilities（application/json）；头部：Cache-Control
403	禁止 - 项目计划不在目录中。	问题 (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/organizations/{org_id}/audit¶

列出组织审计

组织自己的审计日志：其管理员、域名和账单设置的变更，条目、筛选条件和格式均与 GET /api/audit 相同。需要组织管理员。这是审计日志功能的一部分，Enterprise 计划包含该功能；计划不含该功能的组织会被拒绝并返回 feature_not_in_plan（402）。

每个计划都会记录其更改。

身份验证: dashboardSession
请求主体: 无
操作 ID: listOrganizationAudit

参数

名称	发送	必需？	描述
org_id	路径	必填
操作者	查询	可选
actor_kind	查询	可选
来源	查询	可选
操作	查询	可选
自从	查询	可选
直到	查询	可选
游标	查询	可选
限制	查询	可选
格式	查询	可选	json（默认）以 JSON 返回报告。csv、xlsx 和 pdf 以附件形式返回相同的行（分页报告的每一页，最多 50000 行）。

请求模板和响应

shell · 请求模板

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/audit'

响应

状态	含义	正文和头部
200	一页条目，或筛选后日志的文件。	AuditList (application/json), string (text/csv), string (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet), string (application/pdf)
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
402	feature_not_in_plan — 审计日志属于 Enterprise 计划；该问题指明功能、账户所在的计划和 required_plan。	问题 (application/problem+json)
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (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/organizations/{org_id}/notifications¶

列出组织通知

按从旧到新的顺序列出组织的通知，涵盖所有渠道（最多 50 个）。

通知属于组织，覆盖其所有项目，包括之后新增的项目（project_ids 缺省），或选定的项目（project_ids）；它对这些项目的屏幕、数据源、活动和卡片的作用与项目通知完全相同。只要任一被覆盖项目的投递处于失败状态，status 就是 failing，failing_since、last_success_at 和 last_failure_at 汇总被覆盖项目的值（最早的失败开始时间、最近的成功和失败）。

此处绝不会返回 Webhook 的签名密钥。需要组织的管理员；其他任何人返回 not_found。

身份验证: dashboardSession
请求主体: 无
操作 ID: listOrganizationNotifications

参数

名称	发送	必需？	描述
org_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/notifications'

响应

状态	含义	正文和头部
200	组织的通知。	OrganizationNotificationList (application/json)
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (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/organizations/{org_id}/notifications¶

创建组织通知

创建组织的通知，包含 POST /api/notifications 的各成员以及它覆盖的项目：project_ids 缺省或为 null 时覆盖组织的所有项目（现有的和之后新增的），列表则恰好覆盖这些项目，每个都必须是本组织的活跃项目（否则返回 invalid_request）。

电子邮件通知的收件人是 owner（每个被覆盖项目的所有者），或组织人员（其管理员和主组织成员）或被覆盖项目成员的 user_ids；每个项目仍只向属于该项目成员的人员发送邮件。

每个组织最多有 50 个通知，系统生成的默认通知不计入（notification_limit_reached）。渠道、规则和条件受与项目路由相同的计划功能限制，按组织的计划判定。每个被覆盖的项目都会收到 notification.created，该变更会记录在组织的审计日志中。

Webhook 的签名密钥仅在本次响应和 rotate-secret 中返回；一个密钥为所有被覆盖项目的投递签名。以相同的 Idempotency-Key 原样重试，24 小时内会返回同一响应（包括密钥）。

身份验证: dashboardSession
请求主体: OrganizationNotificationWrite
操作 ID: createOrganizationNotification

参数

名称	发送	必需？	描述
org_id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
channel（必填，string）	允许："email", "webhook", "slack", "teams", "pagerduty", "telegram"
描述（可选，字符串）	供人识别的名称。maxLength: 200
conditions（可选，NotificationConditions）
screen_tags（可选，ScreenTags）	设备组选择器标签，0 到 16 个唯一且精确的标签，每个标签符合媒体标签语法。在 ScreenPatch 中，数组替换整个集合，空数组则清空；重复或格式错误的标签为 invalid_request。更改标签会提升屏幕版本（If-Match 保护），并附加 screen.updated，详情见 details.tags；不会更改清单版本。标签永远不会出现在运行时清单中，也不会用于授权。
audience (可选, CampaignAudience)	活动定向的屏幕：all（每条规则都匹配）、any（至少一条匹配）、tag（屏幕带有该标签）、screen_id（该屏幕）或 folder（该屏幕文件夹及其内部每个文件夹中的屏幕，GET /api/screen-folders；该文件夹必须存在）中的恰好一个。规则最多嵌套 3 层，一个 audience 最多有 500 条规则。{"all": []} 表示项目的每个屏幕；在其他位置，all 和 any 至少列出一条规则。
min_severity（可选，NotificationSeverity）	提醒的严重级别，由低到高。已开启的提醒具有其条件的严重级别：screen_offline 为 error，其他每个条件为 warning，除非通知的 severity 另有设置。已解决的提醒和测试为 info。允许："info", "warning", "error"
severity（可选，NotificationSeverityOverrides）	此通知的条件到严重级别的映射，例如 {"not_playing": "error"}。它计入 min_severity，也是 Teams 和 PagerDuty 为该条件显示的严重级别。未列出的条件保持其默认值。在补丁中，空对象与 null 一样，清除所有覆盖。
active_hours（可选，NotificationActiveHours）	已开启提醒发出的时间：窗口（screenrig.schedule/v1），按 timezone 解读。窗口关闭期间到期的提醒会等到下一次开启（outside hold，默认），若届时条件仍然成立才发出，因此条件先行解除则不发送任何内容，或者被跳过（outside drop；last_error outside_hours）。已发送的已开启提醒对应的已解决提醒始终发出，无论是否在时段内，测试则忽略时段。crashing 与其他条件一样被保留或丢弃。时段在提醒首次发出时判定；失败的提醒按常规计划重试，不论时段。添加、更改或移除时段，会立即对为旧时段而保留的提醒重新判定。
reach_drop（可选，NotificationReachDrop）	活动触达减少多少时发送 reach_dropped 提醒的最小值：screens 是最少失去的屏幕数（默认 1），percent 设置后是活动发布时所触达屏幕的最小占比；减少必须同时满足两者。较小的减少不会排入提醒，已排队的提醒如果到期时减少已低于该阈值，则会被跳过 (condition_cleared)。仅适用于 reach_dropped 条件；未带该条件的通知返回 invalid_request。
hold_minutes（可选，integer）	条件需持续多久才会发出通知。crashing 不设等待期。default: 10 minimum: 0 maximum: 1440
recipients（可选，NotificationRecipients）	仅限电子邮件。owner（提醒发送时该项目的所有者）或项目成员的 user_id；不是成员的 user_id 会返回 invalid_request。每位收件人都会通过其已验证的地址收到电子邮件。已离开项目或没有已验证地址的收件人会被跳过。
url（可选，字符串）	仅限 Webhook：公共互联网主机上的 https URL，端口 443（默认）或 8443。不得包含 userinfo 或片段。maxLength: 2048 format: "uri"
event_types（可选，NotificationEventTypes）	仅限 Webhook。项目事件发生时也会通过 POST 发送，格式与 Webhook 发送的完全一致：精确类型（如 screen.online），或以 .* 结尾的前缀（如 screen.*）。notification.test 绝不会被分发。
destination（可选，NotificationDestination）	仅适用于 Slack、Teams、PagerDuty 和 Telegram，对它们必填。凭据须为服务签发的格式：slack 为传入 Webhook URL（hooks.slack.com）；teams 为 Workflows Webhook URL（logic.azure.com 或 powerplatform.com；Office 365 连接器 URL 已停用）；pagerduty 为 32 位 Events API v2 路由密钥；telegram 为机器人令牌。其他格式会返回 notification_destination_rejected。它会被加密封存，绝不会返回，读取时只以 destination_hint 的形式出现。 minLength: 1 maxLength: 2048
telegram_chat_id（可选，NotificationTelegramChat）	仅适用于 Telegram，对其必填。要发布到的聊天：其数字 id（群组或频道为负数）或 @channelname。不是凭据。 pattern: "^(-?[0-9]{1,20}\|@[A-Za-z][A-Za-z0-9_]{4,31})$"
启用（可选，布尔值）	默认：true
project_ids（可选，内联）	通知覆盖的项目；null 或缺省时覆盖组织的所有项目。

请求模板和响应

shell · 请求模板

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/organizations/ORG_ID/notifications'

响应

状态	含义	正文和头部
201	已创建。Webhook 的密钥仅在此处和 rotate-secret 中显示。	Notification (application/json)；响应头：Cache-Control
400	invalid_request、webhook_url_rejected 或 notification_destination_rejected。	问题 (application/problem+json)
402	feature_not_in_plan — 与 POST /api/notifications 相同，按组织的计划判定。	问题 (application/problem+json)
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
409	notification_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)

GET/api/organizations/{org_id}/notifications/{id}¶

获取组织通知

组织的一个通知，与 GET /api/organizations/{org_id}/notifications 显示的相同。

身份验证: dashboardSession
请求主体: 无
操作 ID: getOrganizationNotification

参数

名称	发送	必需？	描述
org_id	路径	必填
id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/notifications/RESOURCE_ID'

响应

状态	含义	正文和头部
200	单个通知。	Notification (application/json)；响应头：ETag
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

PATCH/api/organizations/{org_id}/notifications/{id}¶

更新组织通知

更改 PATCH /api/notifications/{id} 可更改的任何成员，作用于通知本身和每个被覆盖的项目，以及 project_ids：缺省时保持项目不变，null 覆盖所有项目，列表则恰好覆盖这些项目。新获得该通知的项目从其当前事件开始（不会发送更早的内容）；失去该通知的项目会删除该通知。

每个被覆盖的项目都会收到 notification.updated，该变更会记录在组织的审计日志中。

使通知覆盖其当前未覆盖的项目的变更，与按变更后的样子创建该通知一样，受计划功能限制（其渠道、规则和屏幕画面条件，依组织的计划而定）；覆盖更少的项目从不受限制，而把列表切换为所有项目则总是覆盖更多。If-Match 保护修订号。

身份验证: dashboardSession
请求主体: OrganizationNotificationPatch
操作 ID: updateOrganizationNotification

参数

名称	发送	必需？	描述
org_id	路径	必填
id	路径	必填
If-Match	header	可选	可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
描述（可选，字符串）	空字符串会清除描述。maxLength：200
conditions（可选，NotificationConditions）
screen_tags（可选，ScreenTags）	设备组选择器标签，0 到 16 个唯一且精确的标签，每个标签符合媒体标签语法。在 ScreenPatch 中，数组替换整个集合，空数组则清空；重复或格式错误的标签为 invalid_request。更改标签会提升屏幕版本（If-Match 保护），并附加 screen.updated，详情见 details.tags；不会更改清单版本。标签永远不会出现在运行时清单中，也不会用于授权。
audience（可选，内联）	同 NotificationPatch。
min_severity（可选，内联）	同 NotificationPatch。
severity（可选，内联）	替换所有覆盖；null 或空对象将其清除。
active_hours（可选，内联）	替换时段；null 将其清除。
reach_drop（可选，内联）	替换阈值；null 表示清除。
hold_minutes（可选，integer）	minimum: 0 maximum: 1440
recipients（可选，NotificationRecipients）	仅限电子邮件。owner（提醒发送时该项目的所有者）或项目成员的 user_id；不是成员的 user_id 会返回 invalid_request。每位收件人都会通过其已验证的地址收到电子邮件。已离开项目或没有已验证地址的收件人会被跳过。
url（可选，字符串）	maxLength：2048 格式：“uri”
event_types（可选，NotificationEventTypes）	仅限 Webhook。项目事件发生时也会通过 POST 发送，格式与 Webhook 发送的完全一致：精确类型（如 screen.online），或以 .* 结尾的前缀（如 screen.*）。notification.test 绝不会被分发。
destination（可选，NotificationDestination）	仅适用于 Slack、Teams、PagerDuty 和 Telegram，对它们必填。凭据须为服务签发的格式：slack 为传入 Webhook URL（hooks.slack.com）；teams 为 Workflows Webhook URL（logic.azure.com 或 powerplatform.com；Office 365 连接器 URL 已停用）；pagerduty 为 32 位 Events API v2 路由密钥；telegram 为机器人令牌。其他格式会返回 notification_destination_rejected。它会被加密封存，绝不会返回，读取时只以 destination_hint 的形式出现。 minLength: 1 maxLength: 2048
telegram_chat_id（可选，NotificationTelegramChat）	仅适用于 Telegram，对其必填。要发布到的聊天：其数字 id（群组或频道为负数）或 @channelname。不是凭据。 pattern: "^(-?[0-9]{1,20}\|@[A-Za-z][A-Za-z0-9_]{4,31})$"
启用（可选，布尔值）
snoozed_until（可选，inline）	在此时刻之前不发送任何内容，最多可设为 30 天之后；null 表示结束暂停。
project_ids（可选，内联）	缺省时保持通知覆盖的项目不变，null 覆盖组织的所有项目，列表则恰好覆盖这些项目。

请求模板和响应

shell · 请求模板

curl --request PATCH --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/organizations/ORG_ID/notifications/RESOURCE_ID'

响应

状态	含义	正文和头部
200	更新后的通知。	Notification (application/json)；响应头：ETag
400	invalid_request、webhook_url_rejected 或 notification_destination_rejected。	问题 (application/problem+json)
402	feature_not_in_plan — 与 PATCH /api/notifications/{id} 相同，按组织的计划判定。	问题 (application/problem+json)
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
412	revision_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/organizations/{org_id}/notifications/{id}¶

删除组织通知

从它覆盖的每个项目中删除该通知，并在每个项目中追加 notification.deleted，同时记录在组织的审计日志中。待处理的提醒会以 webhook_deleted 标记为失败。

身份验证: dashboardSession
请求主体: 无
操作 ID: deleteOrganizationNotification

参数

名称	发送	必需？	描述
org_id	路径	必填
id	路径	必填
If-Match	header	可选	可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求模板和响应

shell · 请求模板

curl --request DELETE --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/notifications/RESOURCE_ID'

响应

状态	含义	正文和头部
204	已删除。	无正文；头部：Cache-Control
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
412	revision_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)

POST/api/organizations/{org_id}/notifications/{id}/rotate-secret¶

轮换组织通知密钥

仅限 Webhook 通知（其他任何渠道会返回 invalid_request）。一次性替换所有被覆盖项目中的签名密钥，使同一个接收方始终验证同一个密钥，并返回通知，新密钥位于 secret 中。

与 POST /api/notifications/{id}/rotate-secret 一样，每个项目最多有一次已在传输中的尝试仍可能以旧密钥签名送达。以相同的 Idempotency-Key 原样重试，24 小时内会返回同一个新密钥。

身份验证: dashboardSession
请求主体: 无
操作 ID: rotateOrganizationNotificationSecret

参数

名称	发送	必需？	描述
org_id	路径	必填
id	路径	必填
If-Match	header	可选	可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求模板和响应

shell · 请求模板

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/notifications/RESOURCE_ID/rotate-secret'

响应

状态	含义	正文和头部
200	通知及其新密钥。	Notification (application/json)；响应头：Cache-Control
400	invalid_request：该通知不是 Webhook。	问题 (application/problem+json)
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
412	revision_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)

POST/api/organizations/{org_id}/notifications/{id}/test¶

测试组织通知

通过通知覆盖的第一个项目（按项目 id 排序）发送一条 notification.test，与 POST /api/notifications/{id}/test 通过其项目发送的方式相同：一次投递，其结果显示在投递列表中，仅尝试一次。

每个被覆盖的项目都有相同的接收方、目标和密钥，因此一次测试即可验证该渠道；测试的电子邮件会发送给该项目的收件人。不覆盖任何项目的通知返回 invalid_request。

身份验证: dashboardSession
请求主体: 无
操作 ID: testOrganizationNotification

参数

名称	发送	必需？	描述
org_id	路径	必填
id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求模板和响应

shell · 请求模板

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/notifications/RESOURCE_ID/test'

响应

状态	含义	正文和头部
202	排队的测试投放。	NotificationDelivery (application/json)；响应头：RateLimit-Policy、RateLimit
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (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)

GET/api/organizations/{org_id}/notifications/{id}/deliveries¶

列出组织通知投递记录

通知覆盖的所有项目的投递日志合并为一个列表，按每行的排队时间从新到旧排列。每一行都标明其项目（project_id），其 id 用于打开 GET .../deliveries/{delivery_id}/attempts。像之前一样传回 next_cursor 即可获取下一页。

身份验证: dashboardSession
请求主体: 无
操作 ID: listOrganizationNotificationDeliveries

参数

名称	发送	必需？	描述
org_id	路径	必填
id	路径	必填
before	查询	可选	上一交付页的 next_cursor。
限制	查询	可选

请求模板和响应

shell · 请求模板

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/notifications/RESOURCE_ID/deliveries'

响应

状态	含义	正文和头部
200	一页投递记录。	NotificationDeliveryList (application/json)
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (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/organizations/{org_id}/notifications/{id}/deliveries/{delivery_id}/attempts¶

列出组织通知投递尝试

某次投递的尝试记录，按从新到旧排列，最近 20 条。不属于此通知的投递返回 not_found。

身份验证: dashboardSession
请求主体: 无
操作 ID: listOrganizationNotificationDeliveryAttempts

参数

名称	发送	必需？	描述
org_id	路径	必填
id	路径	必填
delivery_id	路径	必填	某个 webhook 投递的 ID。

请求模板和响应

shell · 请求模板

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/notifications/RESOURCE_ID/deliveries/DELIVERY_ID/attempts'

响应

状态	含义	正文和头部
200	交付的保留尝试。	NotificationDeliveryAttemptList (application/json)
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (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/organizations/{org_id}/notifications/{id}/unsubscribed/{user_id}¶

重新订阅某人的组织通知

让已通过邮件中的取消订阅链接停止接收某个电子邮件通知的人重新收到邮件，对通知覆盖的每个项目都生效（该链接会在所有项目中停止对其发送）。幂等：未被停止的人不会带来任何变化，响应就是该通知当前的样子。

变更会提高修订号，并向每个被覆盖的项目追加 notification.updated，其详情为 change resubscribed、user_id 和 via api。

身份验证: dashboardSession
请求主体: 无
操作 ID: resubscribeOrganizationNotificationUser

参数

名称	发送	必需？	描述
org_id	路径	必填
id	路径	必填
user_id	路径	必填	通知的 unsubscribed 列表中某人的 user_id。

请求模板和响应

shell · 请求模板

curl --request DELETE --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/notifications/RESOURCE_ID/unsubscribed/USER_ID'

响应

状态	含义	正文和头部
200	该通知，unsubscribed 中不再含有此人。	Notification (application/json)；响应头：ETag
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (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/projects/{project_id}/reports¶

列出项目中的报告类型

列出 GET /api/reports/{kind} 可生成的报告类型及各自的筛选条件，以及报告的输出格式。需要报告权限。

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/reports'

响应

状态	含义	正文和头部
200	报告类型。	ReportCatalog (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/projects/{project_id}/report-subscriptions¶

列出项目中的报告订阅

按时间从旧到新列出项目已排程的报告（最多 50 个），每个都含下次运行和上次运行的结果。需要项目权限。

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/report-subscriptions'

响应

状态	含义	正文和头部
200	项目的报告订阅。	ReportSubscriptionList (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/projects/{project_id}/report-subscriptions¶

在项目中创建报告订阅

安排以 PDF、XLSX 或 CSV 附件通过电子邮件发送报告，每天、每周或每月在某时区的指定整点发送。

每次运行覆盖其之前的周期（按 UTC 日）：前一天、前七天或上个月。recipients 是项目成员，用 user_id 或成员的电子邮件地址指定；其他人会被拒绝，因此订阅不会成为向外部人员发邮件的途径，离开项目的成员将不再收到。

失败的运行会重试，并以 last_status failed 和 last_error 显示。每个组织跨其所有项目最多 50 个（report_subscription_limit_reached）。

身份验证: projectBearer
请求主体: ReportSubscriptionWrite
操作 ID: createReportSubscriptionInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
名称（必填，字符串）	minLength: 1 maxLength: 100
kind（必填，字符串）	允许的值："fleet_health", "uptime", "publishing", "alerts", "alert_log", "proof_of_play"
filters（可选，对象）	报告的日期以外的筛选条件（GET /api/reports 会列出）。
schedule（必填，ReportSchedule）
format（必填，字符串）	允许的值："pdf", "xlsx", "csv"
recipients（必填，数组）	项目成员的 user_id 或电子邮件地址。
启用（可选，布尔值）	默认：true

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/report-subscriptions'

响应

状态	含义	正文和头部
201	已创建。	ReportSubscription（application/json）；标头：ETag
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
402	feature_not_in_plan — 报告属于 Plus。该问题指明功能、项目的计划和 required_plan。	问题 (application/problem+json)
409	report_subscription_limit_reached.	问题 (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/projects/{project_id}/cards¶

列出项目中的卡片

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

参数

名称	发送	必需？
project_id	路径	必填
项目	查询	可选
after	查询	可选

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/cards'

响应

状态	含义	正文和头部
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/projects/{project_id}/cards¶

创建项目卡片

身份验证: projectBearer
请求主体: CardCreate
操作 ID: createProjectCard

参数

名称	发送	必需？	描述
project_id	路径	必填

请求主体字段

字段	描述
类型（必填，字符串）
major（可选，整数）	最小值：1
参数（必填，对象）
data（可选，对象）

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/cards'

响应

状态	含义	正文和头部
201	卡片资源	CardInstance（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)

POST/api/organizations/{org_id}/billing/portal-sessions¶

创建组织门户

需要有效组织的指定管理员、完全同源的 Cookie 身份验证以及 JWT CSRF。操作者和返回 URL 由服务器管理。响应为 private 且 no-store。也向委托给经销商的组织开放，用于其银行卡和过往发票。

身份验证: dashboardSession
请求主体: EmptyPaymentRequest
操作 ID: createOrganizationPortal

参数

名称	发送	必需？	描述
org_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/organizations/ORG_ID/billing/portal-sessions'

响应

状态	含义	正文和头部
201	账单管理结果。	BillingPortalSession (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/organizations/{org_id}/billing/auto-top-up¶

设置组织自动充值

需要有效组织的指定管理员、完全同源的 Cookie 身份验证以及 JWT CSRF。操作者由服务器管理。关闭会保留已保存的金额和本月支出；关闭时金额字段会被忽略。响应为 private 且 no-store。只有在任何支付失败的待付发票被安全作废之后，更改设置才会清除可恢复的暂停。

为委托给经销商的组织启用它会返回 409 billed_by_reseller；关闭仍然开放。

身份验证: dashboardSession
请求主体: AutoTopUpSettings
操作 ID: setOrganizationAutoTopUp

参数

名称	发送	必需？	描述
org_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/organizations/ORG_ID/billing/auto-top-up'

响应

状态	含义	正文和头部
200	账单管理结果。	AutoTopUpView (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/organizations/{org_id}/billing/payments¶

获取组织付款

有效组织的付款视图。需要其指定管理员的 Cookie；仅有员工查看权限并不授予购买权限。未配置付款时返回 available false。浏览器返回不会授予额度。

身份验证: dashboardSession
请求主体: 无
操作 ID: getOrganizationPayments

参数

名称	发送	必需？	描述
org_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/billing/payments'

响应

状态	含义	正文和头部
200	付款可用性与最近购买记录。	OrganizationPayments (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/organizations/{org_id}/billing/credit-checkouts¶

创建组织结账

为有效组织的指定管理员发起预付购买。需要同源 Cookie 身份验证；JWT 会话还需要匹配的 CSRF 请求头。组织、客户、操作人和返回 URL 由服务器管理。只有在计费服务确认付款后才会增加额度。响应不明确时，请使用相同的 Idempotency-Key 和金额重试。

委托给经销商的组织返回 409 billed_by_reseller。

身份验证: dashboardSession
请求主体: object
操作 ID: createOrganizationCheckout

参数

名称	发送	必需？	描述
org_id	路径	必填
Idempotency-Key	header	必填

请求主体字段

字段	描述
amount_cents（必需，整数）	最小值：10000 最大值：1000000 格式："int64"

请求模板和响应

shell · 请求模板

curl --request POST --cookie cookies.txt --cookie-jar cookies.txt --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/organizations/ORG_ID/billing/credit-checkouts'

响应

状态	含义	正文和头部
201	购买已创建或重放。完成后不包含结账 URL。响应为私密内容，且使用 no-store。	CreditPurchase (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/organizations/{org_id}/billing/balance¶

获取组织账单余额

组织钱包。需要指定的组织管理员、该组织所委托经销商的管理员或员工会话。不授予项目成员资格。

身份验证: dashboardSession
请求主体: 无
操作 ID: getOrganizationBillingBalance

参数

名称	发送	必需？	描述
org_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/billing/balance'

响应

状态	含义	正文和头部
200	组织账单余额。	BillingBalance（application/json）；头部：Cache-Control
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

GET/api/organizations/{org_id}/billing/statement¶

获取组织账单对账单

计费时归属于该组织的账目条目，含项目和付款人身份。移动不转移历史访问权限。早于所记录组织上下文的条目仍保留在其项目对账单中。读取者与余额相同（getOrganizationBillingBalance）。

身份验证: dashboardSession
请求主体: 无
操作 ID: getOrganizationBillingStatement

参数

名称	发送	必需？
org_id	路径	必填
游标	查询	可选
限制	查询	可选

请求模板和响应

shell · 请求模板

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/billing/statement'

响应

状态	含义	正文和头部
200	组织账单对账单。	BillingStatement（application/json）；头部：Cache-Control
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

GET/api/organizations/{org_id}/billing/usage¶

获取组织账单使用情况

组织在一个 UTC 月内的用量池及每个项目的份额。涵盖本组织支付的用量；其他付款方的费用见组织对账单。读取者与余额相同（getOrganizationBillingBalance）。

身份验证: dashboardSession
请求主体: 无
操作 ID: getOrganizationBillingUsage

参数

名称	发送	必需？	描述
org_id	路径	必填
游标	查询	可选
限制	查询	可选
周期	查询	可选	以YYYY-MM格式表示的UTC月份；默认为当前月份。

请求模板和响应

shell · 请求模板

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/organizations/ORG_ID/billing/usage'

响应

状态	含义	正文和头部
200	组织账单使用情况。	OrganizationBillingUsage（application/json）；头部：Cache-Control
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

GET/api/organizations¶

Agent 组织列表

可见的组织，包括其管理员的空组织。名称不唯一。

身份验证: agentIdentityBearer 或 dashboardSession
请求主体: 无
操作 ID: agentOrganizationsList

请求模板和响应

shell · 请求模板

curl --request GET --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/organizations'

响应

状态	含义	正文和头部
200	组织结果。	OrganizationList（application/json）；头部：Cache-Control
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

PATCH/api/organizations/{org_id}¶

Agent 组织重命名

指定的管理员和其验证的负责人为管理员的代理可以重命名组织。不授予项目权限或成员资格。

身份验证: agentIdentityBearer 或 dashboardSession
请求主体: 组织重命名
操作 ID: agentOrganizationsRename

参数

名称	发送	必需？	描述
org_id	路径	必填

请求主体字段

字段	描述
名称（必填，ProjectName）	修剪后的可打印项目名称。拒绝控制字符、类似URL的文本、@、www.及://。minLength：1 maxLength：60

请求模板和响应

shell · 请求模板

curl --request PATCH --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/organizations/ORG_ID'

响应

状态	含义	正文和头部
200	组织结果。	OrganizationView（application/json）；头部：Cache-Control
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

PUT/api/project/review-policy¶

设置项目审核策略

开启或关闭“需要审核代理更改”。开启时，项目中的每个代理和服务客户端在每次请求时都被限制为提议访问权限，无论其凭证如何。仅项目所有者或项目组织的管理员可更改（其他人禁止）；员工影子会话无法更改。

If-Match 包含 review_policy_revision（允许为 0）且必需；过期值为 revision_conflict。关闭需证明，使用智能体连接审批的最新通行密钥或密码证明；开启无需。开放审核无论如何均可决定。追加 project.review_policy_changed。

身份验证: dashboardSession
请求主体: ReviewPolicyUpdate
操作 ID: setProjectReviewPolicy

参数

名称	发送	必需？	描述
If-Match	header	必填

请求主体字段

字段	描述
agent_changes_require_review（必填，布尔值）
proof（可选，DashboardProof）

请求模板和响应

shell · 请求模板

curl --request PUT --cookie cookies.txt --cookie-jar cookies.txt --header 'If-Match: "REVISION"' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/project/review-policy'

响应

状态	含义	正文和头部
200	当前生效的策略。	ReviewPolicy（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/projects/{project_id}/project/deletion-preview¶

项目内预览项目删除代理

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

参数

名称	发送	必需？	描述
project_id	路径	必填
project_id	查询	可选	预期项目 ID；更改选择将被拒绝。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/project/deletion-preview'

响应

状态	含义	正文和头部
200	项目生命周期结果	ProjectDeletionPreview（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/projects/{project_id}/project/owner¶

在项目中转移项目所有者智能体

身份验证: projectBearer
请求主体: ProjectOwnerTransfer
操作 ID: transferProjectOwnerAgentInProject

参数

名称	发送	必需？	描述
project_id	路径	必填

请求主体字段

字段	描述
project_id（可选，字符串）	预期项目 ID。如果当前凭据或 cookie 会话针对其他项目，服务器拒绝该操作；浏览器客户端发送页面的项目 ID。minLength: 1 maxLength: 200
user_id（必填，字符串）	minLength：1 maxLength：200

请求模板和响应

shell · 请求模板

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/project/owner'

响应

状态	含义	正文和头部
200	项目生命周期结果	ProjectContext（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/projects/{project_id}/project/move¶

在项目中移动项目代理

所有者授权的移动将屏幕占用和新使用原子地转移到目标付款方；历史费用保持其付款方。

身份验证: projectBearer
请求主体: ProjectMove
操作 ID: moveProjectAgentInProject

参数

名称	发送	必需？	描述
project_id	路径	必填

请求主体字段

字段	描述
project_id（可选，字符串）	预期项目 ID。如果当前凭据或 cookie 会话针对其他项目，服务器拒绝该操作；浏览器客户端发送页面的项目 ID。minLength: 1 maxLength: 200
organization_id（必填，字符串）	minLength：1 maxLength：200

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/project/move'

响应

状态	含义	正文和头部
200	项目生命周期结果	ProjectContext（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/projects/{project_id}/project/moves¶

允许项目内移动智能体

列出所有者管理的目的地或其验证域与其验证电子邮件匹配的目的地。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
project_id	查询	可选	预期项目 ID；更改选择将被拒绝。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/project/moves'

响应

状态	含义	正文和头部
200	项目生命周期结果	ProjectMoveDestinations（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/projects/{project_id}/invitations¶

列出项目中的邀请

列出当前项目的邀请生命周期记录，不包括登录重置。接收地址对拥有项目可见，项目提供了这些地址。令牌和凭证 URL 永不列出。

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

参数

名称	发送	必需？
project_id	路径	必填
kind	查询	可选
状态	查询	可选
游标	查询	可选

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/invitations'

响应

状态	含义	正文和头部
200	列出当前项目的邀请生命周期记录，不包括登录重置。	InvitationList（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/projects/{project_id}/invitations¶

在项目中创建邀请

限定屏幕范围的成员不能邀请人员（outside_screen_scope）。

身份验证: projectBearer
请求主体: InvitationCreate
操作 ID: createInvitationsInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	必填

请求主体字段

字段	描述
kind（必填，字符串）	允许值：“project_member”、“ad_buyer”
delivery（可选，字符串）	允许：“email”、“link”，默认：“email”
电子邮件（可选，数组）
advertising（可选，InvitationAdvertising）	卖方拥有的范围：至少一个屏幕或广告位。仅屏幕、仅广告位或两者皆可。
upload_scope（可选，UploadScope）	上传者可以使用的内容（docs/uploaders.md）：其可更改页面的播放列表，以及可上传到的媒体文件夹。文件夹仅限所列出的那些，不包括其子文件夹。写入时不指向项目有效对象的 id 会在其所在位置返回 invalid_request；之后被删除的对象会留下一个失效 id，它不授予任何权限。范围在每次请求时读取，因此更改会在下一次请求时生效。
screen_scope（可选，ScreenScope）	带范围的成员或智能体可以操作的内容（docs/screen-scope.md）：所列屏幕文件夹及其内部每个文件夹中的屏幕，以及所列屏幕。所有 ID 中至少一个。写入时不指向项目现存文件夹或屏幕的 ID，在其位置为 invalid_request；之后的删除会留下不授予任何权限的无效 ID。范围在每次请求时读取，因此更改会在下一次请求时生效。标签永远不是范围。

请求模板和响应

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/projects/PROJECT_ID/invitations'

响应

状态	含义	正文和头部
201	创建成员或广告买家邀请。	InvitationCreated（application/json）；头部：RateLimit-Policy，RateLimit
402	feature_not_in_plan — 屏幕范围需要 Enterprise，上传范围（上传者）需要 Plus；该问题指明功能、账户所在的计划和 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)
429	稳定的 rate_limited 问题。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。	问题 (application/problem+json)；头部：Retry-After，RateLimit-Policy，RateLimit

GET/api/projects/{project_id}/project¶

在项目中获取项目

SSE、运行时、内容和未认证响应省略它们。

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/project'

响应

状态	含义	正文和头部
200	项目	项目 (application/json)；头部：ScreenRig-Credits-Remaining，ScreenRig-Credits-Reset，ScreenRig-Credits-Included，ScreenRig-Credits-Low
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

PATCH/api/projects/{project_id}/project¶

更新项目中的项目

重命名当前项目。名称包含1至60个可打印字符，不得包含类似URL的文本。

身份验证: projectBearer
请求主体: ProjectPatch
操作 ID: updateProjectInProject

参数

名称	发送	必需？	描述
project_id	路径	必填

请求主体字段

字段	描述
project_id（可选，字符串）	预期项目 ID。如果当前凭据或 cookie 会话针对其他项目，服务器拒绝该操作；浏览器客户端发送页面的项目 ID。minLength: 1 maxLength: 200
名称（必填，ProjectName）	修剪后的可打印项目名称。拒绝控制字符、类似URL的文本、@、www.及://。minLength：1 maxLength：60

请求模板和响应

shell · 请求模板

curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/project'

响应

状态	含义	正文和头部
200	重命名当前项目。	项目 (application/json)
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

删除/api/projects/{project_id}/project¶

删除项目中的项目智能体

仅项目所有者或其组织管理员可删除；其他调用者拒绝，返回 forbidden。人员必须是项目成员。

身份验证: projectBearer
请求主体: ProjectDeleteConfirmation
操作 ID: deleteProjectAgentInProject

参数

名称	发送	必需？	描述
project_id	路径	必填

请求主体字段

字段	描述
project_id（可选，字符串）	预期项目 ID。如果当前凭据或 cookie 会话针对其他项目，服务器拒绝该操作；浏览器客户端发送页面的项目 ID。minLength: 1 maxLength: 200
empty_only（可选，布尔值）	删除事务中要求 Screens 项目为空，包括内容、其他智能体或成员、工作和通信。CLI 还要求其保存的注册来源后才使用此清理保护。省略则保留显式成员删除。
名称（必填，ProjectName）	修剪后的可打印项目名称。拒绝控制字符、类似URL的文本、@、www.及://。minLength：1 maxLength：60
revision（必填，整数）	最小值：1

请求模板和响应

shell · 请求模板

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/project'

响应

状态	含义	正文和头部
200	项目生命周期结果	DeletedProject（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/projects/{project_id}/applications¶

列出项目中的应用

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

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

参数

名称	发送	必需？	描述
project_id	路径	必填
after	查询	可选	同一列表上一页的 next_cursor，使用相同过滤条件。省略时从最新行开始。非此类游标值为 invalid_request。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/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/projects/{project_id}/applications¶

在项目中上传应用

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

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

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

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	必填
ScreenRig-Archive-SHA256	header	必填
ScreenRig-Expanded-Bytes	header	必填
ScreenRig-File-Count	header	必填
ScreenRig-SDK-Version	header	可选
ScreenRig-Application-Name	header	可选	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://api.screenrig.ai/api/projects/PROJECT_ID/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/projects/{project_id}/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: createApplicationUploadInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	必填

请求主体字段

字段	描述
名称（可选，字符串）	新应用程序的名称，已修剪；最多 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/projects/PROJECT_ID/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)

GET/api/projects/{project_id}/playlists¶

列出项目中的播放列表 V2

版本化播放列表列表，可能暴露广告位页面。v1 列表拒绝持有 version_required 的广告文档页面，而非过滤。

页面如 listPlaylists，最新优先，每页最多 200 条，且当页面存储的播放列表达到 8 MiB 时减少。next_cursor 是最后返回行的位置，当还有更多行时；将其作为 after 传回，使用相同过滤器，获取下一页。最后一页时 next_cursor 为 null。library=true 改为列出组织媒体库的播放列表（只读；可对其排期，或基于其模板创建）。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
library	查询	可选	true 表示列出组织的媒体库项目而不是本项目：其条目在此为只读，并带有 library true。没有媒体库的组织，或媒体库项目本身，使用 true 时不列出任何内容。
after	查询	可选	同一列表上一页的 next_cursor，使用相同过滤条件。省略时从最新行开始。非此类游标值为 invalid_request。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/playlists'

响应

状态	含义	正文和头部
200	带广告位页面并集的播放列表。	播放列表 V2 列表（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/projects/{project_id}/playlists¶

在项目中创建播放列表 V2

广告位页面联合的创作入口。最多16个广告位页面，至少一个无可见性的普通页面，以及在不同页面上重用一个插槽定义仍由服务器检查。参考解析和DNS仍由服务器检查。

包含 Player 网页应用无法嵌入的 iframe 页面的写入仍会保存；响应包含警告（PlaylistWarning），项目日志会为每个页面记录一个 playlist.iframe_framing_refused 事件。

写入中的 iframe src、fallback_src 或应用 params 读取了显示该播放列表的某个屏幕所缺少的屏幕令牌（{screen.field.NAME} 及原语模式中的其他令牌）时，也会返回 screen_fact_missing 警告，列出前 20 个此类屏幕；这些屏幕的清单会省略该原语。

iframe 的 src 或 fallback_src 若是 Google Slides、Docs 或 Sheets 链接（分享、发布到网络或嵌入），或 Microsoft 365 OneDrive 或 SharePoint 嵌入链接，会重新构建后存储以适配屏幕：Slides 循环并按链接的 delayms 翻页（受页面时长限制），Docs、Sheets、Word 和 Excel 每 5 分钟重新加载。

src 或 fallback_src 中粘贴的 <iframe> 嵌入代码会读取其 src。要求查看者登录的文件会被拒绝，返回 document_not_shared (400)，其 errors[0].field 为该 src 或 fallback_src，detail 指明需要更改的共享设置。

身份验证: projectBearer
请求主体: PlaylistCreateRequest
操作 ID: createPlaylistV2InProject

参数

名称

发送

必需？

描述

project_id

路径

必填

Screenrig-Review-Note

header

可选

审查类写入时的可选提议者备注，以百分号编码的 UTF-8 发送（JavaScript 的 encodeURIComponent 写入内容）。服务器进行百分号解码（无效转义为 400 invalid_request）；解码后的备注为纯文本，修剪后最多 280 字符，无控制字符（否则 400 invalid_request）。

写入成为审核时存储；实时应用时忽略。

Idempotency-Key

header

可选

省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/playlists'

响应

状态	含义	正文和头部
202	写入成为审核，等待人员批准（docs/reviews.md），适用于提议权限，或者在任何访问级别下涉及受保护屏幕文件夹中的屏幕时，由第二位审批人决定（docs/screen-scope.md）。人员在控制台的 review.url 处批准、驳回或要求更改。使用相同 Idempotency-Key 的重放会返回相同的响应体。	ReviewPending（application/json）
201	带广告位页面的播放列表。	播放列表 V2（application/json）
402	feature_not_in_plan — 声明字段、锁定图元或更改声明了字段的播放列表属于播放列表模板，而项目的计划不包含这些功能；required_plan 指明包含它们的计划。从模板创建播放列表始终允许。 2 块或更多显示器的格式（视频墙）属于 Plus；区域格式和没有格式的播放列表每个计划都包含。该问题指明功能、项目的计划和 required_plan。	问题 (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/projects/{project_id}/screens¶

列出项目中的屏幕

默认列表返回 pairing_pending 和 active 屏幕。传递 state=archived 仅列出归档屏幕。传递 tag 仅列出标签包含该精确标签的屏幕；存在过滤器时未标记屏幕将被省略。

每个字段各传一次 field，格式为 NAME:VALUE，即可仅列出各字段均匹配相应值的屏幕；以 LAT,LON,KM 的格式传入 near，即可仅列出位于该点 KM 千米范围内的屏幕；没有位置的屏幕会被省略，且所有筛选条件都可与 state 和 tag 组合使用。

将 folder 传为屏幕文件夹 ID，仅列出直接位于其中的屏幕（不包括其子文件夹的屏幕），或传 root 以列出不在任何文件夹内的屏幕。

屏幕按最新优先排列，每页最多 500 个。next_cursor 是仍有更多行时最后返回行的位置；将它作为 after 传回，并使用相同的筛选条件，即可获取下一页。最后一页的 next_cursor 为 null。限定屏幕范围的调用方（docs/screen-scope.md）只列出其范围内的屏幕。

未指明项目的请求，会省略调用方限定于屏幕的每个项目；请指明项目以列出它。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
状态	查询	可选	省略 pairing_pending 和 active。传递 archived 仅列出归档屏幕。
标签	查询	可选	确切的屏幕标签。存在此筛选器时，未标记的屏幕将被省略。
field	查询	可选	NAME:VALUE，在第一个冒号处拆分：仅返回字段 NAME 的值恰好为 VALUE 的屏幕。可重复传入该参数以匹配多个字段；每一项都必须匹配，且同一名称只能出现一次。格式错误或重复的项会返回 invalid_request 并指明 field。
near	查询	可选	LAT,LON,KM，经纬度以十进制度数表示，KM 以千米表示，例如 47.6062,-122.3321,25：仅返回位置距该点 KM 千米以内的屏幕。纬度为 -90 到 90，经度为 -180 到 180，KM 须大于 0 且不超过 20038。没有位置的屏幕会被省略。格式错误的值会返回 invalid_request 并指明 near。
文件夹	查询	可选	屏幕文件夹 ID 仅保留直接位于该文件夹内的屏幕，不包括其子文件夹的屏幕；root 仅保留不在任何文件夹内的屏幕。省略则列出所有屏幕。
after	查询	可选	同一列表上一页的 next_cursor，使用相同过滤条件。省略时从最新行开始。非此类游标值为 invalid_request。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/screens'

响应

状态	含义	正文和头部
200	屏幕	ScreenList（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/projects/{project_id}/screen-folders¶

列出项目中的屏幕文件夹

列出项目中的所有屏幕文件夹，最多 1000 个，按名称排序。

文件夹用于组织屏幕并将其作为目标：活动受众叶子节点 {"folder": ID} 匹配该文件夹及其内部每个文件夹中的屏幕，车队操作选择器 by:folder 作用于同一批屏幕，文件夹的 default_playlist_id 是其中没有自己播放列表的屏幕所显示的播放列表。parent_id 在项目根目录为 null；通过 parent_id 构建树。screens 统计直接位于每个文件夹内的实时屏幕数量。

屏幕的文件夹是 Screen.folder_id。限定屏幕范围的调用方（docs/screen-scope.md）可列出其范围内的文件夹及其上级文件夹，上级文件夹为只读，使其树有一个根；上级文件夹不带屏幕数量，同级文件夹隐藏。未指明项目的请求会省略调用方限定于屏幕的每个项目。

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/screen-folders'

响应

状态	含义	正文和头部
200	屏幕文件夹	ScreenFolderList（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/projects/{project_id}/screen-folders¶

在项目中创建屏幕文件夹

在项目根目录（parent_id 为 null 或缺失）或 parent_id 内创建一个屏幕文件夹。名称经修剪，包含 1 到 100 个无控制字符的 Unicode 字符，不为“.”或“..”，且在同级中唯一（resource_conflict）。

一个组织跨其所有项目最多包含 1000 个文件夹（quota_exceeded），嵌套深度最多 10 层（invalid_request）。default_playlist_id 设置时必须指向已批准的播放列表（playlist_not_approved）。发出 screen.folder_created。

限定屏幕范围的调用方（docs/screen-scope.md）只能在其范围内的文件夹中创建文件夹；项目根目录或任何其他父级属于 outside_screen_scope。在受保护文件夹内创建文件夹属于 protected_change 审核（202 pending_review），由第二位审批人决定。

身份验证: projectBearer
请求主体: ScreenFolderCreate
操作 ID: createScreenFolderInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
名称（必填，字符串）	修剪；1 到 100 个 Unicode 字符，无控制字符，不为 . 或 ..，在同级中唯一。minLength: 1 maxLength: 100
parent_id（可选，内联）	要在其中创建的文件夹；项目根目录为 null 或缺失。
default_playlist_id（可选，字符串）	为文件夹中没有自己播放列表的屏幕指定的已批准播放列表。minLength: 1

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/screen-folders'

响应

状态	含义	正文和头部
201	已创建文件夹。	ScreenFolder（application/json）；头部：ETag
202	写入成为审核，等待人员批准（docs/reviews.md），适用于提议权限，或者在任何访问级别下涉及受保护屏幕文件夹中的屏幕时，由第二位审批人决定（docs/screen-scope.md）。人员在控制台的 review.url 处批准、驳回或要求更改。使用相同 Idempotency-Key 的重放会返回相同的响应体。	ReviewPending（application/json）
403	outside_screen_scope，同 OutsideScreenScope；或 approver_required - 不能审批审核的、限定屏幕范围的成员不能更改屏幕播放什么或何时播放（docs/screen-scope.md）。	问题 (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/projects/{project_id}/screens/move¶

在项目中移动屏幕

将屏幕（screen_ids）和文件夹（folder_ids）移动到一个文件夹（folder_id），或当 folder_id 为 null 时移动到项目根目录，一次请求最多 1000 个 ID，全部成功或全部失败。每个 ID 必须存在（not_found）。文件夹不能移动到自身或其内部的文件夹，且移动后所有文件夹层级不得超过 10 层（invalid_request）。

已在目标中的项保持不变；每个被移动的屏幕和文件夹都会推进其修订版本。被移动的屏幕会在约 15 秒内重新解析其播放列表：levels 列出这些屏幕进入或离开其文件夹受众的活动，以及它们获得或失去的文件夹默认播放列表。发出 screen.moved。

限定屏幕范围的调用方（docs/screen-scope.md）将其范围内的屏幕和文件夹移入其范围内的某个文件夹；范围之外的任何 ID 或目的地以及项目根目录，都会使整个移动被拒绝（outside_screen_scope），屏幕在检查与写入之间离开范围时也是如此。

移入或移出受保护文件夹属于 protected_change 审核（202 pending_review），由第二位审批人决定。

身份验证: projectBearer
请求主体: ScreenMove
操作 ID: moveScreensInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
folder_id（必填，内联）	目标文件夹；项目根目录为 null。
screen_ids (可选, array)
folder_ids（可选，数组）

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/screens/move'

响应

状态	含义	正文和头部
200	移动了多少屏幕和文件夹，以及被移动的屏幕获得或失去的 levels。	ScreenMoveResult（application/json）
202	写入成为审核，等待人员批准（docs/reviews.md），适用于提议权限，或者在任何访问级别下涉及受保护屏幕文件夹中的屏幕时，由第二位审批人决定（docs/screen-scope.md）。人员在控制台的 review.url 处批准、驳回或要求更改。使用相同 Idempotency-Key 的重放会返回相同的响应体。	ReviewPending（application/json）
403	outside_screen_scope，同 OutsideScreenScope；或 approver_required - 不能审批审核的、限定屏幕范围的成员不能更改屏幕播放什么或何时播放（docs/screen-scope.md）。	问题 (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/projects/{project_id}/schedule/calendar¶

获取项目中的排程日历

回答某个主体的屏幕在 [from, to) 内播放什么及原因，供控制台的“排程”日历使用：screen_id、folder_id（该文件夹及其内部每个文件夹中的屏幕）、tag 或 campaign_id（其受众中的屏幕）中恰好填一个。

堆栈输入相同（层级、默认值、时区和显示器数量都相同）的屏幕共用一个分组和一条时间线，因此大型主体只需几十条时间线；一个分组最多列出其 500 个屏幕，一次回答最多 200 个分组（truncated）。

每个分组包含其堆栈（优先级从高到低：接管、覆盖这些屏幕的活动、屏幕自己的排程条目，然后是默认播放列表或最近文件夹的播放列表）、每个层级的 spans（在其目标的每个显示器上播放；partial 并附其播放所在的显示器；outranked；或 conditional，即等待交互或只有播放器才能观察到的数据条件）、每个显示器显示的内容（on_screen；整页的主区域），以及 conflicts（同一优先级的两个活动同时生效；生效却从不播放的层级）。from 和 to 是 RFC 3339 时间点，to 晚于 from，相差最多 93 天；它们会被截断到分钟。

规则按各分组的时区读取，与清扫任务和每个播放器读取的方式一致；每个层级都被视为可播放。限定屏幕范围的调用方（docs/screen-scope.md）必须发送其范围内的 screen_id 或 folder_id；标签、campaign_id 或没有主体都属于 outside_screen_scope。

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

参数

名称	发送	必需？
project_id	路径	必填
起始	查询	必填
至	查询	必填
screen_id	查询	可选
folder_id	查询	可选
标签	查询	可选
campaign_id	查询	可选

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/schedule/calendar?from=FROM&to=TO'

响应

状态	含义	正文和头部
200	该主体的日历。	ScheduleCalendar（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)

GET/api/projects/{project_id}/schedule/imports/template¶

项目内获取排程导入模板

返回一张含有排程导入所读列和三个示例行（屏幕代码、屏幕文件夹和标签）的工作表，格式为 CSV；使用 format=xlsx 时为 XLSX 工作簿。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
格式	查询	可选

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/schedule/imports/template'

响应

状态	含义	正文和头部
200	模板工作表。	字符串 (text/csv)，字符串 (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet)
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

POST/api/projects/{project_id}/schedule/imports/preview¶

项目内预览排程导入

对照项目读取一张排程行工作表，并回答提交它会做什么，不写入任何内容。

每行指明目标（按 id、按屏幕字段值如房间代码或按名称指定的屏幕；folder:NAME；tag:NAME；多个目标以 ; 或 | 分隔）、内容（媒体文件名，或 playlist:NAME 或播放列表 id）、开始和结束（只有日期的结束时间在当天结束时关闭），以及可选的 timezone、days (Mon-Fri)、每日时间窗口（daily_start、daily_end）、0 到 100 的 priority、名称和显示编号。

时间按每个屏幕自己的时钟读取；timezone 列可将其从另一个时区转换。

每一行都会被检查，并按列报告其错误：屏幕、文件夹或标签未知或有歧义，文件缺失或有歧义，文件无法铺满屏幕，时间无效或颠倒，结束时间已过，完全没有时间，屏幕没有时区或默认播放列表，同一屏幕上两行以相同优先级同时生效，以及层级数超过屏幕的上限（32），或活动数超过其组织在所有项目中的上限（100；每个共享层级算一个）。

内容、时间、优先级和名称一致的行合并为一个层级：一个屏幕是该屏幕自有排程的一个条目；多个屏幕、一个文件夹或一个标签是一个共享层级（活动），优先于屏幕的自有层级。

应答列出各层级及提交对每个层级的操作（create、update、unchanged）、同一导入的先前运行生成而工作表中已不存在的层级（removals）、屏幕的堆栈在提交后的样子（calendar），以及要发送给提交的指纹。工作表为 JSON 行、CSV 或 XLSX，最多 5,000 行。

限定屏幕范围的调用方无法使用（outside_screen_scope）。排程导入属于 Enterprise 计划；计划不含该功能的项目会被拒绝并返回 feature_not_in_plan（402）。模板在每个计划中都开放。

身份验证: projectBearer
请求主体: ScheduleImportRequest
操作 ID: previewScheduleImportInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
name	查询	可选	导入名称；以相同名称再次导入会更新它生成的层级（默认 import）。随文件请求体发送。
时区	查询	可选	行没有 timezone 时，时间所用的 IANA 时区。未指定时，时间按每个屏幕自己的时钟读取。
来源	查询	可选	文件名，随导入记录。
code_field	查询	可选	只从此屏幕字段读取屏幕代码（例如 code 或 room_id）；否则代码匹配任意字段。

请求主体字段

字段	描述
名称（可选，字符串）	标识该导入；同一名称会更新它生成的层级（默认 import）。minLength: 1 maxLength: 80
source（可选，字符串）	行的来源文件。maxLength: 200
时区（可选，字符串）	行没有 timezone 时，时间所用的 IANA 时区。
code_field（可选，字符串）	只从此屏幕字段读取屏幕代码。
fingerprint（可选，字符串）	预览的指纹；提交时必填。
rows（必填，数组）

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/schedule/imports/preview'

响应

状态	含义	正文和头部
200	预览。任一行有错误时 valid 为 false。	ScheduleImportPreview (application/json)
402	feature_not_in_plan — 排程导入属于 Enterprise 计划；该问题指明功能、账户所在的计划和 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/projects/{project_id}/schedule/imports¶

项目内提交排程导入

提交已预览的导入：同一张工作表及其预览返回的指纹。每个层级都会被创建、更新或移除，屏幕的排程和共享层级在一个事务中写入，并追加导入事件 schedule.imported：所有行都应用，或都不应用。

工作表的文件所需的单文件播放列表先创建（它们不改变任何屏幕）。行有错误的工作表会被拒绝（schedule_import_invalid）；预览之后项目已更改或各行读取结果不同时会被拒绝（schedule_import_stale），客户端再次预览。

以相同名称再次导入同一张工作表不会改变任何内容；更改的行会更新其层级，删除的行会移除其层级。需要能在仪表板中批准的人员，对智能体则需要具有写权限的凭据。

会更新或删除预留活动的提交返回 reserved_item（403）且不写入任何内容，除非由可以审批的人员提交。

涉及受保护屏幕的提交会被整体拒绝，返回 protected_target；即使导入没有 levels，但移除了受保护屏幕的导入条目或删除了受众涉及受保护屏幕的导入活动，也是如此。

在有受保护屏幕文件夹的项目中，如果提交的预览因服务而非工作表失败，则返回 dependency_unavailable 且不写入任何内容：请稍候片刻再次发送同一请求。工作表、活动或屏幕的验证错误按提交时的方式返回（invalid_request 和上面的其他问题）。

限定屏幕范围的调用方无法使用。排程导入属于 Enterprise 计划；计划不含该功能的项目会被拒绝并返回 feature_not_in_plan（402）。模板在每个计划中都开放。

身份验证: projectBearer
请求主体: ScheduleImportRequest
操作 ID: commitScheduleImportInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。
fingerprint	查询	可选	预览的指纹，用于 CSV 或 XLSX 请求体；JSON 请求体以成员携带。
name	查询	可选	导入名称；以相同名称再次导入会更新它生成的层级（默认 import）。随文件请求体发送。
时区	查询	可选	行没有 timezone 时，时间所用的 IANA 时区。未指定时，时间按每个屏幕自己的时钟读取。
来源	查询	可选	文件名，随导入记录。
code_field	查询	可选	只从此屏幕字段读取屏幕代码（例如 code 或 room_id）；否则代码匹配任意字段。

请求主体字段

字段	描述
名称（可选，字符串）	标识该导入；同一名称会更新它生成的层级（默认 import）。minLength: 1 maxLength: 80
source（可选，字符串）	行的来源文件。maxLength: 200
时区（可选，字符串）	行没有 timezone 时，时间所用的 IANA 时区。
code_field（可选，字符串）	只从此屏幕字段读取屏幕代码。
fingerprint（可选，字符串）	预览的指纹；提交时必填。
rows（必填，数组）

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/schedule/imports'

响应

状态	含义	正文和头部
200	提交所应用的内容。	ScheduleImportCommitted (application/json)
402	feature_not_in_plan — 排程导入属于 Enterprise 计划；该问题指明功能、账户所在的计划和 required_plan。	问题 (application/problem+json)
403	outside_screen_scope - 调用方限定于屏幕，且请求所指明或涉及的屏幕、屏幕文件夹、选择器或受众超出了这些屏幕（docs/screen-scope.md）。范围之外的 ID 和不存在的 ID 得到相同的答复；errors[0].screen_scope 携带调用方的范围，写入会被整体拒绝，绝不会被缩小范围。	问题 (application/problem+json)
409	protected_target - 此更改涉及受保护屏幕文件夹中的屏幕，且没有审核表单（docs/screen-scope.md）。通过审核清除该文件夹的保护，完成更改，再次保护该文件夹。	问题 (application/problem+json)
500	dependency_unavailable - 受保护屏幕文件夹的检查无法运行；请稍候片刻再次发送同一请求。	问题 (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/projects/{project_id}/project/browser-links/claim¶

在项目中认领浏览器链接

认领一个经过身份验证的项目的浏览器链接代码，并原子性创建一个首次 pairing_pending 屏幕及其现有浏览器配置授权。注册仍限于项目。响应仅包含安全元数据，绝不包含配置令牌、片段 URL、Cookie 或证明。

身份验证: projectBearer
请求主体: BrowserLinkClaimRequest
操作 ID: claimBrowserLinkInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	必填

请求主体字段

字段	描述
code（必填，字符串）	模式："^[23456789ABCDEFGHJKMNPQRSTUVWXYZ]{3}-?[23456789ABCDEFGHJKMNPQRSTUVWXYZ]{3}$"

请求模板和响应

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/projects/PROJECT_ID/project/browser-links/claim'

响应

状态	含义	正文和头部
201	精确的重放安全无片段浏览器链接声明。	BrowserLinkClaim（application/json）；头部：Cache-Control，RateLimit-Policy，RateLimit
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
403	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
409	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
410	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
429	稳定的 rate_limited 问题。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。	问题 (application/problem+json)；头部：Retry-After，RateLimit-Policy，RateLimit
500	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (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/projects/{project_id}/screens/pair¶

在项目中配对屏幕

声明一个全舰队通用的六字符播放器配对会话。精确的 Idempotency-Key 次重试返回持久的原始结果，不会再次消耗配额。

控制台会话以相同的请求体、Idempotency-Key、预算和问题认领到其当前项目，区别在于：对未知或已被认领的代码，其 not_found 不指明任何 CLI 命令；这是状态更改，因此遵循控制台变更规则，没有员工写入模式的影子会话会被拒绝，认领所追加的事件会指明控制台用户。folder_id 指定屏幕落入的文件夹。

限定屏幕范围的调用方（docs/screen-scope.md）必须发送其范围内的文件夹，并且只能以可以审批的人员身份配对（outside_screen_scope、approver_required）。

身份验证: projectBearer
请求主体: 配对屏幕
操作 ID: pairScreenInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	必填

请求主体字段

字段

描述

code（必填，字符串）

模式："^[23456789ABCDEFGHJKMNPQRSTUVWXYZ]{6}$"

label（可选，字符串）

minLength：1 maxLength：120

folder_id（可选，字符串）

屏幕落入的屏幕文件夹；省略则落在项目根目录。限定屏幕范围的调用方必须发送其范围内的文件夹（否则为 outside_screen_scope）。对覆盖整个项目的调用方，项目中不存在的文件夹为 invalid_request。

属于幂等请求的一部分：同一 Idempotency-Key 下的另一个 folder_id 为 idempotency_mismatch。minLength: 1

请求模板和响应

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/projects/PROJECT_ID/screens/pair'

响应

状态	含义	正文和头部
201	持久的 pairing_pending 屏幕声明。	PairingClaim（application/json）；头部：Cache-Control，RateLimit-Policy，RateLimit
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
401	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
409	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
413	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
429	稳定的 rate_limited 问题。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。	问题 (application/problem+json)；头部：Retry-After，RateLimit-Policy，RateLimit
500	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
403	outside_screen_scope，同 OutsideScreenScope；或 approver_required - 不能审批审核的、限定屏幕范围的成员不能更改屏幕播放什么或何时播放（docs/screen-scope.md）。	问题 (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/projects/{project_id}/screens/provision¶

在项目中配置屏幕

可选的仅限浏览器的新屏幕配置。始终创建一个新的 pairing_pending 屏幕；同时最多有五个在等待配对（quota_exceeded）。完全相同的重试会在十分钟内重新交付同一个片段令牌。六位字符配对仍是默认且唯一的恢复流程。folder_id 指定屏幕落入的文件夹。

限定屏幕范围的调用方（docs/screen-scope.md）必须发送其范围内的文件夹（否则为 outside_screen_scope）。

身份验证: projectBearer
请求主体: 配置屏幕
操作 ID: provisionScreenInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	必填

请求主体字段

字段	描述
label（可选，字符串）	minLength：1 maxLength：120
folder_id（可选，字符串）	屏幕落入的屏幕文件夹，与 PairScreen 相同。minLength: 1

请求模板和响应

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/projects/PROJECT_ID/screens/provision'

响应

状态	含义	正文和头部
201	新的浏览器配置链接。	ScreenProvisioning（application/json）；头部：Cache-Control，RateLimit-Policy，RateLimit
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
401	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
409	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
410	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
413	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
429	稳定的 rate_limited 问题。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。	问题 (application/problem+json)；头部：Retry-After，RateLimit-Policy，RateLimit
500	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
403	outside_screen_scope，同 OutsideScreenScope；或 approver_required - 不能审批审核的、限定屏幕范围的成员不能更改屏幕播放什么或何时播放（docs/screen-scope.md）。	问题 (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/projects/{project_id}/screens/actions¶

在项目中应用屏幕操作

对选定的舰队应用一项操作，无屏幕数量上限。选择唯一 screen_ids 或匹配活动屏幕的标签，按创建顺序。解析后的选择在任何变更前被固定，分块存储，并在 Idempotency-Key 下保存 24 小时。

每一步都使用其单屏幕变更路径，保留修订、事件、运行时信号和每屏幕限制。响应包含一页有限的结果；匹配、成功和失败描述该页内容。HTTP 202 包含总数、偏移量和 next_cursor。继续操作时，使用相同的选择器、操作和 Idempotency-Key，并传递 next_cursor 作为 after。

存在 Retry-After 时予以尊重，包括结果为零的页面。响应回显 Idempotency-Key，包括调用方省略时生成的密钥；保留此密钥以便继续。HTTP 200 表示选择完成。已回答的页面完全重放，包括每个屏幕的失败；中断的步骤重放时不重复其效果。

大型操作根据现有的每分钟 600 次组织预算节奏执行，涵盖重新加载、提示、接管、播放列表排程、重启、显示器及显示器排程；组织预算耗尽时暂停操作而非拒绝整个设备群。单屏耗尽仅失败该屏幕。

assign、takeover 或 set_playlist_schedule 步骤将带有格式的播放列表绑定到墙形状不同的屏幕时，仅该屏幕失败，返回 409 playlist_format_mismatch。分配和标签变更没有消息预算。

分配的播放列表含有 iframe src 或应用 params，读取了页面中某个屏幕所缺少的屏幕令牌时，会在该页面上添加 screen_fact_missing 警告（warnings、PlaylistWarning）。部分失败属于正常结果。同一个键下的所有页面和重试算作一次计量操作。

请求使用有界的字节载荷；对于大于传输载荷的选择，请使用标签。格式错误的选择器或操作会在触及任何屏幕之前被拒绝。selector 或 action 会在触及任何屏幕之前被拒绝。

限定屏幕范围的调用方（docs/screen-scope.md）按 screen_ids 或文件夹选择，二者都是其范围内的每个屏幕；标签选择器、范围之外的屏幕或未知屏幕会使整个操作被拒绝（outside_screen_scope），之后才会固定或提议任何内容。

涉及受保护屏幕的 Assign、takeover、takeover_clear、set_playlist_schedule 和 clear_playlist_schedule 会成为由第二位审批人决定的审核（202 pending_review），在任何访问级别都是如此；受保护屏幕上的 set_tags、add_tags 和 remove_tags 为 protected_target（409）。

带有已暂停条目（草稿）的 set_playlist_schedule 操作属于排程变更控制，Enterprise 计划包含该功能；计划不含该功能的项目会被拒绝并返回 feature_not_in_plan（402）。

身份验证: projectBearer
请求主体: ScreenActionRequest
操作 ID: applyScreenActionsInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Screenrig-Review-Note	header	可选	审查类写入时的可选提议者备注，以百分号编码的 UTF-8 发送（JavaScript 的 encodeURIComponent 写入内容）。服务器进行百分号解码（无效转义为 400 invalid_request）；解码后的备注为纯文本，修剪后最多 280 字符，无控制字符（否则 400 invalid_request）。写入成为审核时存储；实时应用时忽略。
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。
after	查询	可选	从前一结果页的 next_cursor。重用原始 Idempotency-Key 和请求体。

请求主体字段

字段	描述
selector（必填，ScreenActionSelector）
action（必填，ScreenAction）	一个舰队操作，按类型区分。每个成员仅携带自身参数；不同类型的成员视为未知字段和 invalid_request。

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/screens/actions'

响应

状态	含义	正文和头部
200	每屏幕结果。部分成功为正常答案。	ScreenActionResult（application/json）；头部：Idempotency-Key，Cache-Control，RateLimit-Policy，RateLimit
202	还有更多屏幕（使用 next_cursor 以及相同的 Idempotency-Key 和请求体继续，并遵守 Retry-After），或者在状态为 pending_review 时，该操作在提议权限下成为审核（docs/reviews.md），或者因涉及受保护屏幕文件夹中的屏幕，在任何访问级别下都成为审核（docs/screen-scope.md）。只有 assign、takeover、takeover_clear、set_playlist_schedule 和 clear_playlist_schedule 会变成审查；其他操作对 Propose 返回 insufficient_access。	inline（application/json）；头部：Idempotency-Key、Retry-After、Cache-Control、RateLimit-Policy、RateLimit
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
401	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
402	feature_not_in_plan — 设置 enabled true 的 set_reboot_schedule（排程重启）以及带 displays 锁定的 set_playlist_schedule（视频墙）属于 Plus；清除类操作和一次性命令开放。payment_required — 项目已无剩余额度。该问题指明功能、项目的计划和 required_plan。	问题 (application/problem+json)
403	insufficient_access；限定屏幕范围的调用方在其范围之外选择时返回 outside_screen_scope；不能审批的、限定屏幕范围的成员返回 approver_required。	问题 (application/problem+json)
409	playlist_format_mismatch 以及该操作的其他冲突；或当 set_tags、add_tags、remove_tags、toast、display、display_clear、set_display_schedule 或 clear_display_schedule 涉及受保护屏幕文件夹中的屏幕时返回 protected_target。	问题 (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)

POST/api/projects/{project_id}/tab-shares¶

在项目中开始标签页共享

在指定项目的屏幕上显示浏览器标签页；请求、响应、访问和限制与POST /api/tab-shares相同。

身份验证: projectBearer
请求主体: TabShareWrite
操作 ID: startTabShareInProject

参数

名称	发送	必需？	描述
project_id	路径	必填

请求主体字段

字段	描述
screen_ids (可选, array)	按id指定屏幕。重复项会合并。
folder_ids（可选，数组）	屏幕文件夹；每个文件夹都包含其所有子文件夹。
tags (可选, array)	带有任意一个标签的屏幕。
tabs（必填，array）
cookies (可选, array)	发送方用于页面的Cookie，编码后最多64 KiB。属于秘密信息；参见POST /api/tab-shares。
reload_s (可选, integer)	0（从不，默认值）或60到86400：每个页面的iframe重新加载间隔。
until (可选, string)	须严格晚于现在且不超过24小时；省略时为从现在起24小时。每个目标的接管结束时间及临时播放列表的到期时间。format: "date-time"
qr (可选, boolean)	为true时，每个页面右下角显示其地址的二维码。默认为false。

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/tab-shares'

响应

状态	含义	正文和头部
200	共享。至少接管了一个屏幕。	TabShare (application/json）；头部：RateLimit-Policy, RateLimit
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
401	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
409	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
429	稳定的 rate_limited 问题。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。	问题 (application/problem+json)；头部：Retry-After，RateLimit-Policy，RateLimit
403	outside_screen_scope，同 OutsideScreenScope；或 approver_required - 不能审批审核的、限定屏幕范围的成员不能更改屏幕播放什么或何时播放（docs/screen-scope.md）。	问题 (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/projects/{project_id}/campaigns¶

列出项目中的活动

按优先级顺序列出项目的活动（最多 100 个），即解析时读取它们的顺序。每个活动都有 reserved。

限定屏幕范围的调用方（docs/screen-scope.md）可以看到每个活动，只有整个受众都在其范围内且调用方可以更改所播放的内容时，editable 才为 true（标签叶节点和根上的“每个屏幕”规则永远不算；all 规则需要一个被包含的子项，any 规则需要每个子项都被包含）。

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/campaigns'

响应

状态	含义	正文和头部
200	项目的活动。	CampaignList (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/projects/{project_id}/campaigns¶

在项目中创建活动

为路径中指定的项目执行 createCampaign。reserved true 预留该活动，只有可以审批的人员才能设置（智能体、服务客户端或其他任何人返回 reserved_item），并追加 campaign.reserved_changed。

限定屏幕范围的调用方（docs/screen-scope.md）只能为其范围内的受众创建活动（folder 和 screen_id 叶节点；不能用标签，也不能用“每个屏幕”），否则返回 outside_screen_scope，并且只能以可以审批的人员身份创建（approver_required）。

涉及受保护屏幕的活动在任何访问级别都属于 protected_change 审核，由第二位审批人决定（202 pending_review）。reserved true 属于受保护的文件夹，新活动（草稿）上的 paused true 属于排程变更控制，二者都属于 Enterprise 计划；计划不含该功能的项目会被拒绝并返回 feature_not_in_plan（402）。

身份验证: projectBearer
请求主体: CampaignWrite
操作 ID: createCampaignInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
名称（必填，字符串）	minLength：1 maxLength：120
playlist_id（必填，字符串）	minLength：1
audience (必填, CampaignAudience)	活动定向的屏幕：all（每条规则都匹配）、any（至少一条匹配）、tag（屏幕带有该标签）、screen_id（该屏幕）或 folder（该屏幕文件夹及其内部每个文件夹中的屏幕，GET /api/screen-folders；该文件夹必须存在）中的恰好一个。规则最多嵌套 3 层，一个 audience 最多有 500 条规则。{"all": []} 表示项目的每个屏幕；在其他位置，all 和 any 至少列出一条规则。
from (可选, string)	pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T([01][0-9]\|2[0-3]):[0-5][0-9]$"
until (可选, string)	晚于 from。 pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T([01][0-9]\|2[0-3]):[0-5][0-9]$"
windows (可选, array)
monthly（可选，数组）
dates（可选，数组）
except（可选，数组）	民用日期，按升序存储且每个仅一次。例外会移除在该日期开始的每次出现，包括跨夜的后续部分；它落在 from 和 until 之间。
data（可选，PageDataCondition）	卡片数据谓词，在本地时间前评估。缺失或过期数据永不匹配。页面也遵守其普通时间范围。需要 host 功能 page.conditions；旧主机收到禁用页面。
interaction（可选，LevelInteraction）	该层级在有人使用屏幕期间生效：从一次触摸、点击或按键开始，直到 idle_s 秒内没有任何输入。典型用法：叠在展示循环之上的交互页面。idle_s 会被存储并返回（省略时为 60）。
covers（可选，字符串）	该层级的播放位置：整页（默认，存储为缺省）或 main（页面本身），用于普通播放列表；header、footer 或 side，即绘制在页面之上的条带，仅用于该区域的区域播放列表（PlaylistRegionFormat）。区域播放列表使用 full 或 main 时会被拒绝，而条带需要布局在目标显示器上的区域播放列表。允许：“full”、“main”、“header”、“footer”、“side”
displays（可选，数组）	它所播放的视频墙输出；缺省则在每个输出上播放。
start（可选，字符串）	on_time 在边界时刻切换，中断当前项目；next_item（默认，存储为缺省）等待当前项目结束。允许：“next_item”、“on_time”
priority (可选, integer)	default: 0 minimum: 0 maximum: 100
paused (可选, boolean)	default: false
reserved（可选，布尔值）	只有可以审批的人员才能预留活动（否则为 reserved_item）。default: false

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/campaigns'

响应

状态	含义	正文和头部
201	已创建。	Campaign (application/json); headers: ETag
202	写入成为审核，等待人员批准（docs/reviews.md），适用于提议权限，或者在任何访问级别下涉及受保护屏幕文件夹中的屏幕时，由第二位审批人决定（docs/screen-scope.md）。人员在控制台的 review.url 处批准、驳回或要求更改。使用相同 Idempotency-Key 的重放会返回相同的响应体。	ReviewPending（application/json）
402	feature_not_in_plan — 受保护的文件夹和排程变更控制属于 Enterprise 计划；该问题指明功能、账户所在的计划和 required_plan。将播放列表锁定到视频墙第 2 块或更靠后显示器（displays）的活动属于 Plus。该问题指明功能、项目的计划和 required_plan。	问题 (application/problem+json)
403	outside_screen_scope 或 approver_required，同 ScreenScopePlays；或 reserved_item - 预留的活动只能由可以审批审核的人员更改、暂停、删除或取消预留，智能体或服务客户端绝不可以（docs/screen-scope.md）。	问题 (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/projects/{project_id}/connections¶

列出项目的连接

按最新优先列出项目的连接，每页最多 200 个；把 next_cursor 作为 after 传回即可获取下一页。密钥、密钥文件或刷新令牌绝不会返回：secret 显示是否已保存，以及一条不属于机密的提示。读取绝不会带有授权链接。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
after	查询	可选	同一列表上一页的 next_cursor，使用相同过滤条件。省略时从最新行开始。非此类游标值为 invalid_request。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/connections'

响应

状态	含义	正文和头部
200	一页连接。	ConnectionList（application/json）；头信息：Cache-Control
400	invalid_request，包括格式错误的游标。	问题 (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/projects/{project_id}/connections¶

在项目中创建连接

在此项目中创建到 Microsoft 或 Google 的连接：使用客户自己凭据的 own_app 模式，或返回 consent_url（供完成授权的人使用的一次性链接）的 screenrig_app 模式（见 createConnection）。追加 connection.created。使用相同 Idempotency-Key 的完全相同的重试会返回同一个连接。

身份验证: projectBearer
请求主体: ConnectionWrite
操作 ID: createConnectionInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
provider（必填，字符串）	允许：“microsoft”、“google”
mode（必填，字符串）	允许：“own_app”、“screenrig_app”
名称（必填，字符串）	minLength：1 maxLength：80
config（可选，ConnectionConfigWrite）	Microsoft，own_app 模式：两个成员都要提供。Google 连接和 screenrig_app 模式不接受。
secret（可选，字符串）	own_app 模式。Microsoft：应用某个客户端密钥的值（不是其 ID，最多 1024 个字符），并带上 config.tenant_id 和 config.client_id。Google：服务账号的完整 JSON 密钥文件（最多 16384 字节）。到达时即加密封存，绝不会返回；CLI 从文件或标准输入读取，绝不从参数读取。 screenrig_app 模式下不接受。minLength: 1 maxLength: 16384

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/connections'

响应

状态	含义	正文和头部
201	已创建。screenrig_app 模式的连接带有 consent_url 和 consent_expires_at。	ConnectionConsent（application/json）；头信息：ETag, Location, Cache-Control
400	invalid_request，会指出无效的字段。	问题 (application/problem+json)
409	connection_app_not_configured、connection_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)

GET/api/projects/{project_id}/bi-connections¶

列出项目中的BI 连接

按从旧到新的顺序列出项目的 BI 连接，每页 200 个；把 next_cursor 作为 cursor 传回即可获取下一页。密钥绝不会返回：secret 仅显示是否已设置及其最后 4 个字符。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
游标	查询	可选	上一页的 next_cursor。
限制	查询	可选

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/bi-connections'

响应

状态	含义	正文和头部
200	一页连接。	BIConnectionList（application/json）；头信息：Cache-Control
400	invalid_request，包括格式错误的游标。	问题 (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/projects/{project_id}/bi-connections¶

在项目中创建 BI 连接

为项目拥有的 BI 系统添加一个连接。对于 Grafana：其地址（公共主机上的 http 或 https，可带路径前缀）以及具有 Viewer 角色的服务账户令牌。令牌会被加密封存，绝不会返回。

Grafana renders dashboards for screens through its Image Renderer plugin or remote rendering service, so the customer installs one; run POST /api/bi-connections/{id}/test to check. For Power BI (kind powerbi): config.tenant_id and config.client_id of a Microsoft Entra app registration and its client secret value as secret.

Power BI 管理员必须为该应用启用开发者设置 Embed content in apps 和 Service principals can call Fabric public APIs（管理门户，租户设置）；该应用必须是其所显示的每个工作区的成员或管理员；生产环境中的报表需要 Embedded、Fabric 或 Premium 容量。

For Tableau (kind tableau): config.url (the https address of Tableau Server, or of your Tableau Cloud pod such as https://10ay.online.tableau.com), config.site (the site content URL, empty for the default site), config.client_id and config.secret_id of a connected app with direct trust, config.username (the Tableau user the screens views are shown as) and the secret value as secret.

把响应中的 embed_origin 加入已连接应用的域名允许列表，并启用密钥。持有屏幕票据的人可以嵌入该用户能看到的任何视图，因此请使用只能看到屏幕仪表板的用户。Tableau Cloud，或 Tableau Server 2023.3 及更高版本。

适用于需要登录的网页（kind web）：显示登录后仪表板的网站的服务账号。config.login_mode 为 auto（config.login_url、config.username 和作为 secret 的密码：渲染器打开登录页面并填写表单）、steps（config.login_url 和 config.steps，由 goto、fill、click、press、wait_for 和 wait_ms 步骤组成的脚本，其值可包含 {{username}}、{{password}} 和 {{otp}}）或 none（不登录：连接用您提供的 Cookie 显示页面）。totp_secret 是账号身份验证器应用的 base32 密钥或 otpauth:// 地址：服务器计算一次性验证码（RFC 6238），只向渲染器发送验证码。cookies 是从已登录浏览器导出的 Cookie 集，适用于登录无法用脚本完成的网站（在手机上批准的单点登录、设备检查）；服务器保留该 Cookie 集，并用每次截图返回的 Cookie 续期，因此很少需要登录。

密码、种子和 Cookie 都加密封存，绝不会返回。请使用只读的服务账号。密码只会在 config.login_url 和 goto 步骤中输入，因此把它们换到另一个来源需要重新提供 secret。连续五次登录被拒绝后，连接会停止登录，直到其凭据发生变化。

没有页面渲染器的服务器会返回 bi_web_unavailable。追加 bi_connection.created。使用相同 Idempotency-Key 的完全相同的重试会返回同一个响应。

身份验证: projectBearer
请求主体: BIConnectionWrite
操作 ID: createBIConnectionInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
名称（必填，字符串）	minLength：1 maxLength：80
kind（必填，字符串）	允许：“grafana”、“powerbi”、“tableau”、“web”
config（必填，BIConnectionConfig）
secret（可选，字符串）	除 web 外必填，指定了 connection_id 的 Power BI 连接也不必填。服务账号令牌（Grafana）、应用的客户端密钥值（Power BI）、已连接应用的密钥值（Tableau）或服务账号的密码（web：login_mode 为 auto 时必填，none 不使用）。到达时即加密封存；CLI 从文件或标准输入读取，绝不从参数读取。minLength: 1 maxLength: 4096
totp_secret（可选，字符串）	Web：账号身份验证器应用的 base32 密钥（16 到 128 个字符，可含空格），或其 otpauth://totp 地址，后者可设置算法（SHA1、SHA256、SHA512）、位数（6 到 8）和周期。加密封存；只有计算出的验证码会离开服务器。maxLength: 1024
cookies (可选, array)	Web：从已登录浏览器导出的 Cookie 集。加密封存；每次截图都会续期。

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/bi-connections'

响应

状态	含义	正文和头部
201	已创建。	BIConnection（application/json）；头信息：ETag, Cache-Control
400	invalid_request，包括不是公共互联网主机的地址。	问题 (application/problem+json)
402	feature_not_in_plan — 项目的计划不包含 BI 仪表板；required_plan 指明包含它的计划。	问题 (application/problem+json)
409	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)

GET/api/projects/{project_id}/bi-views¶

列出项目中的BI 视图

Lists the project's BI views, oldest first, 200 to a page; pass next_cursor back as cursor for the next. Each carries embed_url, the address an iframe primitive shows (content_fit fill); it is null where this server has no embed host.

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

参数

名称	发送	必需？	描述
project_id	路径	必填
游标	查询	可选	上一页的 next_cursor。
限制	查询	可选

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/bi-views'

响应

状态	含义	正文和头部
200	一页视图。	BIViewList（application/json）；头信息：Cache-Control
400	invalid_request，包括格式错误的游标。	问题 (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/projects/{project_id}/bi-views¶

在项目中创建 BI 视图

添加连接的 Grafana 仪表板或其中某一个面板的视图（url：连接主机上的 /d/{uid}/... 地址，或 target），或 Grafana 公开仪表板链接的视图（kind grafana 和 target.public_url，无需连接）。

Put the answer's embed_url in an iframe primitive: the server renders the dashboard as a PNG through Grafana's /render API, refreshed every refresh_s (30 to 86400, default 300) and shared by every screen of the same size; the screen never talks to Grafana. A public dashboard plays live from Grafana, which must allow embedding.

嵌入页面只显示屏幕清单所携带的票据，因此视图只会在其所属项目的屏幕上播放。

For Power BI (kind powerbi): a report of a workspace the connection's app is a member of (url: an app.powerbi.com /groups/{workspace}/reports/{report} address, or target with workspace_id and report_id), with pages to show and rotate_s to rotate through them (pages listing two or more, or rotate_all_pages, need rotate_s of 10 to 3600; one report page needs none), and refresh_s of 0 (no refresh) or 60 to 86400 (default 300).

The page asks the server for a short-lived view-only embed token (GenerateToken, App owns data) and renews it before it expires; the screen never holds the client secret. A Power BI Publish to web link is a view without a connection (kind powerbi, target.public_url https://app.powerbi.com/view?r=...), framed as it is.

For Tableau (kind tableau): a view of the connection site (url: an address copied from Tableau, such as https://HOST/t/SITE/views/WORKBOOK/VIEW or Tableau Cloud https://HOST/#/site/SITE/views/WORKBOOK/VIEW, or Workbook/View; or target.view), optionally with target.rotate_sheets and rotate_s of 10 to 3600 to turn the workbook published sheets (rotate_s and rotate_sheets go together; rotate_sheets may be given as the whole target beside url), and refresh_s of 0 (no refresh) or 60 to 86400 (default 300).

The page asks the server for a five minute JWT with only the embed scope, signed with the connected app secret, and builds the Embedding API v3 tableau-viz from the Tableau host; the screen never holds the secret.

Tableau Public 可视化是不带连接的视图（kind tableau、target.public_url，重建为 https://public.tableau.com/views/WORKBOOK/VIEW），同样接受 rotate_sheets。对于网页（kind web）：Web 连接所属网站的一个页面（url：公共主机上的 https 地址，不带 target）。

边缘的浏览器以已登录状态打开它，如果设置了 wait_for 就等待该元素，并等待 wait_ms 毫秒（最多 10000），然后绘制 clip（一个 CSS 选择器）所指的部分（如果设置了），否则绘制整个页面。

图片每 refresh_s（60 到 86400，默认 300）重新绘制一次，由所有尺寸相同的屏幕共享，并且只在有屏幕显示该视图时才绘制；截图失败时，最后一张图片会留在屏幕上。把 wait_for 设为只有页面已登录时才存在的元素，这样就绝不会显示登录页面。追加 bi_view.created。

身份验证: projectBearer
请求主体: BIViewWrite
操作 ID: createBIViewInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
connection_id（可选，字符串）
kind（可选，字符串）	没有 connection_id 时必填；否则必须与该连接一致。允许：“grafana”、“powerbi”、“tableau”、“web”
名称（必填，字符串）	minLength：1 maxLength：80
url（可选，字符串）	连接所在主机上的 /d/{uid}/... 仪表板地址。服务器会从中读取 orgId、viewPanel（N 或 panel-N）或 panelId、from、to、var-* 和 theme。Tableau：连接所在主机上的视图地址（/views/W/V、/t/SITE/views/W/V、#/site/SITE/views/W/V）或 Workbook/View。Web：公共主机上页面的 https 地址。maxLength: 2048
target（可选，BITarget）	视图显示的内容。带连接的 Grafana：dashboard_uid（以及可选的单个面板）。带连接的 Power BI：workspace_id 和 report_id，以及 pages 或 rotate_all_pages。带连接的 Tableau：view（Workbook/View），以及 rotate_sheets。带连接的 Web：url。不带连接时：只有 public_url（Tableau 还有 rotate_sheets）。
refresh_s（可选，整数）	Grafana 为 30 到 86400；Power BI 和 Tableau 为 0 或 60 到 86400；web 为 60 到 86400。default: 300 minimum: 0 maximum: 86400
rotate_s（可选，整数）	Power BI 和 Tableau：0 或 10 至 3600；轮换页面或工作表的目标必填。default: 0 minimum: 0 maximum: 3600
fit（可选，字符串）	允许："contain", "cover", "fill" 默认值："contain"
wait_for（可选，字符串）	Web：一个元素的 CSS 选择器，该元素在页面就绪时出现，并且只在已登录时出现。maxLength: 512
wait_ms（可选，整数）	Web：页面就绪后要等待的毫秒数。minimum: 0 maximum: 10000
clip（可选，字符串）	Web：要绘制的页面部分的 CSS 选择器。maxLength: 512

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/bi-views'

响应

状态	含义	正文和头部
201	已创建。	BIView（application/json）；头信息：ETag, Cache-Control
400	invalid_request，包括不是该连接的仪表板地址的 url。	问题 (application/problem+json)
402	feature_not_in_plan — 项目的计划不包含 BI 仪表板；required_plan 指明包含它的计划。	问题 (application/problem+json)
404	not_found：该连接不在此项目中。	问题 (application/problem+json)
409	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)

GET/api/projects/{project_id}/triggers¶

列出项目中的触发器

列出项目的 CAP 警报触发器，按最旧优先（最多 20 个），每个触发器包含其摄取 URL、用户名和最新警报。密码不会在此处返回。

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/triggers'

响应

状态	含义	正文和头部
200	项目触发器。	触发器列表（application/json）；头部：Cache-Control
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

POST/api/projects/{project_id}/triggers¶

在项目中创建触发器

创建一个 CAP 警报触发器：一个入站 URL，紧急通知系统（Everbridge、Rave、Alertus、IPAWS 中继及其他 CAP 1.2 发送者）通过 HTTP Basic 凭据向其发布警报。

答案是密码出现的唯一位置（带旋转答案）：请立即将其存储在发送系统中。target 是一个标签（警报到达时所有带该标签的活动屏幕）或最多 500 个 screen_ids。

警报会接管所有带默认播放列表的目标屏幕，直到警报的 <expires>，否则为 default_for_seconds（60 到 604800，默认 3600）；参见 POST /api/triggers/{id}/cap.。组织跨其所有项目最多有 20 个触发器（trigger_limit_reached）。追加 trigger.created。

完全相同的重试使用同一个 Idempotency-Key，在二十四小时内返回同样的答复，包括密码。选择器涉及受保护屏幕的触发器为 protected_target（409），读取屏幕保护状态失败为 dependency_unavailable（500，重试同一请求）；限定屏幕范围的调用方无法使用触发器。

身份验证: projectBearer
请求主体: TriggerWrite
操作 ID: createTriggerInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
kind（可选，字符串）	允许: "cap", "overlay" 默认: "cap"
label（必填，字符串）	minLength：1 maxLength：80
target（必填，TriggerTarget）	tag 和 screen_ids 中恰好一个。
default_for_seconds（可选，整数）	没有 <expires> 的告警保持屏幕的时长: CAP 触发器为 60 到 604800，默认 3600；没有 duration 的推送保持其告警的时长: 叠加层触发器为 10 到 604800，默认 600。minimum: 10 maximum: 604800
pull（可选，CapPull）	CAP 来源平台读取触发器，包含目标屏幕位置和计数警报：cap-alert 卡片放置参数（docs/feeds.md “CAP 警报”）。每个源 URL 每分钟为每个触发器和放置请求一次。如果没有来源，平台将读取覆盖该位置的公共信息源（NWS、加拿大 NAAD 和带有区号的 MeteoAlarm）。最严重的匹配警报会像推送消息一样完全接管目标屏幕；当来源显示无警报（取消或过期）时，拉取的警报结束。过期或失败的源不会结束警报。除非提供了 sources，否则 location 是必需的。
overlay（可选，TriggerOverlayWrite）

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/triggers'

响应

状态	含义	正文和头部
201	已创建，含其网址、用户名和密码。	TriggerWithPassword（application/json）；头部：ETag，Cache-Control
400	invalid_request，包括格式错误的标签或标签和 screen_ids 同时存在。	问题 (application/problem+json)
409	trigger_limit_reached、idempotency_mismatch；或当选择器涉及受保护屏幕文件夹中的屏幕时返回 protected_target。	问题 (application/problem+json)
500	dependency_unavailable - 受保护屏幕文件夹的检查无法运行；请稍候片刻再次发送同一请求。	问题 (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/projects/{project_id}/events¶

列出项目中的事件

按序列升序列出持久项目事件。

分页是连续的：将返回的 next_cursor 作为 after 传递，精确续接页面停止处。next_cursor 是最后返回事件的游标，当有更新事件存在时，历史末尾为 null。limit 默认为 50，接受 1-200；超出范围的值返回 invalid_request 和包含 limit 的 errors[]。

不支持偏移分页。source=log 列出播放器日志：按接收时间升序报告播放器发送的条件（runtime.reported），通过 screen_id 和严重级别过滤，时间窗口从至（默认最近 24 小时，最多 31 天）。

其游标不透明：lg1_ 或 ev1_，取决于服务器存储播放器日志的位置，故返回页面的游标应传回；其他类型游标拒绝，返回 invalid_request 并指明字段。播放器日志记录无序列，不在 GET /stream/project 上，也不传递给 webhook。

当播放器日志队列接受记录时，该记录被确认，并保留用于项目的事件保留。使用最后的游标和默认窗口进行轮询，跟踪日志。播放器日志记录不在默认（source=project）列表中。除非 source 是 log，否则 from 和 to 会被拒绝并返回 invalid_request。

项目列表使用 screen_id、playlist_id 和 application_id 读取一个屏幕、播放列表或应用程序的事件，所有事件均限定为凭证的项目（一个 ID 指定读取哪些事件，永不指定谁的）：screen_id 保留资源为该屏幕的事件；playlist_id 保留资源为该播放列表的事件加上将其命名为 details.playlist_id（使用该播放列表的屏幕）的事件；application_id 保留资源为该应用程序的事件加上资源带有其为 application_id（其发布和键值条目）的事件。

非其类型 ID 的值被拒绝，返回 invalid_request 并指明字段；playlist_id 和 application_id 在 source=log 时被拒绝，日志记录仅属于屏幕。

两个来源都接受resource_id、类型和严重性（至少），彼此组合，并与 id 筛选和分页结合；播放器日志记录是runtime.reported记录，其资源为其屏幕，因此resource_id不是该屏幕或类型排除runtime.reported时，返回空页面。before（或 order=desc）分页为最新优先：next_cursor为返回结果中最旧项的游标，作为 before 继续查找更早的项。

无起始时间时，最新优先的 source=log 页面会超出默认的 24 小时，直到项目事件保留的最旧记录，每次请求最多 31 天。最新优先的 source=log 页面可能包含少于限制数的记录，甚至无记录，但带有 next_cursor；null 表示结束，位于保留日志末尾。

限定屏幕范围的调用方（docs/screen-scope.md）读取经过筛选的事件流：范围内屏幕的事件，其可见屏幕文件夹（自己的文件夹，以及上级和内部的文件夹；screen.moved 仅在目的地位于其范围内时）的事件，活动、播放列表、媒体、应用和卡片的事件，以及 playlist_change 审核。

其他所有事件都会被省略，因此一页可能少于 limit 个事件，甚至为空，但仍带有 next_cursor；请继续用它翻页。source=log 需要其范围内的 screen_id。不发送关于项目本身的事件。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
after	查询	可选	先前响应的游标：ev1_ 用于项目事件（及事件流）。播放器日志（source=log）使用 lg1_ 或 ev1_ 游标分页，依据服务器存储位置；视为不透明并传回页面返回的游标。其他类型游标返回 invalid_request。
before	查询	可选	页面最新优先，严格早于此游标：最新优先页面的 next_cursor，或任何项目游标（ev1_ 用于项目事件；source=log 时为其项目携带的不透明游标）。order=desc 时为空或缺失，从最新项目开始。
顺序	查询	可选	升序分页，使用 after；降序分页，使用 before。before 表示降序；order=asc 与 before 一起使用将被拒绝。
限制	查询	可选	页面大小。超出 1-200 范围的值将被拒绝，返回 invalid_request 和包含字段 limit 的 errors[]。
来源	查询	可选	项目列出有序的项目事件。日志列出播放器日志：播放器状态报告（runtime.reported），按接收时间升序。
resource_id	查询	可选	仅限 resource.id 为此 ID（屏幕、播放列表、媒体、webhook、代理或应用 ID）的项目。source=log 时为记录的屏幕。
类型	查询	可选	精确事件类型，如 playlist.updated，或以点结尾的系列前缀，如 playlist.，适用于所有 playlist.* 类型。
screen_id	查询	可选	仅此屏幕的事件：source=project 时资源为屏幕，source=log 时为播放器日志记录。其他 ID 类型拒绝，返回 invalid_request。
playlist_id	查询	可选	使用 source=project 时，仅返回此播放列表的事件：资源为该播放列表的事件及以 details.playlist_id 命名的事件。使用 source=log 时拒绝。
application_id	查询	可选	使用 source=project 时，仅返回此应用的事件：资源为该应用的事件及资源带有 application_id（其发布和键值条目）的事件。使用 source=log 时拒绝。
严重性	查询	可选	最低严重级别：info 包含所有项，warning 保留警告和错误，error 仅保留错误。两个来源均适用。
起始	查询	可选	使用 source=log 时，窗口开始时间（含）。默认为结束时间前 24 小时；无起始时间的最新优先页面会回溯到项目的事件保留期。
至	查询	可选	使用 source=log 时，窗口结束时间（不含）。默认为当前时间。窗口最长为 31 天。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/events'

响应

状态	含义	正文和头部
200	持久事件（source=project）或播放器日志记录（source=log）	EventList (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)

GET/api/projects/{project_id}/project/capabilities¶

在项目中获取项目功能

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/project/capabilities'

响应

状态	含义	正文和头部
200	项目功能。	ProjectCapabilities（application/json）；头部：Cache-Control
403	禁止 - 项目计划不在目录中。	问题 (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/projects/{project_id}/billing/balance¶

获取项目中的账单余额

调用项目的源感知余额快照。所有毫额度数均为规范十进制字符串。它是快照，不是支付授权；当信用卡、税务和提现通道不可用时，rails_available 为 false。

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/billing/balance'

响应

状态	含义	正文和头部
200	余额快照。	BillingBalance（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/projects/{project_id}/billing/statement¶

获取项目中的账单明细

针对调用项目的不可变已发布日志条目的稳定游标分页。保留的不是已发布条目。更正链接到原始事件，而非重写。此表面无任意授权或支付变更。

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

参数

名称	发送	必需？
project_id	路径	必填
游标	查询	可选
限制	查询	可选

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/billing/statement'

响应

状态	含义	正文和头部
200	对账单页面。	BillingStatement（application/json）
400	invalid_request - 限制超出范围。	问题 (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/projects/{project_id}/billing/usage¶

获取项目中的账单使用情况

调用项目在一个 UTC 月内的使用情况，包括已提供和已接收的字节（从不计费）、超出付款方套餐免费存储部分所计费的存储（allowance.storage_bytes），以及计入每月 10,000 次免费额度的 API 请求、计费的项目流事件和 webhook 投递尝试。自行付款的项目读取其自己的池。

另一付款方支付的项目共享该付款方与其其他项目的资金池；项目读取自身份额，付款方标识付款方。付款方资金池总额保留在付款方账单读取中。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
周期	查询	可选	以YYYY-MM格式表示的UTC月份；默认为当前月份。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/billing/usage'

响应

状态	含义	正文和头部
200	项目用量。	ProjectBillingUsage（application/json）；头部：Cache-Control
400	invalid_request - 周期不是 YYYY-MM 格式的 UTC 月份。	问题 (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/projects/{project_id}/advertising/network¶

获取项目中的广告网络

呼叫卖方的一个网络，包括其已解决的 ScreenRig 服务费。卖方无法更改该费用。

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/advertising/network'

响应

状态	含义	正文和头部
200	网络。	AdvertisingNetwork（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/projects/{project_id}/advertising/network¶

在项目中创建广告网络

若不存在，则创建调用卖方的一个网络。需要 screens=true。幂等；重复调用返回相同网络。

身份验证: projectBearer
请求主体: AdvertisingNetworkCreate
操作 ID: createAdvertisingNetworkInProject

参数

名称	发送	必需？	描述
project_id	路径	必填

请求主体字段

字段	描述
名称（必填，字符串）	maxLength：120

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/advertising/network'

响应

状态	含义	正文和头部
200	网络。	AdvertisingNetwork（application/json）
403	禁止 - 项目缺少屏幕功能或计划未知。	问题 (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/projects/{project_id}/advertising/network/rate¶

在项目中设置广告默认费率

设置卖方项目每完成播放 15 秒的默认费率。更改影响已接受广告活动的有效费率时，会暂停整个活动并标记 price_change_pending；掩码或无操作更改不影响。If-Match 带网络修订版本。

身份验证: projectBearer
请求主体: AdvertisingRate
操作 ID: setAdvertisingDefaultRateInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
If-Match	header	可选	可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。

请求主体字段

字段	描述
rate_mcr_per_15s（必填，McrString）	精确的整数毫信用额度，采用规范十进制字符串。1 额度等于 1000 mcr。模式："^-?[0-9]+$"

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/advertising/network/rate'

响应

状态	含义	正文和头部
200	已更新网络。	AdvertisingNetwork（application/json）
412	revision_conflict - If-Match 已过期。	问题 (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/projects/{project_id}/advertising/inventory¶

列出项目中的广告库存

呼叫卖方选择加入的库存。

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/advertising/inventory'

响应

状态	含义	正文和头部
200	库存。	AdvertisingInventoryList（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/projects/{project_id}/advertising/slots¶

列出项目中的广告时段

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/advertising/slots'

响应

状态	含义	正文和头部
200	插槽。	AdvertisingSlotList（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/projects/{project_id}/advertising/slots¶

在项目中创建广告位

创建一个可重复使用的卖方广告位。图片时长为 5-30 秒，视频最长为平台上限 120 秒。广告始终静音。

身份验证: projectBearer
请求主体: AdvertisingSlotWrite
操作 ID: createAdvertisingSlotInProject

参数

名称	发送	必需？	描述
project_id	路径	必填

请求主体字段

字段	描述
名称（必填，字符串）	minLength：1 maxLength：120
启用（可选，布尔值）
accepted_media（必填，数组）
max_image_duration_ms（必填，整数）	最小值：5000 最大值：30000
max_video_duration_ms（必填，整数）	最小值：1000 最大值：120000
rate_override_mcr_per_15s（可选，内联）
vast_tag_url（可选，内联）	卖方自有的 VAST 2-4 广告标签，当无邀请活动填充该卖方自有屏幕的插槽时尝试。仅限 HTTPS，端口 443 或 8443，且为公共主机。后端获取它，跟进最多五个 Wrapper，将选定的渐进式 MP4 或 WebM 媒体文件导入项目媒体，并在接受开始时触发 Impression、creativeView 和 start，接受完成时触发 complete，失败时触发 Error。不触发四分之一追踪器。宏 [CACHEBUSTING]、[TIMESTAMP]、[SCREENRIG_SCREEN_ID]、[SCREENRIG_SLOT_ID] 和 [SCREENRIG_PAGE_ID] 会被展开。插槽必须支持视频。空值、缺失或空字符串会清除标签。买家永远看不到它。

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/advertising/slots'

响应

状态	含义	正文和头部
201	插槽插槽。	AdvertisingSlot（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/projects/{project_id}/advertising/memberships¶

列出项目中的广告会员

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/advertising/memberships'

响应

状态	含义	正文和头部
200	成员资格。	AdvertisingMembershipList（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/projects/{project_id}/advertising/networks¶

列出项目中加入的广告网络

调用广告主当前所属的网络，及其授予的范围和审核策略。屏幕计数不保证为展示次数。

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/advertising/networks'

响应

状态	含义	正文和头部
200	已加入的网络。	AdvertisingJoinedNetworkList（application/json）
403	禁止 - 项目缺少广告主标志。	问题 (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/projects/{project_id}/advertising/creatives¶

列出项目中的广告创意

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/advertising/creatives'

响应

状态	含义	正文和头部
200	创意集。	AdvertisingCreativeList（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/projects/{project_id}/advertising/creatives¶

在项目中创建广告创意

将一个准备好的拥有媒体修订绑定到不可变创意。不复制字节，不重新上传，也不重新计费生成。未知或未准备好的媒体被拒绝。

身份验证: projectBearer
请求主体: AdvertisingCreativeCreate
操作 ID: createAdvertisingCreativeInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
media_id（必填，字符串）
copy（可选，字符串）	maxLength：500

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/advertising/creatives'

响应

状态	含义	正文和头部
201	创意。	AdvertisingCreative（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/projects/{project_id}/advertising/campaigns¶

列出项目中的广告活动

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/advertising/campaigns'

响应

状态	含义	正文和头部
200	广告活动。	AdvertisingCampaignList（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/projects/{project_id}/advertising/campaigns¶

在项目中创建广告活动

创建一个草稿广告活动。草稿不持有资金，不保留资源，也不授权投放。激活需要明确接受的报价。

身份验证: projectBearer
请求主体: AdvertisingCampaignDraft
操作 ID: createAdvertisingCampaignInProject

参数

名称	发送	必需？	描述
project_id	路径	必填

请求主体字段

字段	描述
名称（必填，字符串）	minLength：1 maxLength：120
category (可选, AdvertisingCategory)	广告主类别。同一类别的两则广告不会在屏幕的同一个广告时段内播放；没有类别的广告不会被分隔。允许值: "alcohol", "apparel", "automotive", "beauty", "cannabis", "consumer_electronics", "education", "entertainment", "financial_services", "food_and_beverage", "gambling", "government", "grocery", "health_and_pharma", "home_and_garden", "insurance", "jobs", "legal", "media", "political", "quick_service_restaurants", "real_estate", "restaurants", "retail", "sports_and_fitness", "technology", "telecom", "tobacco_and_vaping", "travel", "utilities"
daily_cap_mcr（必填，McrString）	精确的整数毫信用额度，采用规范十进制字符串。1 额度等于 1000 mcr。模式："^-?[0-9]+$"
lifetime_cap_mcr（必填，McrString）	精确的整数毫信用额度，采用规范十进制字符串。1 额度等于 1000 mcr。模式："^-?[0-9]+$"
image_duration_ms（可选，整数）	广告活动范围内的图片停留时间。视频保持其服务器验证的时长。默认：10000 最小值：5000 最大值：30000
max_play_price_mcr（可选，内联）	正的最大完成播放价格。省略表示无额外上限。
flight_start（必填，字符串）	格式：“date-time”
flight_end（必填，字符串）	格式：“date-time”
网络（必填，数组）

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/advertising/campaigns'

响应

状态	含义	正文和头部
201	草稿广告活动。	AdvertisingCampaign（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/projects/{project_id}/advertising/reviews¶

列出项目中的广告评论

提交给调用卖方审核的创意版本。卖方仅见提交的创意，绝不见买方库。

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/advertising/reviews'

响应

状态	含义	正文和头部
200	审核。	AdvertisingReviewList（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/projects/{project_id}/advertising/reports/spend¶

获取项目中的广告支出

买家范围内的单个广告活动支出和投放计数。金额为十进制 mcr 字符串。绝不暴露卖家的收入、银行状态或项目范围使用情况。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
格式	查询	可选	json（默认）以 JSON 返回报告。csv、xlsx 和 pdf 以附件形式返回相同的行（分页报告的每一页，最多 50000 行）。
campaign_id	查询	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/advertising/reports/spend?campaign_id=CAMPAIGN_ID'

响应

状态	含义	正文和头部
200	花费报告。	AdvertisingSpendReport（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/projects/{project_id}/advertising/reports/delivery¶

获取项目中的广告投放

卖方范围内的毛额、服务费和净额，针对一个窗口，带有其自身的交付证据。它永远不会暴露买方的钱包或其他网络。只有授权的已完成播放证据才能建立可计费的交付。窗口最长为 92 天；更宽的窗口是 invalid_request。

当持有超过 5000 个结算时，响应设置为截断，总计和计数仍涵盖全部，行仅列出最早的 5000 个。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
格式	查询	可选	json（默认）以 JSON 返回报告。csv、xlsx 和 pdf 以附件形式返回相同的行（分页报告的每一页，最多 50000 行）。
起始	查询	必填
至	查询	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/advertising/reports/delivery?from=FROM&to=TO'

响应

状态	含义	正文和头部
200	投递报告。	AdvertisingDeliveryReport（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/projects/{project_id}/playback¶

列出项目中的播放汇总

每日播放汇总。

JSON 最多返回 200 行且无速率限制。format=csv（或 Accept text/csv 无 application/json）流式传输 day_from 到 day_to（含 UTC 天；默认 day_to 为今天，day_from 为 30 天前；最多 366 天，否则 invalid_request）内所有匹配行，格式为带固定表头行的 CSV（PlaybackAggregateCsv）；仅 CSV 形式消耗 playback-export-org（每分钟 30 次）和 playback-export-ip（每分钟 60 次）预算。

两种形式都是一次计量的 API 请求。响应带有 Vary Accept。限定屏幕范围的调用方（docs/screen-scope.md）必须发送 screen_id，并且它必须是其范围内的屏幕（否则为 outside_screen_scope）；CSV 形式遵循同样的规则。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
screen_id	查询	可选
media_id	查询	可选
天	查询	可选	汇总的UTC日历日。
day_from	查询	可选	首个 UTC 天（含）。不含 day。与 day_to 一起最多跨 366 天。CSV 默认设置为 day_to 前 30 天。
day_to	查询	可选	最后的UTC日，含当日。不含当天。CSV默认为今天（UTC）。
格式	查询	可选	json（默认）、csv、xlsx 或 pdf。省略时，指定 text/csv 但未指定 application/json 的 Accept 标头会选择 csv。xlsx 和 pdf 写出同一列表的前 50000 行。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/playback'

响应

状态	含义	正文和头部
200	调用项目的每日播放汇总，包含图片和视频。每行对应一个屏幕、媒体和UTC日期。最新日期优先。标识符仅过滤调用者自己的行，绝不跨项目查询。	PlaybackAggregateList（application/json），PlaybackAggregateCsv（text/csv）；头部：Vary，RateLimit-Policy，RateLimit
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
429	稳定的 rate_limited 问题。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。	问题 (application/problem+json)；头部：Retry-After，RateLimit-Policy，RateLimit
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/projects/{project_id}/playback/plays¶

列出项目中的播放记录

每次播放记录：调用项目中每个接受的 playback.media_started（或旧版 playback.video_started）和每个接受的 playback.application_started（设置了 release_id，媒体字段为空）各一行，按 received_at 由旧到新排序，插入时并列按顺序。from（包含）和 to（不包含）限定 received_at；to 默认为现在，from 默认为 to 之前 24 小时，范围最多 31 天（否则为 invalid_request）。

最新5秒未返回：有效结束时间最多为当前时间减5秒（结算延迟），因此实时尾部不会跳过提交在其游标后的行。筛选条件包括 screen_id、media_id、playlist_id（开始显示的播放列表）和标签（播放接收时屏幕携带的标签）。

playlist_id 页面可能包含少于限制行数的内容，甚至为空；当扫描到长时间播放其他播放列表时会有 next_cursor，null 仍表示范围结束。

JSON 是最多 limit 行（默认 200，最多 1000）的一页，带 next_cursor，范围末尾为 null；用相同过滤器传回作为 cursor。order=desc（或 before）在同一范围内按最新优先分页：next_cursor 是返回的最旧行游标，范围起始为 null，传回作为 before（排除）和相同过滤器；order=asc 搭配 before 拒绝，返回 invalid_request 并指明 order，游标带最新优先页命名 cursor。

最新优先的页面可能包含少于限制行数，甚至没有数据，但会有 next_cursor；null 表示结束。

后续页面不会跳过早先页面存在的行，也不会重复行，除非播放器在未确认报告后重新发送的开始（相同 play_id，稍后收到）可能在后续页面再次出现；CSV 流以 CSV 格式（PlaybackPlayCsv）从游标到范围结束列出每个播放，最新的在前，使用 order=desc；CSV 不接受 limit。

计量按请求计算：每个 JSON 页面消耗一个 API 请求额度，而整个范围的一个 CSV 流消耗一个。每个播放请求（页面或流）消耗 playback-export-org（每分钟 30 次）和 playback-export-ip（每分钟 60 次）预算。

流限定每次写入（15 秒），客户端断开时结束；200 头后失败则连接中止，故读取到干净结尾的导出即完整。响应携带 Vary Accept。播放保留期为计划的事件保留期（出厂为 30 天；基于计划的保留使用计划自身的 7 或 90 天窗口）。

限定屏幕范围的调用方（docs/screen-scope.md）必须发送 screen_id，并且它必须是其范围内的屏幕（否则为 outside_screen_scope）；CSV 形式遵循同样的规则。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
起始	查询	可选	received_at 的包含下限。默认为 to 之前 24 小时。
至	查询	可选	received_at 的排他性上限。默认为当前时间。to - from 最多 31 天。
screen_id	查询	可选
media_id	查询	可选
playlist_id	查询	可选	仅显示此播放列表的播放。
标签	查询	可选	播放接收时屏幕携带的标签。
游标	查询	可选	上一页的 next_cursor，使用相同过滤条件。不透明。
顺序	查询	可选	升序分页，使用 cursor；降序分页，使用 before。before 表示降序；order=asc 与 before 一起使用将被拒绝。
before	查询	可选	页面最新优先，严格早于此位置：最新优先页面的 next_cursor，使用相同过滤器。不透明。
限制	查询	可选	JSON 页面大小。CSV 拒绝。
格式	查询	可选	json（默认）、csv、xlsx 或 pdf。省略时，指定 text/csv 但未指定 application/json 的 Accept 标头会选择 csv。xlsx 和 pdf 写出同一列表的前 50000 行。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/playback/plays'

响应

状态	含义	正文和头部
200	播放记录页面，或 CSV 流。	PlaybackPlayList（application/json），PlaybackPlayCsv（text/csv）；头部：Cache-Control，Vary，RateLimit-Policy，RateLimit
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
401	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
429	稳定的 rate_limited 问题。仅在权威 Retry-After 间隔后重试。固定窗口拒绝还包括适用的 RateLimit-Policy 和 RateLimit 成员；并发和字节预算拒绝省略这些可选披露。	问题 (application/problem+json)；头部：Retry-After，RateLimit-Policy，RateLimit
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/projects/{project_id}/playback/totals¶

在项目中获取播放总计

播放调用项目在包含的 UTC 天数内的总计，从每日汇总读取：by=day 返回每天一行播放数据（screen_id 或 media_id 可缩小到单个屏幕或媒体），by=screen 和 by=media 排名最繁忙的屏幕或媒体（最多 100 个），by=screen_day 返回顶级屏幕的每日序列（最多 10 个）。day_to 默认为今天（UTC），day_from 默认为 29 天前。

日期序列最多跨 366 天（缩小到屏幕或媒体时为 92 天）；排名最多 92。计数包括项目记录的所有启动次数，包括播放汇总出现前存储的。

汇总数据在摄取后最多延迟约 21 分钟。当排名基于过大窗口的切片构建时，truncated 为 true：它覆盖每个切片的最佳键。无速率限制。一次计量的 API 请求。

限定屏幕范围的调用方（docs/screen-scope.md）必须发送 screen_id，并且它必须是其范围内的屏幕（否则为 outside_screen_scope）；CSV 形式遵循同样的规则。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
格式	查询	可选	json（默认）以 JSON 返回报告。csv、xlsx 和 pdf 以附件形式返回相同的行（分页报告的每一页，最多 50000 行）。
by	查询	可选	day：每天播放；screen、media：最繁忙的键；screen_day：顶级屏幕的每日序列。
day_from	查询	可选	首个 UTC 天（含）。默认从 day_to 向前 29 天。日期序列最多跨 366 天（缩小到屏幕或媒体时为 92 天），排名最多 92 天。
day_to	查询	可选	最后的UTC日，含当日。默认为今天（UTC）。
screen_id	查询	可选
media_id	查询	可选
顶部	查询	可选	排名返回的屏幕或媒体数量（by=screen_day 最多 10 个）。by=day 时拒绝。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/playback/totals'

响应

状态	含义	正文和头部
200	请求分组的总计。	PlaybackTotals（application/json）；头部：Cache-Control
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
401	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (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/projects/{project_id}/playback/completeness¶

获取项目中的播放完整度

屏幕产生的播放中有多少到达了后端，以及缺失的播放出现在哪里。Player 会为每次媒体播放开始编号，因此从未到达的开始记录会在编号中留下空缺，例如屏幕离线时间超出其 24 小时报告队列，或队列丢弃了报告时。

在 day_from 至 day_to（含首尾）的 UTC 日期范围内（day_to 默认为今天的 UTC 日期，day_from 默认为其之前 29 天；窗口最多跨 92 天），响应包含：measured_plays，即已到达的带编号播放；missing_plays，即 Player 跳过的编号；completeness，即 measured_plays 占二者之和的比例，二者均为 0 时为 null；days，即有数据的每一天的同样三项数字，按最早在前排列，空缺计入其后一次播放所在的 UTC 日；gaps，即按最新在前排列的空缺，每项包含其 screen_id、day、from 和 to（空缺两侧播放的开始时间）以及 missing_plays。screen_id 可将 days 和 gaps 限定到某一个屏幕；limit（默认 100，最大 500）限制 gaps 的数量，存在更多时 truncated 为 true。

关闭的屏幕不会产生播放，也不会留下缺口。没有编号的播放（较旧的 Player，以及在播放编号出现之前存储的开始记录）不参与测量：它们计入 GET /api/playback/totals 的 play_count，但不属于这些数字中的任何一项。不受速率限制。计为一次计量 API 请求。

限定屏幕范围的调用方（docs/screen-scope.md）必须发送 screen_id，并且它必须是其范围内的屏幕（否则为 outside_screen_scope）；CSV 形式遵循同样的规则。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
格式	查询	可选	json（默认）以 JSON 返回报告。csv、xlsx 和 pdf 以附件形式返回相同的行（分页报告的每一页，最多 50000 行）。
day_from	查询	可选	起始 UTC 日期，包含该日。默认为 day_to 之前 29 天。与 day_to 一起构成的区间最长为 92 天。
day_to	查询	可选	最后的UTC日，含当日。默认为今天（UTC）。
screen_id	查询	可选
限制	查询	可选	列出缺口的最大数量，按最新在前排列。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/playback/completeness'

响应

状态	含义	正文和头部
200	该时间窗口的完整度及其缺口。	PlaybackCompleteness (application/json)；响应头：Cache-Control
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
401	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (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/projects/{project_id}/health/trend¶

在项目中获取 Health 趋势

项目车队健康状况按 UTC 小时统计：报告的屏幕数量，以及其中温度过高（≥80 °C）、显示器断开或崩溃（24 小时内崩溃 3 次及以上）的数量。from（含）和 to（不含）默认为最近 24 小时，最多 93 天；每页最多 limit 行（默认 100，最多 500），带 next_cursor，末页为 null。

小时数最多延迟报告约 5 分钟。限定屏幕范围的调用方会被拒绝（outside_screen_scope）；GET /api/screens/{id}/health/history 是单个屏幕的形式。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
格式	查询	可选	json（默认）以 JSON 返回报告。csv、xlsx 和 pdf 以附件形式返回相同的行（分页报告的每一页，最多 50000 行）。
起始	查询	可选	报告时间的包含下限。默认为 to 之前 24 小时。
至	查询	可选	报告时间的独占上限。默认为当前时间。
限制	查询	可选	页面大小。
游标	查询	可选	上一页的 next_cursor，使用相同过滤条件。不透明。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/health/trend'

响应

状态	含义	正文和头部
200	小时级车队健康页面。	HealthTrend（application/json）；头部：Cache-Control
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
401	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (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/projects/{project_id}/uptime/daily¶

在项目中获取项目正常运行时间

项目屏幕在包含的 UTC 天数内的每日可用性（默认及范围同 GET /api/screens/{id}/uptime）。每行汇总当天有记录状态的屏幕的在线和离线秒数；覆盖率为这些屏幕当天有记录状态的时间比例。

间隔在结束时计数，因此今天的行涵盖迄今结束的间隔；实时在线计数显示在控制台摘要中。限定屏幕范围的调用方会被拒绝（outside_screen_scope）；GET /api/screens/{id}/uptime 是单个屏幕的形式。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
格式	查询	可选	json（默认）以 JSON 返回报告。csv、xlsx 和 pdf 以附件形式返回相同的行（分页报告的每一页，最多 50000 行）。
day_from	查询	可选	首个 UTC 天（含）。默认从 day_to 向前 29 天。与 day_to 一起最多跨 366 天。
day_to	查询	可选	最后的UTC日，含当日。默认为今天（UTC）。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/uptime/daily'

响应

状态	含义	正文和头部
200	每日在线时间行，最早日期优先。	ProjectUptime（application/json）；头部：Cache-Control
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
401	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (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/projects/{project_id}/card-types¶

列出项目中的卡片类型

发现此环境已发布目录中的内置卡片，与供应的底层合并。刷新和架构验证在后台进行；此路由从不调用边缘存储桶。每条目列出其当前副本、所属层级及该层级允许的布局，以及所有提供的主要内容。

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/card-types'

响应

状态	含义	正文和头部
200	内置卡片目录，按 ID 排序	CardCatalogue（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/projects/{project_id}/card-data¶

列出项目中的卡片数据

列出项目的卡片数据文档，最多 200 个，按键升序排列。next_cursor 是最后返回的键；作为 after 传回以获取下一页，无更多时为 null。卡片数据文档保存卡片位置的动态属性（菜单部分、跑马灯项目、KPI 瓷砖）；位置的数据键名即为其中之一。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
after	查询	可选

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/card-data'

响应

状态	含义	正文和头部
200	卡片数据文档	CardDataList（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/projects/{project_id}/media¶

列出项目中的媒体

列出已准备好的媒体，最新优先，每页最多 1000 条。folder 仅保留直接包含在一个媒体文件夹（其 ID）内的文件，或仅保留库根目录的文件；格式正确但未命名文件夹 ID 不列出任何内容。next_cursor 是最后返回行的位置，若还有更多行；将其作为 after 传回，配合同样的筛选条件，用于下一页。最后一页时 next_cursor 为 null。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
标签	查询	可选	精确的媒体标签。存在此过滤器时，未标记对象将被忽略。
原始类型	查询	可选
文件夹	查询	可选	媒体文件夹 ID 仅保留该文件夹内的文件，不包括子文件夹的文件；根目录仅保留库根目录的文件。省略则列出所有文件。
ids	查询	可选	以逗号分隔的媒体 id，最多 200 个不同的值；超过则在 ids 处返回 invalid_request。只保留这些文件：没有指向任何就绪文件的 id 不会出现在结果中，其他筛选条件和分页仍然适用。值为空时不列出任何内容。
library	查询	可选	true 表示列出组织的媒体库项目而不是本项目：其条目在此为只读，并带有 library true。没有媒体库的组织，或媒体库项目本身，使用 true 时不列出任何内容。
after	查询	可选	同一列表上一页的 next_cursor，使用相同过滤条件。省略时从最新行开始。非此类游标值为 invalid_request。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/media'

响应

状态	含义	正文和头部
200	媒体	MediaList（application/json）

POST/api/projects/{project_id}/media/generations¶

在项目中创建媒体生成

根据提示生成一张静态图像，将其存储为项目中已就绪的私有媒体，并对其使用量计费。无论是否带有 Prefer: respond-async，POST 都会立即以 202 返回 Operation，因为 API 前面的代理会丢弃 100 s 内未发送任何字节的请求，而高质量静态图像可能需要更长时间。

轮询 GET /api/operations/{id}，直到 Operation 为 succeeded，此时其 result 为 {media_id, usage: {quality, credits, usd}}（MediaGenerationUsage），或为 failed，此时其 error 为问题所在。在任何供应商工作之前决定的拒绝（payment_required、reseller_generation_limit、rate_limited、not_ready、invalid_request）仍会响应 POST。

绝不包含图像字节、b64_json、对象键、签名 URL、供应商 URL、供应商成本、供应商令牌或部署模型名称。提示为客户字节，不回显。

在提示到达图像供应商之前，服务器会附加固定的构图要求：艺术作品必须填满画框边缘，不得描绘任何电视、显示器、屏幕、显示器边框、框架、边界、安装、支架、墙壁、房间、设备模型、投影阴影或已安装标牌的照片，且调用者提示中描述标牌挂放位置或显示设备的任何文字均视为位置元数据而非主题内容。

设计内部的装饰规则和边框仍然可用。调用者的提示从不被重写或删除，并保持原样存储。Idempotency-Key 会重放相同的 Operation，绝不会进行第二次计费尝试。客户端不会 PUT 或提交生成的字节。

存储的版本为有损 WebP（质量 90），精确长宽比尺寸，短边 1080 px（16:9 为 1920x1080，9:16 为 1080x1920，1:1 为 1080x1080，4:3 为 1440x1080，3:4 为 1080x1440，3:2 为 1620x1080，2:3 为 1080x1620）；供应商画布居中裁剪并重采样至该尺寸。

文件名在每次生成时都独特，格式为 generated-16x9-1a2b3c4d.webp，后缀取自媒体 ID。使用 GET /api/media/{id}/content. 获取字节。Own-gen-then-upload 仍然有效。

在 Standard 上，在入门底线（2027-01-01 前为负 1,000,000 额度，之后为零）之后，余额不足以覆盖静态图像供应商成本的两倍（向上取整为整数额度）时返回 payment_required，SCREENRIG__ENVIRONMENT=development 除外；供应商调用前的准入要求余额高于该底线至少每质量最低值：低质 200 额度，中质 800，高质 2000。

其他计划绝不会因余额而被拒绝。

通过经销商计费的组织，一旦其经销商的委托客户已被计收当月的图像生成上限（经销商等待审核期间按标价 $100，之后 $1,000，按 UTC 月计算），就会被 reseller_generation_limit (402) 拒绝，除非该组织自己的额度可以覆盖该图像；已受理的生成会完成。

所选供应商的配置为空时返回 not_ready。仅限项目 bearer。每个组织同时只能有一个生成任务进行；更多并行会返回 rate_limited。

身份验证: projectBearer
请求主体: MediaGenerationRequest
操作 ID: createMediaGenerationInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	必填
Prefer	header	可选	可选。无论是否带有此标头，该路由都会立即以 202 返回 Operation；请轮询 Operation。

请求主体字段

字段	描述
prompt（必填，字符串）	minLength：1 maxLength：4000
aspect_ratio（可选，字符串）	允许：“1:1”、“16:9”、“9:16”、“4:3”、“3:4”、“3:2”、“2:3”，默认：“16:9”
质量（可选，字符串）	允许值：“low”、“medium”、“high”，默认值：“medium”
标签（可选，字符串）	模式："^[A-Za-z0-9]{1,32}$"
references（可选，数组）

请求模板和响应

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/projects/PROJECT_ID/media/generations'

响应

状态	含义	正文和头部
202	生成已接受并继续运行；轮询 GET /api/operations/{id}，直到 Operation 为 succeeded（result 的 media_id 和 usage）或 failed（error）。相同的 Idempotency-Key 会以相同的 Operation 响应。	操作（application/json）；头信息：Preference-Applied、RateLimit-Policy、RateLimit
402	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
500	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (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/projects/{project_id}/media-folders¶

列出项目中的媒体文件夹

列出项目中的所有媒体文件夹，最多 1000 个，按名称排序。文件夹组织媒体库，播放列表选择器按文件夹播放直接包含在一个文件夹内的文件。文件夹的 parent_id 在库根目录为 null。

通过 parent_id 构建树；文件的文件夹为 Media.folder_id。library=true 改为列出组织媒体库的文件夹（只读；by:folder 选择器可以指定其中一个）。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
library	查询	可选	true 表示列出组织的媒体库项目而不是本项目：其条目在此为只读，并带有 library true。没有媒体库的组织，或媒体库项目本身，使用 true 时不列出任何内容。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/media-folders'

响应

状态	含义	正文和头部
200	媒体文件夹	MediaFolderList（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/projects/{project_id}/media-folders¶

在项目中创建媒体文件夹

在库根目录（parent_id 为空或缺失）或 parent_id 内创建一个媒体文件夹。名称经修剪，包含 1 到 100 个无控制字符的 Unicode 字符，不为“.”或“..”，且可重复。一个组织跨其所有项目最多包含 1000 个文件夹（quota_exceeded），嵌套深度最多 10 层（invalid_request）。发出 media.folder_created。

身份验证: projectBearer
请求主体: MediaFolderCreate
操作 ID: createMediaFolderInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
名称（必填，字符串）	修剪；1至100个Unicode字符，无控制字符，不允许为.或.. minLength：1 maxLength：100
parent_id（可选，内联）	创建它的文件夹；库根目录为 null 或缺失。

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/media-folders'

响应

状态	含义	正文和头部
201	已创建文件夹。	MediaFolder（application/json）；头信息：ETag
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

POST/api/projects/{project_id}/media/move¶

在项目中移动媒体

将文件（media_ids）和文件夹（folder_ids）移动到一个文件夹（folder_id），或当 folder_id 为 null 时移动到库根目录，一次请求最多 1000 个 ID，全部成功或全部失败。每个 ID 必须存在（not_found）。文件夹不能移动到自身或其内部的文件夹，且移动后所有文件夹层级不得超过 10 层（invalid_request）。

目标中已有的项目保持不变；每个移动的文件和文件夹版本号递增。移动文件改变旧新文件夹的 by:folder 选择器播放内容，基于每屏幕的下一个选择器解析；移动文件夹不改变任何文件夹自身文件。触发 media.moved。

Propose 凭据的移动使每个移动的文件待处理并排队其媒体审核，已批准播放列表的选择器通过其批准的文件夹解析，直到人员批准更改（docs/reviews.md）。

身份验证: projectBearer
请求主体: MediaMove
操作 ID: moveMediaInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
folder_id（必填，内联）	目标文件夹；库根目录为 null。
media_ids（可选，数组）
folder_ids（可选，数组）

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/media/move'

响应

状态	含义	正文和头部
200	移动的文件和文件夹数量。	MediaMoveResult（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/projects/{project_id}/media/uploads¶

在项目中创建媒体上传

身份验证: projectBearer
请求主体: MediaUploadDeclaration
操作 ID: createMediaUploadInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	必填
project_id	查询	可选	dashboardSession 必填：文件排队所在项目。必须与会话选择的项目匹配，否则返回 resource_conflict。此绑定跨标签页限制上传许可。返回的上传 ID 在项目范围内用于字节上传和提交。项目持有者可省略。

请求主体字段

字段	描述
文件名（必填，字符串）	上传字节的名称，与发送时一致：仅为文件名，最多 255 个 UTF-8 字节，不含目录、反斜杠或控制字符。minLength：1 maxLength：255
source_filename（可选，字符串）	调用方在客户端转码之前的原始文件名。仅限文件名，最多 255 个 UTF-8 字节。作为 source_filename 原样存储在就绪的媒体上，并用于派生 filename。minLength：1 maxLength：255
content_type（必填，字符串）	允许：“image/png”、“image/jpeg”、“image/webp”、“image/gif”、“video/mp4”、“video/webm”、“audio/mpeg”
bytes（必填，整数）	最小值：1 最大值：1073741824
sha256（必填，字符串）	模式："^[a-f0-9]{64}$"
标签（可选，字符串）	模式："^[A-Za-z0-9]{1,32}$"
folder_id（可选，字符串）	就绪媒体所落入的媒体文件夹；省略则落在媒体库根目录。该文件夹在声明上传时必须存在（否则在 folder_id 处返回 invalid_request），在提交时也必须存在（否则操作以 invalid_request 失败：请重新声明）。上传者（docs/uploaders.md）必须指定其文件夹之一（否则返回 outside_upload_scope）。

请求模板和响应

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/projects/PROJECT_ID/media/uploads'

响应

状态

含义

正文和头部

201

针对恰好一个私有对象 PUT 的短期签名授权。逐字发送返回的方法和每个返回的头信息。控制台也通过这种方式上传。其浏览器会将字节直接 PUT 到对象存储，绝不经过 API，因为 API 前面的代理会拒绝超过 100 MB 的请求体。

浏览器会根据正文本身设置 Content-Length，因此会发送返回的每个头信息，只有该头信息除外。

MediaUploadSession（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/projects/{project_id}/selectors/preview¶

项目内预览选择器

只读预览当前项目拥有的就绪图像或视频匹配。返回文件名排序和标准化策略；播放器每次新循环随机播放。不会推进游标、生成内容授权或更改清单。超过 1024 个匹配返回 invalid_request。

身份验证: projectBearer
请求主体: SelectorPreviewInput
操作 ID: previewSelectorInProject

参数

名称	发送	必需？	描述
project_id	路径	必填

请求主体字段

字段	描述
时区（可选，字符串）	读取媒体可用性所用的 IANA 时区；默认 UTC。
rect（可选，对象）	原语的 rect 尺寸；与 selector.fit aspect 一起使用时必填。
原始类型（必填，字符串）	允许：“image”、“video”
selector（必填，内联）

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/selectors/preview'

响应

状态	含义	正文和头部
200	当前选择器匹配。	SelectorPreview（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/projects/{project_id}/feedback/bugs¶

列出项目中的错误报告

返回调用项目自己的错误报告，最新优先，最多一百条。不会返回其他项目的提交。通过反馈 ID 读取拥有的线程。v1 中无分页游标。每条提交包含其状态及员工/代理回复，最早的先显示。

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/feedback/bugs'

响应

状态	含义	正文和头部
200	错误报告归调用项目所有。	FeedbackList（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/projects/{project_id}/feedback/bugs¶

在项目中报告错误

针对调用项目记录一条错误报告。提交的字段不可更新或删除；可在同一反馈线程回复中添加更正或更多信息。

携带相同 Idempotency-Key 的精确重试在 24 小时内返回原始提交，避免重复创建；同一密钥下不同正文返回 idempotency_mismatch。每次提交存储前均经过筛查。

正文少于 12 字符或 3 词返回 submission_too_short；描述无问题或请求的文本（随机字符、键盘乱敲）返回 submission_unclear；垃圾邮件、链接过多文本、提示注入和恶意文本返回 submission_rejected。

拒绝的提交不会被存储，其问题详情中不会重复提交的文本，在相同的 Idempotency-Key 下的精确重试会返回相同的拒绝。

切勿在标题、正文或上下文中放置凭证、Cookie、授权头、完成随机数、签名 URL 或对象密钥；凭证形文本（ScreenRig 令牌、JWT、承载令牌、云和 API 密钥、私钥）在存储提交前替换为[已编辑]，响应中带有编辑文本。

当筛选模型暂时不可用时，提交被接受并等待后台重新筛选；在一小时内多次接受后，项目将收到 submission_screening_unavailable（500，Retry-After）并稍后重试相同请求。

身份验证: projectBearer
请求主体: FeedbackWrite
操作 ID: reportBugInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	必填

请求主体字段

字段	描述
标题（必填，字符串）	单行摘要。前后空白被修剪，控制字符被拒绝。minLength：1 maxLength：120
body（必填，字符串）	完整描述。仅接受换行和制表符作为控制字符。minLength：1 maxLength：4000
context（可选，FeedbackContext）	已关闭诊断信封。每个成员为可选受限标量，结构上不允许嵌套，未知成员将被拒绝并返回 invalid_request。该结构存在以防客户端持久化参数值、凭证或自由格式环境数据。

请求模板和响应

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/projects/PROJECT_ID/feedback/bugs'

响应

状态	含义	正文和头部
201	已存储的错误报告。完全幂等的重试返回相同提交。	FeedbackSubmission（application/json）；头部：RateLimit-Policy，RateLimit
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
409	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
422	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (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)

GET/api/projects/{project_id}/feedback/features¶

列出项目中的功能请求

返回调用项目自己的功能请求，最新优先，最多一百条。不会返回其他项目的提交。通过反馈 ID 读取拥有的线程。v1 中无分页游标。每条提交包含其状态及员工/代理回复，最早的先显示。

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/feedback/features'

响应

状态	含义	正文和头部
200	调用项目拥有的功能请求。	FeedbackList（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/projects/{project_id}/feedback/features¶

请求项目中的功能

针对调用项目记录一条功能请求。提交的字段不可更新或删除；可在同一反馈线程回复中添加更正或更多信息。

携带相同 Idempotency-Key 的精确重试在 24 小时内返回原始提交，避免重复创建；同一密钥下不同正文返回 idempotency_mismatch。每次提交存储前均经过筛查。

拒绝的提交不会被存储，其问题详情中不会重复提交的文本，在相同的 Idempotency-Key 下的精确重试会返回相同的拒绝。

身份验证: projectBearer
请求主体: FeedbackWrite
操作 ID: requestFeatureInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	必填

请求主体字段

字段	描述
标题（必填，字符串）	单行摘要。前后空白被修剪，控制字符被拒绝。minLength：1 maxLength：120
body（必填，字符串）	完整描述。仅接受换行和制表符作为控制字符。minLength：1 maxLength：4000
context（可选，FeedbackContext）	已关闭诊断信封。每个成员为可选受限标量，结构上不允许嵌套，未知成员将被拒绝并返回 invalid_request。该结构存在以防客户端持久化参数值、凭证或自由格式环境数据。

请求模板和响应

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/projects/PROJECT_ID/feedback/features'

响应

状态	含义	正文和头部
201	已存储的功能请求。完全幂等的重试返回相同提交。	FeedbackSubmission（application/json）；头部：RateLimit-Policy，RateLimit
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
409	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
422	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (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)

GET/api/projects/{project_id}/service-clients¶

列出项目中的服务客户端

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

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/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/projects/{project_id}/service-clients¶

在项目中创建服务客户端

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

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

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

身份验证: agentIdentityBearer
请求主体: ServiceClientChange
操作 ID: createServiceClientInProject

参数

名称	发送	必需？	描述
project_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 --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/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/projects/{project_id}/media-sync-accounts¶

列出项目中的媒体同步账户

Lists the project's media sync accounts, newest first (200 per page; next_cursor continues). Each shows its tenant and client id, its state and its last test; the client secret is never returned, only whether one is set and its last four characters.

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

参数

名称	发送	必需？	描述
project_id	路径	必填
游标	查询	可选	上一页的 next_cursor。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/media-sync-accounts'

响应

状态	含义	正文和头部
200	项目的账户。	MediaSyncAccountList（application/json）；头信息：Cache-Control
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

POST/api/projects/{project_id}/media-sync-accounts¶

在项目中创建媒体同步账户

添加一个通过读取来同步的账号。kind microsoft365 存储项目自己的 Microsoft Entra 应用的凭据，使同步可以读取 SharePoint 或 OneDrive 工作文件夹：config.tenant_id 是租户的目录 ID 或主域名（common、organizations 和 consumers 会被拒绝），config.client_id 是应用的应用程序 ID，secret 是应用某个客户端密钥的值；该应用需要经管理员同意的 Microsoft Graph 应用程序权限 Sites.Selected（在每个站点上授予）或 Files.Read.All。

可以不用这三项，改用 config.connection_id 指定项目的 Microsoft 连接（createConnection，两种模式均可），由它登录并保存密钥。kind canva 只接受名称：账号处于 pending_consent，响应带有 authorize_url（有效期至 authorize_expires_at 的一次性链接），由 Canva 账号的所有者在登录 Canva 后打开，通过 screenRIG 的 Canva 集成连接。

该授权属于项目，因此其同步在连接它的人离开后仍会继续。

没有 Canva 集成的服务器会返回 409 canva_not_configured。kind dropbox 的工作方式与 canva 相同：账户处于 pending_consent 状态，authorize_url 是一次性链接，由 Dropbox 账户的所有者在登录 Dropbox 后打开，以允许只读访问（files.metadata.read、files.content.read、account_info.read、sharing.read）。

它通过 screenRIG 的 Dropbox 应用进行；当 config.app_key 指定了客户自己的 Dropbox 应用时，则通过该应用进行（使用 PKCE，因此没有 app secret；该应用必须将 https://API_ORIGIN/api/dropbox/callback 列为重定向 URI）。

没有 screenRIG Dropbox 应用的服务器，会对没有 app_key 的 dropbox 账户返回 409 dropbox_not_configured。kind google_drive 立即处于 ready 状态，读取与 config.service_account_email 共享的文件夹：即 screenRIG 的服务账号，或当 secret 是该服务账号的 JSON 密钥时，客户自己的服务账号。

与 screenRIG 的服务账号共享的文件夹，仅当共享者或所有者是邮箱已验证的项目成员时才会同步。没有 screenRIG 服务账号的服务器，会对不带密钥的 google_drive 账户返回 409 google_drive_not_configured。密钥在存储时即加密封存，绝不会返回，也不会写入日志。追加 media_sync_account.created。

使用相同 Idempotency-Key 的完全相同的重试会返回同一个账户（Canva 或 Dropbox 的重试会得到新的链接）。

身份验证: projectBearer
请求主体: MediaSyncAccountWrite
操作 ID: createMediaSyncAccountInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
kind（必填，字符串）	允许：“microsoft365”、“canva”、“dropbox”、“google_drive”
名称（必填，字符串）	minLength：1 maxLength：80
config（可选，object）	对于 microsoft365，要么同时提供 tenant_id 和 client_id 并带上 secret，要么只提供 connection_id：本项目某个 Microsoft 连接的 ID。对于 dropbox，app_key 可选，用于指定客户自己的 Dropbox 应用。canva 和 google_drive 不接受此项。
secret（可选，字符串）	microsoft365 搭配 tenant_id 和 client_id 时必填：应用某个客户端密钥的值（不是其 ID），最多 1024 个字符。对于 google_drive，可选：客户自己的 Google Cloud 服务账号的 JSON 密钥（type 为 service_account），其 client_email 会成为该账户的 service_account_email；不提供时，账户通过 screenRIG 的服务账号读取。不能与 connection_id 一起使用，canva 和 dropbox 也不接受。 minLength: 1 maxLength: 8192

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/media-sync-accounts'

响应

状态	含义	正文和头部
201	已创建，密钥已被遮蔽；Canva 或 Dropbox 账户还带有 authorize_url。	MediaSyncAccountConnect（application/json）；头信息：ETag, Cache-Control
400	invalid_request。	问题 (application/problem+json)
402	feature_not_in_plan — 项目的计划不包含媒体同步；required_plan 指明包含它的计划。	问题 (application/problem+json)
409	canva_not_configured（此服务器没有 Canva 集成；仅限 kind canva）、dropbox_not_configured（没有 screenRIG Dropbox 应用，且没有 config.app_key；仅限 kind dropbox）、google_drive_not_configured（没有 screenRIG 服务账号，且没有密钥；仅限 kind google_drive）、resource_conflict 或 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)

GET/api/projects/{project_id}/media-syncs¶

列出项目中的媒体同步

Lists the project's media syncs, newest first (200 per page; next_cursor continues), optionally of one account_id or state. Each shows its source folder, the media folder it fills, its cadence, state, next run and the summary of its last run.

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

参数

名称	发送	必需？	描述
project_id	路径	必填
游标	查询	可选	上一页的 next_cursor。
account_id	查询	可选	仅列出通过此账户读取的同步。
状态	查询	可选	仅列出处于此状态的同步。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/media-syncs'

响应

状态	含义	正文和头部
200	项目的同步。	MediaSyncList（application/json）；头信息：Cache-Control
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

POST/api/projects/{project_id}/media-syncs¶

在项目中创建媒体同步

provider canva：通过已连接的 Canva 账户读取设计（design 是其 id 或 canva.com/design/ID/... 地址），并保存该同步，立即到期。

Each run asks Canva for the design's last change and, when it moved, exports the pages (pages, default all; format png gives one image per page and mp4 one video) and imports them into the media folder, replacing the bytes of a page already imported under the same media id so the playlists that use it update; a page the design no longer has leaves play like a removed SharePoint file.

Canva 不再显示的设计会使同步停在 error 状态（运行错误 design_unavailable），并保留媒体。

账户看不到的设计或页面会返回 409 media_sync_source_refused。provider dropbox：url 是形如 https://www.dropbox.com/home/... 的 Dropbox 文件夹地址、已连接账户添加到其 Dropbox 的共享文件夹链接，或以 / 开头的路径；它通过已连接的 Dropbox 账户读取一次，并保存该同步，立即到期。

团队空间中的文件夹从团队根目录读取。每次运行都从 Dropbox 在该文件夹中保存的位置继续，因此只读取变更。

账户无法打开的文件夹会返回 409 media_sync_source_refused；Dropbox 不再认可其连接的账户会返回 409 dropbox_reconnect_required。provider google_drive：url 是形如 https://drive.google.com/drive/folders/ID 的 Google Drive 文件夹地址或其 id，并已与该账户的 service_account_email 共享（Viewer 权限即可）。

每次运行都会列出文件夹，并比较每个文件的校验和。Google Docs、Sheets 和 Slides 文件会因 unsupported_type 被跳过。地址无法打开的文件夹会返回 409 media_sync_source_refused。

通过 screenRIG 的服务账号读取时，文件夹必须由邮箱已验证的项目成员共享或拥有（403 media_sync_sharer_not_member），并且每次运行都会再次检查（运行错误 sharer_not_member 会使同步停在 error 状态）。provider sharepoint：通过该账户读取文件夹的地址（形如 https://TENANT.sharepoint.com/sites/SITE/LIBRARY/FOLDER 的 SharePoint 站点地址，或共享链接；应用必须能看到它：Sites.Selected 需要在站点上授予权限，共享链接需要 Files.Read.All），并保存该同步，立即到期。folder_id 是文件落入的媒体文件夹；省略时，同步会创建一个以来源文件夹命名的媒体文件夹。

Each run imports the images (png, jpeg, webp, gif), videos (mp4, webm) and audio (mp3) directly in the source folder, replaces the bytes of a file that changed under the same media id so playlists that use it update, and takes a file removed at the source out of play: its media is deleted, or, while screens still hold it, moved to a Removed subfolder and deleted later.

Subfolders are ignored; other files are listed as skipped with the reason. every is the seconds between runs, 300 to 86400, default 900. A folder the provider refuses is 409 media_sync_source_refused and one it cannot reach is 500 media_sync_source_unavailable; nothing is stored. Appends media_sync.created.

身份验证: projectBearer
请求主体: MediaSyncWrite
操作 ID: createMediaSyncInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
provider（必填，字符串）	允许：“sharepoint”、“canva”、“dropbox”、“google_drive”
account_id（必填，字符串）	该提供商对应 kind 的账户：sharepoint 对应 microsoft365，canva、dropbox 和 google_drive 对应各自同名的 kind。
url（可选，字符串）	sharepoint（必填）：文件夹的 SharePoint 地址或共享链接，只读取一次以找到该文件夹，不会存储。dropbox（必填）：文件夹的 Dropbox 地址、账户已添加的共享文件夹链接，或以 / 开头的路径。google_drive（必填）：文件夹的 Google Drive 地址或其 id。maxLength: 4096
design（可选，字符串）	canva（必填）：设计的 id，或其 canva.com/design/ID/... 地址。maxLength: 2048
页面（可选，数组）	canva：要同步的页面；省略表示所有页面。设计之后页数减少时，缺失的页面会退出播放。
format（可选，字符串）	canva：png 每页生成一张图像；mp4 将各页生成一个视频。Allowed: "png", "mp4" default: "png"
folder_id（可选，字符串）	文件落入的媒体文件夹。省略则创建一个以源文件夹命名的文件夹。
every（可选，整数）	两次运行之间的秒数；默认为 900。minimum: 300 maximum: 86400
名称（可选，字符串）	默认为源文件夹的名称。minLength: 1 maxLength: 80

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/media-syncs'

响应

状态	含义	正文和头部
201	已创建，立即到期。	MediaSync（application/json）；头信息：ETag, Cache-Control
400	invalid_request。	问题 (application/problem+json)
402	feature_not_in_plan — 项目的计划不包含媒体同步；required_plan 指明包含它的计划。	问题 (application/problem+json)
403	media_sync_sharer_not_member：通过 screenRIG 服务账号读取的 Google Drive 文件夹，不是由邮箱已验证的项目成员共享或拥有的。	问题 (application/problem+json)
409	media_sync_source_refused（提供商拒绝了应用、其权限或该文件夹）、dropbox_reconnect_required（必须重新连接 Dropbox 账户）、dropbox_not_configured、google_drive_not_configured、resource_conflict（同一来源已同步到该媒体文件夹）或 idempotency_mismatch。	问题 (application/problem+json)
500	media_sync_source_unavailable：无法连接到提供方，或其返回了失败。	问题 (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/projects/{project_id}/fleet-links¶

列出项目中的车队链接

列出项目的设备链接，按最旧优先（最多 50 个）。在有效的“管理”下，每个 URL 为空且 url_redacted 为 true，因为 URL 用于创建屏幕。

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/fleet-links'

响应

状态	含义	正文和头部
200	项目车队链接。	FleetLinkList（application/json）；头部：Cache-Control
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

POST/api/projects/{project_id}/fleet-links¶

在项目中创建车队链接

创建车队链接：一个播放器 URL（https://play.<domain>/player/#fleet=<secret>），打开它的每个设备都会成为该项目中的独立屏幕，无需配对码。将其放入设备管理器，如 Google 管理控制台的自助服务应用。

每个新屏幕会继承链接的标签、字段和播放列表，并从设备获取标签（优先管理员资产 ID，其次为位置），否则使用下一个默认标签。已绑定屏幕的播放器不会再创建新屏幕：其密钥在重新加载和重启时保持屏幕身份不变。

恢复出厂设置或重新安装后，报告屏幕序列号或此项目创建的屏幕的 DUID 的设备会恢复该屏幕（screen.recovered），而不是创建新屏幕，前提是旧密钥已静默十分钟。

密钥在 URL 片段中，浏览器不会发送给服务器。max_screens 限制该链接创建的屏幕数量，expires_at 在该时间使链接失效，禁用链接也有同样效果。每个组织跨其所有项目最多有 50 个车队链接（fleet_link_limit_reached）。追加 fleet_link.created。

携带相同 Idempotency-Key 的精确重试在 24 小时内返回相同答案。

身份验证: projectBearer
请求主体: FleetLinkWrite
操作 ID: createFleetLinkInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
label（必填，字符串）	minLength：1 maxLength：80
启用（可选，布尔值）	默认为 true。
标签（可选，ScreenTags）	设备组选择器标签，0 到 16 个唯一且精确的标签，每个标签符合媒体标签语法。在 ScreenPatch 中，数组替换整个集合，空数组则清空；重复或格式错误的标签为 invalid_request。更改标签会提升屏幕版本（If-Match 保护），并附加 screen.updated，详情见 details.tags；不会更改清单版本。标签永远不会出现在运行时清单中，也不会用于授权。
fields（可选，对象）	链接创建的每个屏幕初始带有的字段；卡片放置通过 {screen.field.NAME} 读取它们。
playlist_id（可选，字符串）
max_screens（可选，整数）	最小值：1 最大值：10000
expires_at（可选，字符串）	链接的到期时间（RFC 3339）；已过期的链接不会创建或找回任何屏幕。省略表示永不过期。已经过去的时间也会被接受，并使链接立即过期。format: "date-time"

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/fleet-links'

响应

状态	含义	正文和头部
201	已创建，含其网址。	FleetLink（application/json）；头部：Cache-Control
400	invalid_request，包括未知的 playlist_id 或格式错误的标签或字段。	问题 (application/problem+json)
409	fleet_link_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)

GET/api/projects/{project_id}/webhooks¶

列出项目中的 webhook

以 Webhook 的数据结构按从旧到新的顺序列出项目的 Webhook 通知（最多 50 个）；GET /api/notifications 会列出所有渠道的通知。此处绝不会返回签名密钥。需要项目权限；仅有报告权限的凭据会被拒绝并返回 403 forbidden，因为响应包含接收方 URL。

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/webhooks'

响应

状态	含义	正文和头部
200	项目 webhook。	WebhookList（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/projects/{project_id}/webhooks¶

在项目中创建 webhook

创建一个 webhook，接收项目自身的持久事件，作为签名的 HTTPS POST。url 必须是公共互联网主机上的 https：IP 字面量或该名称的所有当前 DNS 解析均为公共（拒绝私有、回环、链路本地、CGNAT、IPv6 非 2000::/3、文档及其他保留范围，返回 webhook_url_rejected）。

端口必须是 443（默认）或 8443，否则为 webhook_url_rejected。主机在每次传递前解析并再次检查，连接精确拨号至检查的地址，因此后续 DNS 变更无法重定向传递。event_types 列出精确事件类型（screen.online）或以 .* 结尾的前缀（screen.*）。

每个组织最多有 50 个通知，涵盖所有渠道（webhook_limit_reached）。签名密钥由服务器生成，仅在本次响应和 rotate-secret 中返回；请妥善保存。以相同的 Idempotency-Key 原样重试，24 小时内会返回同一响应（包括密钥）。

投递从 notification.created 之后的第一个事件开始。

身份验证: projectBearer
请求主体: WebhookWrite
操作 ID: createWebhookInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
url（必填，字符串）	公共互联网主机上的https URL，端口443（默认）或8443。不含用户信息或片段。maxLength：2048 格式：“uri”
event_types（必填，WebhookEventTypes）	精确的事件类型（如 screen.online），或以 .* 结尾的前缀（如 screen.*，即所有以 screen. 开头的类型）。notification.test 永远不会通过订阅分发；它只会由 POST /api/webhooks/{id}/test 发送。
启用（可选，布尔值）	默认：true
描述（可选，字符串）	maxLength：200

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/webhooks'

响应

状态	含义	正文和头部
201	已创建。密钥仅在此处及密钥轮换时显示。	WebhookWithSecret（application/json）；头部：Cache-Control
400	invalid_request 或 webhook_url_rejected。	问题 (application/problem+json)
409	webhook_limit_reached、idempotency_mismatch，或在项目不属于任何组织时返回 resource_conflict。	问题 (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/projects/{project_id}/alerts¶

列出项目中的警报

列出项目的屏幕警报：每个屏幕和条件在持续期间各有一条（open），以及在套餐的事件保留期内已结束的警报（resolved）。

警报在其条件的事件到达时打开（screen.offline、display_disconnected、temperature_high 或 on_battery 健康变化、screen.storage_shortfall、停滞的 screen.manifest_upgrade、error 级别的 screen.status_changed、判定为停滞、空白或冻结的 screen.glass_changed），并在解除事件到达时解决；crashing 是提醒，不是警报。counts.attention 统计未被确认、暂缓或静音的未解决警报，即控制台显示的数字。

屏幕因后端发出的重启而重启时，在重启完成或发出后十分钟之前，不会开启 screen_offline 或 display_disconnected 警报；届时仍成立的条件会在那一刻开启其警报。未解决的警报在前，最新的在前；翻页时像之前一样传回 next_cursor。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
格式	查询	可选	json（默认）以 JSON 返回报告。csv、xlsx 和 pdf 以附件形式返回相同的行（分页报告的每一页，最多 50000 行）。
状态	查询	可选
screen_id	查询	可选
before	查询	可选	上一页的 next_cursor。
限制	查询	可选

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/alerts'

响应

状态	含义	正文和头部
200	一页警报。	AlertList (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/projects/{project_id}/alert-mutes¶

列出项目中的警报静音

列出项目中尚未结束的静音，最先结束的排在最前（最多 50 条）。

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/alert-mutes'

响应

状态	含义	正文和头部
200	项目当前有效的静音。	AlertMuteList (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/projects/{project_id}/alert-mutes¶

在项目中创建警报静音

为维护让屏幕静音，直到某个最多 30 天后的时间点：包括 screen_ids 所指定的屏幕，以及在提醒到期时带有 tags 中任一标签的每个屏幕。它们的警报仍会打开和解决，并标记为 muted，且从不需要关注；每个通知中关于它们的提醒都会被跳过（muted）。

每个组织跨其所有项目最多有 50 条当前有效的静音（alert_mute_limit_reached）。追加 alert_mute.created。

身份验证: projectBearer
请求主体: AlertMuteWrite
操作 ID: createAlertMuteInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
screen_ids (可选, array)
标签（可选，ScreenTags）	设备组选择器标签，0 到 16 个唯一且精确的标签，每个标签符合媒体标签语法。在 ScreenPatch 中，数组替换整个集合，空数组则清空；重复或格式错误的标签为 invalid_request。更改标签会提升屏幕版本（If-Match 保护），并附加 screen.updated，详情见 details.tags；不会更改清单版本。标签永远不会出现在运行时清单中，也不会用于授权。
until（必填，字符串）	最多 30 天后。format: "date-time"
note（可选，字符串）	maxLength：200

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/alert-mutes'

响应

状态	含义	正文和头部
201	已创建。	AlertMute (application/json)
409	alert_mute_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)

GET/api/projects/{project_id}/notifications¶

列出项目中的通知

按从旧到新的顺序列出覆盖该项目的组织通知，涵盖所有渠道（最多 50 个）。status、failing_since、last_success_at 和 last_failure_at 是此项目自己的值。此处绝不会返回 Webhook 的签名密钥。

需要项目权限；仅有报告权限的凭据会被拒绝并返回 403 forbidden，因为响应包含接收方 URL 和收件人。

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/notifications'

响应

状态	含义	正文和头部
200	项目的通知。	NotificationList (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/projects/{project_id}/notifications¶

在项目中创建通知

创建通知。channel email 发送给 recipients（owner，或项目成员的 user_ids）；channel webhook 以签名方式 POST 到 url，url 遵循 webhook URL 规则（公共互联网主机上的 https，端口 443 或 8443，否则 webhook_url_rejected）。conditions 列出其触发的屏幕状态变化；电子邮件通知至少需要一个，webhook 需要 conditions 或 event_types。screen_tags 将 conditions 限定在带有其中任一标签的屏幕；空值表示每个屏幕，或由 audience 按活动受众的规则指定屏幕。min_severity 和 severity 对提醒进行过滤和评级，active_hours 在其窗口之外保留或丢弃提醒。

条件只有持续满 hold_minutes（默认 10）后才会发出通知；若条件在提醒发出后解除，随后会发出一条恢复提醒。该通知仅覆盖此项目；每个组织最多有 50 个通知，系统生成的默认通知不计入（notification_limit_reached）。

Webhook 的签名密钥由服务器生成，仅在本次响应和 rotate-secret 中返回；请妥善保存。以相同的 Idempotency-Key 原样重试，24 小时内会返回同一响应（包括密钥）。提醒从 notification.created 之后的第一个事件开始发送。

身份验证: projectBearer
请求主体: NotificationWrite
操作 ID: createNotificationInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
channel（必填，string）	允许："email", "webhook", "slack", "teams", "pagerduty", "telegram"
描述（可选，字符串）	供人识别的名称。maxLength: 200
conditions（可选，NotificationConditions）
screen_tags（可选，ScreenTags）	设备组选择器标签，0 到 16 个唯一且精确的标签，每个标签符合媒体标签语法。在 ScreenPatch 中，数组替换整个集合，空数组则清空；重复或格式错误的标签为 invalid_request。更改标签会提升屏幕版本（If-Match 保护），并附加 screen.updated，详情见 details.tags；不会更改清单版本。标签永远不会出现在运行时清单中，也不会用于授权。
audience (可选, CampaignAudience)	活动定向的屏幕：all（每条规则都匹配）、any（至少一条匹配）、tag（屏幕带有该标签）、screen_id（该屏幕）或 folder（该屏幕文件夹及其内部每个文件夹中的屏幕，GET /api/screen-folders；该文件夹必须存在）中的恰好一个。规则最多嵌套 3 层，一个 audience 最多有 500 条规则。{"all": []} 表示项目的每个屏幕；在其他位置，all 和 any 至少列出一条规则。
min_severity（可选，NotificationSeverity）	提醒的严重级别，由低到高。已开启的提醒具有其条件的严重级别：screen_offline 为 error，其他每个条件为 warning，除非通知的 severity 另有设置。已解决的提醒和测试为 info。允许："info", "warning", "error"
severity（可选，NotificationSeverityOverrides）	此通知的条件到严重级别的映射，例如 {"not_playing": "error"}。它计入 min_severity，也是 Teams 和 PagerDuty 为该条件显示的严重级别。未列出的条件保持其默认值。在补丁中，空对象与 null 一样，清除所有覆盖。
active_hours（可选，NotificationActiveHours）	已开启提醒发出的时间：窗口（screenrig.schedule/v1），按 timezone 解读。窗口关闭期间到期的提醒会等到下一次开启（outside hold，默认），若届时条件仍然成立才发出，因此条件先行解除则不发送任何内容，或者被跳过（outside drop；last_error outside_hours）。已发送的已开启提醒对应的已解决提醒始终发出，无论是否在时段内，测试则忽略时段。crashing 与其他条件一样被保留或丢弃。时段在提醒首次发出时判定；失败的提醒按常规计划重试，不论时段。添加、更改或移除时段，会立即对为旧时段而保留的提醒重新判定。
reach_drop（可选，NotificationReachDrop）	活动触达减少多少时发送 reach_dropped 提醒的最小值：screens 是最少失去的屏幕数（默认 1），percent 设置后是活动发布时所触达屏幕的最小占比；减少必须同时满足两者。较小的减少不会排入提醒，已排队的提醒如果到期时减少已低于该阈值，则会被跳过 (condition_cleared)。仅适用于 reach_dropped 条件；未带该条件的通知返回 invalid_request。
hold_minutes（可选，integer）	条件需持续多久才会发出通知。crashing 不设等待期。default: 10 minimum: 0 maximum: 1440
recipients（可选，NotificationRecipients）	仅限电子邮件。owner（提醒发送时该项目的所有者）或项目成员的 user_id；不是成员的 user_id 会返回 invalid_request。每位收件人都会通过其已验证的地址收到电子邮件。已离开项目或没有已验证地址的收件人会被跳过。
url（可选，字符串）	仅限 Webhook：公共互联网主机上的 https URL，端口 443（默认）或 8443。不得包含 userinfo 或片段。maxLength: 2048 format: "uri"
event_types（可选，NotificationEventTypes）	仅限 Webhook。项目事件发生时也会通过 POST 发送，格式与 Webhook 发送的完全一致：精确类型（如 screen.online），或以 .* 结尾的前缀（如 screen.*）。notification.test 绝不会被分发。
destination（可选，NotificationDestination）	仅适用于 Slack、Teams、PagerDuty 和 Telegram，对它们必填。凭据须为服务签发的格式：slack 为传入 Webhook URL（hooks.slack.com）；teams 为 Workflows Webhook URL（logic.azure.com 或 powerplatform.com；Office 365 连接器 URL 已停用）；pagerduty 为 32 位 Events API v2 路由密钥；telegram 为机器人令牌。其他格式会返回 notification_destination_rejected。它会被加密封存，绝不会返回，读取时只以 destination_hint 的形式出现。 minLength: 1 maxLength: 2048
telegram_chat_id（可选，NotificationTelegramChat）	仅适用于 Telegram，对其必填。要发布到的聊天：其数字 id（群组或频道为负数）或 @channelname。不是凭据。 pattern: "^(-?[0-9]{1,20}\|@[A-Za-z][A-Za-z0-9_]{4,31})$"
启用（可选，布尔值）	默认：true

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/notifications'

响应

状态	含义	正文和头部
201	已创建。Webhook 的密钥仅在此处和 rotate-secret 中显示。	Notification (application/json)；响应头：Cache-Control
400	invalid_request、webhook_url_rejected 或 notification_destination_rejected。	问题 (application/problem+json)
402	feature_not_in_plan — 告警路由（Slack、Teams、PagerDuty 或 Telegram 渠道，或 min_severity、severity、active_hours 或 audience 规则）属于 Plus。使用默认规则的电子邮件和 webhook 通知，以及 loop_stalled、glass_blank 和 glass_frozen 条件，所有套餐都包含。该问题指明功能、项目的计划和 required_plan。	问题 (application/problem+json)
409	notification_limit_reached、idempotency_mismatch，或在项目不属于任何组织时返回 resource_conflict。	问题 (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/projects/{project_id}/notes¶

列出项目中的备注

列出项目的备注，按最新优先。备注是代理为其未来自我和项目其他代理写的简短纯文本事实；它是上下文，绝非指令或批准。

任何活动凭证读取，包括只读，读取不计入API计量。state为open（默认）、resolved或all；about_id保留关于一个屏幕或播放列表的备注，author_id保留一个智能体写的备注。

将下一个 next_cursor 作为 after 传回以获取下一页；最后一页为空。new 标记为另一个代理在此调用者上次读取备注后写入的未读备注。

读取备注是打开备注的第一页，无 about_id 或 author_id：该答案计算新内容相较于之前读取的差异，然后将读取标记移动到当前（同一列表的后续页保持之前标记）。

它还包含审核：最多 5 条待审核的开放备注（最旧优先），调用方应确认其仍然有效，否则解决。审核返回后 30 天未答复的，备注自动解决为 not_confirmed。

只有具有管理权限的智能体才能移动其标记并启动 30 天；只读智能体或服务客户端得到相同响应但不更改。其他页面或筛选返回空审查且不移动。计数为项目的未关闭备注数，以及该调用者的新和到期数。

限定屏幕范围的智能体只能列出关于其自身屏幕、播放列表和项目的备注：列表、审核和计数会省略关于范围之外屏幕的备注，跨项目的列表会省略该智能体受限的项目，因此请选择该项目。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
状态	查询	可选
about_id	查询	可选	仅关于此屏幕或播放列表的备注。
author_id	查询	可选	仅此智能体编写的备注。
after	查询	可选	上一页的 next_cursor。
限制	查询	可选

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/notes'

响应

状态	含义	正文和头部
200	一页备注，包含待审阅备注及计数。	备注列表（application/json）
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (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/projects/{project_id}/notes¶

在项目中添加备注

为项目的智能体添加备注：其他智能体会据此行动的事实，绝非进度报告、聊天或秘密。正文为修剪后 1 到 2000 字符的纯文本，可跨行。

包含凭证的文本（令牌、密钥、私钥、URL 中的密码）会被拒绝，返回 note_contains_credential，且作为模型指令的文本返回 note_rejected；不存储任何内容，详情中不会重复文本。关于名称，若是项目的一个屏幕（包括归档）或播放列表，否则返回 not_found。ttl_seconds（3600 到 31536000）创建一个临时备注，过期后解决；无此字段的备注在添加或最后确认后 90 天进入审核。替换名称为此备注所替代的开放备注：在同一事务中解决为替代（已解决时返回 note_not_open）。

规范化文本（已去除首尾空白、合并空白并转为小写）和 about 与某条未解决备注匹配的正文，会确认该备注并以 200 返回，而不是新增一条；不会追加 note.added 事件。一个组织跨其所有项目最多持有 200 条未解决备注；第 201 条为 note_limit_reached，其详情会列出最多 5 条应先解决的备注。

追加 note.added（替换备注时追加 note.resolved），不含文本。携带相同 Idempotency-Key 的精确重试在 24 小时内返回首次答案。

对于限定屏幕范围的智能体（docs/screen-scope.md），about 为其范围之外的屏幕或项目未知的屏幕，或 replaces 指向关于其范围之外屏幕的备注，属于 outside_screen_scope（403），并且不存储任何内容。

身份验证: projectBearer
请求主体: 备注写入
操作 ID: addNoteInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	可选	省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。

请求主体字段

字段	描述
body（必填，字符串）	纯文本，修剪后长度为1到2000个字符；保留换行符。minLength：1 maxLength：2000
关于（可选，内联）
ttl_seconds（可选，整数）	添加后此时长过期备注。无此项时，备注90天后复审。minimum: 3600 maximum: 31536000
replaces（可选，字符串）	一个被此条覆盖的未解决备注；它被标记为已替代。模式："^(?:(?:stage\|qa\|development)_)?nte_[A-Za-z0-9_-]{16,24}$"

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/notes'

响应

状态	含义	正文和头部
201	已添加。	备注（application/json）
200	文本匹配了一个打开的备注，已确认并返回。	备注（application/json）
400	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
403	outside_screen_scope - 调用方限定于屏幕，且请求所指明或涉及的屏幕、屏幕文件夹、选择器或受众超出了这些屏幕（docs/screen-scope.md）。范围之外的 ID 和不存在的 ID 得到相同的答复；errors[0].screen_scope 携带调用方的范围，写入会被整体拒绝，绝不会被缩小范围。	问题 (application/problem+json)
404	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
409	note_not_open、note_limit_reached 或 idempotency_mismatch。	问题 (application/problem+json)
422	note_contains_credential 或 note_rejected。	问题 (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/projects/{project_id}/support/status¶

项目中的支持状态

任何活跃项目的可用性和时间。chat_allowed 对所有活跃项目均为真，包括 Standard。当真人可按请求加入聊天时，human_available 为真（Education、Premium 和 Enterprise）；Standard 和 Plus 提供文档和 AI 支持。staffed 表示工作人员当前是否在工作时间内。Luna 在所有套餐上都会立即回答。

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

参数

名称	发送	必需？	描述
project_id	路径	必填

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/support/status'

响应

状态	含义	正文和头部
200	支持结果。	SupportStatus（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/projects/{project_id}/support/conversations¶

列出项目中的支持对话

项目对话，最新优先，最多100条。员工未读计数基于每个认证人员或智能体。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
before	查询	可选	来自前一页下一游标的会话 ID。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/support/conversations'

响应

状态	含义	正文和头部
200	支持结果。	SupportConversationList（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/projects/{project_id}/support/conversations¶

在项目中创建支持对话

所有套餐均可使用；Luna 首先立即回答。在真人可加入的地方（支持状态中的 human_available），请求真人会为工作人员暂停 Luna；在 Standard 和 Plus 上该请求会被忽略，由 Luna 回答。存储或 Slack 之前进行筛选。

少于8个字符或3个单词的开场消息返回 submission_too_short；非问题或非疑问句返回 submission_unclear；垃圾信息、含大量链接的文本、提示注入和不安全文本返回 submission_rejected。拒绝的文本不会被保留或发送给 Luna，问题详情也不会重复。

除 ScreenRig 凭证（承载令牌、云和 API 密钥、私钥）外，凭证形状的文本在存储前被替换为 [已编辑]；ScreenRig 凭证材料返回 invalid_request。新对话在一个 Slack 线程中开始；后续内容保持在该线程内。相同密钥的请求在 24 小时内可重放，包括拒绝。

身份验证: projectBearer
请求主体: SupportWrite
操作 ID: createSupportConversationInProject

参数

名称	发送	必需？	描述
project_id	路径	必填
Idempotency-Key	header	必填

请求主体字段

字段	描述
body（必填，字符串）	minLength：1 maxLength：4000
human_requested（可选，布尔值）	请求真人，这会暂停 Luna 并等待工作人员。仅在真人可加入的地方计数（human_available：Education、Premium 和 Enterprise）；在 Standard 和 Plus 上会被忽略，由 Luna 回答。默认：false

请求模板和响应

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/projects/PROJECT_ID/support/conversations'

响应

状态	含义	正文和头部
201	支持结果。	SupportSubmission（application/json）
422	消息被筛选拒绝：submission_too_short 或 submission_unclear（仅限开头消息）或 submission_rejected。详情不重复文本。	问题 (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/projects/{project_id}/reviews¶

列出项目中的评论

项目审核（docs/reviews.md）：在提议访问权限下提出的播放列表和屏幕变更，以及广告网络买家提交的创意（类型 ad_creative）。

最新优先，每页最多 limit（默认 50，最多 100）；将 next_cursor 作为游标传回，带相同过滤器。状态 pending（默认）、decided（其他状态）或 all；种类 narrows 到一种。

控制台会话读取所有类型；持有者读取其能力覆盖的类型（播放列表对应 playlist_change，屏幕对应 screen_change，广告对应 ad_creative），无法读取的类型返回空页。pending_count 统计调用者可见的所有类型的待审核数量。

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

参数

名称	发送	必需？
project_id	路径	必填
状态	查询	可选
kind	查询	可选
限制	查询	可选
游标	查询	可选

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/reviews'

响应

状态	含义	正文和头部
200	一页审核。	ReviewList（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/projects/{project_id}/card-data/{key}¶

项目范围获取卡数据

返回文档及其修订版本。ETag 是修订版本，用于下一次写入的 If-Match。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
key	路径	必填	卡片数据键。不得以 feed: 开头。

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/card-data/KEY'

响应

状态	含义	正文和头部
200	卡片数据文档	CardDataEntry（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/projects/{project_id}/card-data/{key}¶

项目范围放置卡数据

创建或替换卡片数据文档。当项目播放列表中的卡片位置绑定该键时，文档必须仅包含每个绑定卡片的动态属性并通过验证；否则写入被拒，返回 card_data_invalid 并指明卡片及属性路径，且无更改。无绑定位置的键接受任意 JSON 对象。

以 media: 开头的每个字符串都是媒体引用，格式为 media:<id>，供卡片绘制（照片）；在任何键上必须命名该项目中准备好的、已批准的图像，每个文档最多 256 个不同媒体，否则写入时拒绝，错误名为 card_media_invalid，包含属性路径和 media_id。

读取密钥内容的屏幕随后可从 GET /media/{media_id}. 获取这些媒体。显示读取密钥的投放位的屏幕接收 screen.card_data_changed 并在原位重新获取；项目日志记录带有 card_data_entry 资源的 kv.updated，该资源永远不会到达播放器。

限制、配额、计量、修订和幂等性由应用的键值存储管理。

智能体和 webhook 的写入也有频率限制，按套餐对每个组织限制（Standard 和 Plus 每分钟 60 次，Education 和 Premium 600 次，Enterprise 3,000 次），所有套餐中每个键均限制为每分钟 60 次；超出限制的写入会被 rate_limited 和 Retry-After 拒绝，且不计量。

身份验证: projectBearer
请求主体: CardDataWrite
操作 ID: projectScoped_putCardData

参数

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

请求主体字段

字段

描述

document（必填，对象）

卡片数据文档：最大 1 MiB 的 JSON 对象。当卡片位置绑定密钥时，仅持有该卡的动态属性。以 media: 开头的字符串为媒体引用，media:<id>，指本项目中已准备好且已批准的图像。

expires_at（可选，字符串）

绝对过期；省略数据永不过期。格式：“date-time”

ttl_seconds（可选，整数）

自首次提交的写入起算的 TTL。与 expires_at 互斥。重试会保留原来的过期时间。两者都省略则清除过期时间。

请按写入方的计划确定它：当卡片的文档在有屏幕显示该卡片期间过期且没有写入来续期时，卡片会变为空白，并由 card_data_stale 通知条件告知项目，因此停止运行的作业会被发现。minimum: 1 maximum: 31536000

请求模板和响应

shell · 请求模板

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/card-data/KEY'

响应

状态	含义	正文和头部
200	卡片数据文档	CardDataEntry（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/projects/{project_id}/card-data/{key}¶

项目范围删除卡数据

删除卡片数据文档。绑定到该键的卡片在屏幕上隐藏，直到再次写入文档。

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

参数

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

请求模板和响应

shell · 请求模板

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/card-data/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/projects/{project_id}/feeds/{family}¶

项目范围获取订阅

读取共享的第三方订阅文档：内置卡片位置使用相同参数读取的文档（docs/feeds.md）。

查询参数会规范化为卡片的 feed 键，由 ScreenRig-Feed-Key 头命名：weather、airquality 和 alerts 取 lat 和 lon（舍入到 0.25 度的单元格）；earthquakes 取 lat、lon、radius_km（10 到 20000，默认 500）、min_magnitude（0 到 9，默认 2.5）和 hours（1 到 168，默认 24）；cyclones 取 basins（逗号分隔的 at、ep、cp、wp；默认全部），以及可选的 lat、lon 和 radius_km（该地点附近的风暴）；tides 取 station（NOAA 潮汐预测站 ID，如 9414290）或 lat 和 lon（100 公里内最近的站点，否则为 invalid_request）；launches 无参数（全球后续发射）；rates 取 base（欧洲央行参考货币，默认 EUR）；crypto 取 symbols（CoinGecko 的 ID 或代码，逗号分隔，最多 20 个）和 currency（默认 usd）；headlines 取 url（http 或 https 的 RSS 或 Atom URL）；drugalerts（screenrig.drugalerts/v1）某个国家近期的召回报告：country（us、ca 或 gb，必填）和 category（默认为 drug，或 food）；respiratory（screenrig.respiratory/v1）某个地点每周的流感、COVID-19 和 RSV 活动：country（us 或 gb，必填）和 region（美国的州、属地或 DC，按名称或邮政编码，或英格兰或 UKHSA 的某个地区；为空则表示全国）。

请求从不调用提供者。200 表示文档（架构、fetchedAt、归属及其家族字段，按卡片合同定义）；其 ETag 是字节的 sha256，If-None-Match 返回 304；Cache-Control max-age 直到下一次计划获取。202 表示尚无文档：读取注册需求，feed 工作线程约一分钟内获取密钥（Retry-After）。

API 读取会缓存密钥 24 小时。组织跨其所有项目每天最多注册 50 个新密钥（超过返回 rate_limited）。无源的家族在此部署返回 not_found。

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

参数

名称	发送	必需？	描述
project_id	路径	必填
ScreenRig-Project	header	可选	已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。
family	路径	必填	订阅系列。
lat	查询	可选
lon	查询	可选
radius_km	查询	可选
min_magnitude	查询	可选	地震：最低震级。
小时	查询	可选	地震：小时窗口。
basins	查询	可选	cyclones：逗号分隔的 at、ep、cp、wp。
station	查询	可选	tides：NOAA 潮汐预测站 ID，如 9414290。不提供时，由 lat 和 lon 选取 100 公里内最近的站点。
base	查询	可选
符号	查询	可选
货币	查询	可选
url	查询	可选
country	查询	可选	drugalerts：us、ca 或 gb。respiratory：us 或 gb。两者都必填。
category	查询	可选	drugalerts：drug（默认）或 food。
region	查询	可选	respiratory：美国的州、属地或 DC，按名称或邮政编码，或英格兰或 UKHSA 的某个地区；为空则表示全国。
If-None-Match	header	可选

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/feeds/FAMILY'

响应

状态	含义	正文和头部
200	Feed 文档	FeedDocument（application/json）；头部：ETag，ScreenRig-Feed-Key
202	尚无文档；提要工作者将在下一次运行时获取密钥。	FeedPending（application/json）；头部：Retry-After，ScreenRig-Feed-Key
304	文档与 If-None-Match 匹配。	无正文
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

GET/api/projects/{project_id}/advertising/networks/{seller_project_id}/inventory¶

项目范围列出广告加入库存

调用者成员内的已选择库存和可重用时段。绝不暴露卖方的屏幕截图、播放列表或项目范围数据。

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

参数

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

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/projects/PROJECT_ID/advertising/networks/SELLER_PROJECT_ID/inventory'

响应

状态	含义	正文和头部
200	允许的库存和时段。	AdvertisingJoinedInventory（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/projects/{project_id}/agents/self¶

项目范围获取当前智能体

返回与调用项目持有者关联的代理安装及 connection_ready。当至少一名成员拥有 passkey 或密码时，项目即为就绪。身份状态为诊断信息，不计入 API 计量。

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

参数

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

请求模板和响应

shell · 请求模板

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/projects/PROJECT_ID/agents/self'

响应

状态	含义	正文和头部
200	当前智能体和项目连接就绪状态。	AgentSelfStatus（application/json）；头信息：Cache-Control
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)

POST/api/projects/{project_id}/agents/self/disconnect¶

项目范围断开当前智能体

仅撤销调用项目的成员资格及其项目令牌，保留全局身份、其他成员资格、项目和内容。使用相同的加密有效撤销承载者重复调用为无操作成功。断开最后一个活动智能体将返回 agent_lockout_risk，除非明确允许 allow_last_agent。不计入 API 计量。

代理访问 JWT（包括只读）断开代理与其令牌项目的连接；成员关系结束，项目同意离开代理授权，该身份/项目对旧访问令牌被切断。令牌中的其他项目继续工作。断开后使用相同 JWT 重试为无操作成功。

身份验证: revocableAgentBearer
请求主体: AgentDisconnectRequest
操作 ID: projectScoped_disconnectCurrentAgent

参数

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

请求主体字段

字段	描述
allow_last_agent（可选，布尔值）	显式接受最后活跃代理持有者的丢失。注册的控制台 passkey 保持独立管理权限。默认：false

请求模板和响应

shell · 请求模板

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/projects/PROJECT_ID/agents/self/disconnect'

响应

状态	含义	正文和头部
204	智能体已断开连接。	无正文；头部：Cache-Control
401	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
409	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)
默认	稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。	问题 (application/problem+json)