OpenAPI YAMLOpenAPI JSON问题 YAMLAPI 概览
此分组有 84 个操作，由 api/openapi.yaml 生成。可按路径、操作或认证筛选。每个端点都会列出其输入；展开后可查看请求模板和响应代码。模板需要您自己的值和符合架构的请求体。
用你的值替换大写占位符。对于JSON请求，请保存符合request.json模式的请求体。Cookie示例使用经过身份验证会话的本地Cookie存储。
屏幕
列出屏幕
默认列表返回 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）只列出其范围内的屏幕。
未指明项目的请求，会省略调用方限定于屏幕的每个项目；请指明项目以列出它。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| 状态 | 查询 | 可选 | 省略 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。 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/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) |
列出屏幕文件夹
列出项目中的所有屏幕文件夹，最多 1000 个，按名称排序。
文件夹用于组织屏幕并将其作为目标：活动受众叶子节点 {"folder": ID} 匹配该文件夹及其内部每个文件夹中的屏幕，车队操作选择器 by:folder 作用于同一批屏幕，文件夹的 default_playlist_id 是其中没有自己播放列表的屏幕所显示的播放列表。parent_id 在项目根目录为 null；通过 parent_id 构建树。screens 统计直接位于每个文件夹内的实时屏幕数量。
屏幕的文件夹是 Screen.folder_id。限定屏幕范围的调用方（docs/screen-scope.md）可列出其范围内的文件夹及其上级文件夹，上级文件夹为只读，使其树有一个根；上级文件夹不带屏幕数量，同级文件夹隐藏。未指明项目的请求会省略调用方限定于屏幕的每个项目。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/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) |
创建屏幕文件夹
在项目根目录（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），由第二位审批人决定。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| 名称（必填，字符串） | 修剪；1 到 100 个 Unicode 字符，无控制字符，不为 . 或 ..，在同级中唯一。minLength: 1 maxLength: 100 |
| parent_id（可选，内联） | 要在其中创建的文件夹；项目根目录为 null 或缺失。 |
| default_playlist_id（可选，字符串） | 为文件夹中没有自己播放列表的屏幕指定的已批准播放列表。minLength: 1 |
请求模板和响应
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/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) |
获取屏幕文件夹
限定屏幕范围的调用方（docs/screen-scope.md）读取其范围内的文件夹及其上级文件夹；任何其他文件夹和未知的 ID 都属于 outside_screen_scope。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screen-folders/RESOURCE_ID'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 一个屏幕文件夹。 | ScreenFolder（application/json）；头部：ETag |
| 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) |
更新屏幕文件夹
重命名文件夹（name），连同内部所有内容一起移动它（parent_id，项目根目录为 null），或设置其中没有自己播放列表的屏幕所显示的默认播放列表（default_playlist_id，null 表示清除）。文件夹不能移动到自身或其内部的文件夹，且移动后所有文件夹层级不得超过 10 层（invalid_request）。
移动或默认值更改会在约 15 秒内重新解析其中的屏幕，响应的 levels 列出这些屏幕获得或失去的活动和文件夹默认值。更改会推进文件夹修订号并发出 screen.folder_updated；相同的值不执行任何操作。
If-Match 可选地保护修订版本。protected true 保护该文件夹及其内部的每个文件夹，false 清除保护；请单独发送（否则为 invalid_request）。只有可以审批的人员才能设置：智能体、服务客户端或不能审批的成员会得到 approver_required。
更改会追加 screen.folder_protection_changed（details 为 folder_id、protected）。清除保护，以及对包含受保护屏幕的文件夹进行移动或默认播放列表更改，属于 protected_change 审核（202 pending_review），由第二位审批人决定。
限定屏幕范围的调用方（docs/screen-scope.md）只能更改其范围内的文件夹：parent_id 也必须指向范围内的文件夹（根目录属于 outside_screen_scope），并且对其范围本身所指定的文件夹，无权更改 protected。protected true 属于受保护的文件夹，Enterprise 计划包含该功能；计划不含该功能的项目会被拒绝并返回 feature_not_in_plan（402）。
已设置的保护会继续把更改留待第二位审批人决定，在每个计划中，请求移除保护都属于审核。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| 名称（可选，字符串） | 修剪；1 到 100 个 Unicode 字符，无控制字符，不为 . 或 ..，在同级中唯一。minLength: 1 maxLength: 100 |
| parent_id（可选，内联） | 将该文件夹移入此文件夹；项目根目录为 null。 |
| default_playlist_id（可选，内联） | 为文件夹中没有自己播放列表的屏幕指定的已批准播放列表；null 表示清除。 |
| protected（可选，布尔值） | 保护该文件夹及其内部的每个文件夹（docs/screen-scope.md）。只有可以审批的人员才能设置。请单独发送：与任何其他成员一起发送，请求即为 invalid_request。在受保护的文件夹上清除它本身就是受保护的更改，属于由第二位审批人决定的审核（202 pending_review）。 |
请求模板和响应
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/screen-folders/RESOURCE_ID'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 已更新文件夹。 | ScreenFolder（application/json）；头部：ETag |
| 202 | 写入成为审核，等待人员批准（docs/reviews.md），适用于提议权限，或者在任何访问级别下涉及受保护屏幕文件夹中的屏幕时，由第二位审批人决定（docs/screen-scope.md）。人员在控制台的 review.url 处批准、驳回或要求更改。 使用相同 Idempotency-Key 的重放会返回相同的响应体。 | ReviewPending（application/json） |
| 402 | feature_not_in_plan — 受保护的文件夹属于 Enterprise 计划；该问题指明功能、账户所在的计划和 required_plan。 | 问题 (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) |
删除屏幕文件夹
删除一个文件夹。其中的内容都不会被删除：其屏幕和文件夹上移到被删除文件夹的父级（没有父级时移到项目根目录），每个被移动的文件夹都会推进其修订版本，这些屏幕会重新解析。
当活动受众指向该文件夹时，请求会被拒绝并返回 resource_conflict，因此不会有排程悄悄失去其屏幕：请先更改或删除这些活动。响应写明其屏幕获得或失去的层级。发出 screen.folder_deleted。If-Match 可选用于保护修订版本。
限定屏幕范围的调用方（docs/screen-scope.md）只能删除其范围内且其范围本身未指定的文件夹（outside_screen_scope）；其中的屏幕上移到父级。删除受保护文件夹或包含受保护屏幕的文件夹，属于 protected_change 审核（202 pending_review），由第二位审批人决定。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求模板和响应
curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screen-folders/RESOURCE_ID'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 已删除；其内容现位于其父级中。levels 写明其屏幕获得或失去的文件夹默认播放列表。 | ScreenFolderDeleteResult (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) |
移动屏幕
将屏幕（screen_ids）和文件夹（folder_ids）移动到一个文件夹（folder_id），或当 folder_id 为 null 时移动到项目根目录，一次请求最多 1000 个 ID，全部成功或全部失败。每个 ID 必须存在（not_found）。文件夹不能移动到自身或其内部的文件夹，且移动后所有文件夹层级不得超过 10 层（invalid_request）。
目标中已有的项目保持不变；每个被移动的屏幕和文件夹的修订都会递增。被移动的屏幕会在约 15 秒内重新解析其播放列表：levels 列出其进入或离开文件夹受众的活动，以及它们获得或失去的文件夹默认播放列表。
发出 screen.moved，其 details 携带数量（screens、folders）以及每个被移动项目原来的位置：moves [{screen_id, from}]（from 是文件夹 id，根目录为空）和 folder_moves [{folder_id, from_parent}]，每项最多 1000 个，因此历史可以用此路由把它们移回去。
限定屏幕范围的调用方（docs/screen-scope.md）将其范围内的屏幕和文件夹移入其范围内的某个文件夹；范围之外的任何 ID 或目的地以及项目根目录，都会使整个移动被拒绝（outside_screen_scope），屏幕在检查与写入之间离开范围时也是如此。
移入或移出受保护文件夹属于 protected_change 审核（202 pending_review），由第二位审批人决定。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| folder_id（必填，内联） | 目标文件夹；项目根目录为 null。 |
| screen_ids (可选, array) | |
| folder_ids（可选，数组） |
请求模板和响应
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/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) |
获取排程日历
回答某个主体的屏幕在 [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。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| 起始 | 查询 | 必填 | |
| 至 | 查询 | 必填 | |
| screen_id | 查询 | 可选 | |
| folder_id | 查询 | 可选 | |
| 标签 | 查询 | 可选 | |
| campaign_id | 查询 | 可选 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/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) |
配对屏幕
声明一个全舰队通用的六字符播放器配对会话。精确的 Idempotency-Key 次重试返回持久的原始结果，不会再次消耗配额。
控制台会话以相同的请求体、Idempotency-Key、预算和问题认领到其当前项目，区别在于：对未知或已被认领的代码，其 not_found 不指明任何 CLI 命令；这是状态更改，因此遵循控制台变更规则，没有员工写入模式的影子会话会被拒绝，认领所追加的事件会指明控制台用户。folder_id 指定屏幕落入的文件夹。
限定屏幕范围的调用方（docs/screen-scope.md）必须发送其范围内的文件夹，并且只能以可以审批的人员身份配对（outside_screen_scope、approver_required）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| 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 |
请求模板和响应
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/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) |
配置屏幕
可选的仅限浏览器的新屏幕配置。始终创建一个新的 pairing_pending 屏幕；同时最多有五个在等待配对（quota_exceeded）。完全相同的重试会在十分钟内重新交付同一个片段令牌。六位字符配对仍是默认且唯一的恢复流程。folder_id 指定屏幕落入的文件夹。
限定屏幕范围的调用方（docs/screen-scope.md）必须发送其范围内的文件夹（否则为 outside_screen_scope）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| Idempotency-Key | header | 必填 |
请求主体字段
| 字段 | 描述 |
|---|---|
| label（可选，字符串） | minLength：1 maxLength：120 |
| folder_id（可选，字符串） | 屏幕落入的屏幕文件夹，与 PairScreen 相同。minLength: 1 |
请求模板和响应
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/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) |
应用屏幕操作
对选定的舰队应用一项操作，无屏幕数量上限。选择唯一 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）。部分失败属于正常结果。同一个键下的所有页面和重试算作一次计量操作。
请求使用有限字节负载；选择大于传输负载时请使用标签。格式错误的选择器或操作在触及任何屏幕前被拒绝。
限定屏幕范围的调用方（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、toast、display、display_clear、set_display_schedule 和 clear_display_schedule 为 protected_target（409）。
带有已暂停条目（草稿）的 set_playlist_schedule 操作属于排程变更控制，Enterprise 计划包含该功能；计划不含该功能的项目会被拒绝并返回 feature_not_in_plan（402）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| 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。 |
请求模板和响应
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/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) |
获取屏幕
返回pairing_pending、活动和归档屏幕。已删除屏幕无法找到。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 屏幕 | 屏幕（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) |
更新屏幕
更新屏幕的 name、playlist_id、timezone、wall、tags、fields、location、log_level、toast_level、display 或 kiosk。标签变更会返回 levels：屏幕加入或离开的活动，以及每个活动变更前后的覆盖范围。wall 设置屏幕的视频墙（一个对象）或清除它（null）。
设置视频墙需要已声明 display.wall 宿主能力的 Player，否则返回 409 wall_unsupported。
更改它会重新生成清单修订号，并追加 screen.updated，附带 details.wall（wall 对象，清除后为 null）。fields 会合并到屏幕自身的值中（字符串表示设置字段，null 表示移除该字段，值为 null 的 fields 会清除所有字段），location 用于设置屏幕所在位置（null 表示清除）。
更改任意一项都会为显示播放列表的屏幕重新生成清单修订号，使其卡片放置项重新展开其中的 {screen.…} 占位符，并追加 screen.updated，附带 details.fields（完整的新对象，清除后为 {}）或 details.location（新对象，清除后为 null）。
语法拒绝的名称或值，或第三十三个字段，会返回指明它的 invalid_request。log_level（debug、info、warn、error）和 toast_level（info、alert、error）设置播放器生成或显示的最低级别，null 会清除各自的设置；任何其他值都是 invalid_request。
更改其中任何一个都会重新生成清单修订，清单以根成员 verbosity 携带它们。display 设置或清除显示器的空闲变暗和亮度设置：display.idle {after_s, wake} 在没有触摸或按键达 after_s 秒（30 到 86400）后，或在 wake 列出 presence 时屏幕前无人达同样时间后，使屏幕变暗，唤醒事件（touch、presence 或两者，各一次）会立即使其重新亮起；display.brightness {mode} 为 auto（由设备的光线传感器设置亮度）或 fixed（默认值，操作员设定的亮度）。
你发送的成员会替换它，null 会清除它，省略的成员保持不变，display 为 null 会同时清除两者。kiosk {lock} true 会将播放器固定在屏幕上（Android 屏幕固定），false 或 null 则解除固定。显示排程和覆盖保留各自的路由；display 成员中若指定 schedule 或 override，则为 invalid_request。
超出范围或类型错误的值会返回 invalid_request，并指明路径（display.idle.after_s）。
更改其中任何一项都会重新生成显示播放列表的屏幕的清单修订，并更改每个屏幕的清单 ETag；清单在根成员 display 中携带 display.idle 和 display.brightness，并以根成员 kiosk 携带锁定，同时追加 screen.manifest_changed；屏幕将它们读回为 Screen.display.idle、Screen.display.brightness 和 Screen.kiosk。
无论是哪种播放器，后端都会存储你发送的内容：播放器只有在其主机能力声明了 display_power.idle、brightness.auto 或 kiosk_lock 时才会应用设置，较旧的播放器会忽略它们。分配格式与屏幕视频墙不匹配的播放列表会返回 409 playlist_format_mismatch。
在 Propose 访问权限下，仅修改 playlist_id 的补丁会变成一次审核（202 pending_review）；任何其他字段，包括 wall、fields、location、display 和 kiosk，都会返回 insufficient_access。没有已批准版本的播放列表为 playlist_not_approved。
当屏幕随后显示的播放列表含有 iframe src 或应用 params，读取了该屏幕所缺少的屏幕令牌时，响应会携带 screen_fact_missing 警告（warnings、PlaylistWarning），并且该屏幕的清单会省略该原语。
对于受保护的屏幕，无论访问级别如何，playlist_id 都需要另一位具有审批权限的人员审核 (202 pending_review)，并且必须单独发送（与 name 一起发送会返回 invalid_request）；tags、fields、location、timezone、wall 和 display 会返回 protected_target (409)，即使与 playlist_id 一起发送也一样。重命名仍会立即生效。在已归档屏幕上清空 playlist_id (null) 会返回 409 screen_archived。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| Screenrig-Review-Note | header | 可选 | 审查类写入时的可选提议者备注，以百分号编码的 UTF-8 发送（JavaScript 的 encodeURIComponent 写入内容）。服务器进行百分号解码（无效转义为 400 invalid_request）；解码后的备注为纯文本，修剪后最多 280 字符，无控制字符（否则 400 invalid_request）。 写入成为审核时存储；实时应用时忽略。 |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| 名称（可选，字符串） | minLength：1 maxLength：120 |
| playlist_id（可选，内联） | 屏幕的默认值：播放列表 id 用于分配；null 用于清除；省略则保留。接管、活动、排程和从文件夹继承的默认值优先。没有有效内容时，已配对的 Player 显示待机画面。 |
| 时区（可选，字符串） | IANA 时区标识符，例如 America/Los_Angeles。此屏幕上每个页面可见性规则均在此时区评估。更改它会重新生成清单版本。分配了使用页面可见性的播放列表的屏幕必须有此项。minLength：1 maxLength：64 |
| wall（可选，内联） | 屏幕的视频墙；null 清除。设置时需要声明 display.wall 主机功能的播放器，否则返回 409 wall_unsupported。更改时重新生成清单版本。 |
| 标签（可选，ScreenTags） | 设备组选择器标签，0 到 16 个唯一且精确的标签，每个标签符合媒体标签语法。在 ScreenPatch 中，数组替换整个集合，空数组则清空；重复或格式错误的标签为 invalid_request。更改标签会提升屏幕版本（If-Match 保护），并附加 screen.updated，详情见 details.tags；不会更改清单版本。 标签永远不会出现在运行时清单中，也不会用于授权。 |
| fields（可选，inline） | 合并到屏幕自身的值中，例如门店编号或区域：字符串表示设置字段，null 表示移除该字段，值为 null 的 fields 会清除所有字段。名称为 1 到 32 个小写字母、数字或下划线；值在去除首尾空白后为 1 到 200 个字符；每个屏幕最多有 32 个字段。 更改字段会为显示播放列表的屏幕重新生成清单修订号。卡片放置项通过 {screen.field.NAME} 占位符读取这些字段。 |
| location（可选，inline） | 屏幕所在的位置；null 表示清除。更改它会为显示播放列表的屏幕重新生成清单修订号。卡片放置项通过 {screen.location} 占位符读取它。 |
| log_level（可选，内联） | 屏幕的播放器生成的最低日志级别：低于它的行不会写入，错误行始终会生成；null 会清除它（播放器的默认值）。更改它会重新生成清单修订，清单以 verbosity.logLevel 携带它。 |
| toast_level（可选，内联） | 屏幕的播放器显示的最低提示级别：低于它不显示任何提示，错误提示始终显示；null 会清除它（显示所有提示）。更改它会重新生成清单修订，清单以 verbosity.toastLevel 携带它。 |
| display（可选，内联） | 显示器的空闲变暗和亮度设置（display.idle、display.brightness）。你发送的成员会替换它，null 会清除它，省略的成员保持不变；display 为 null 会同时清除两者。更改其中任何一项都会重新生成显示播放列表的屏幕的清单修订，清单在根成员 display 中携带它们。 在受保护的屏幕上，会返回 protected_target。 |
| kiosk（可选，内联） | 自助终端锁定（kiosk.lock）。lock true 将播放器固定在屏幕上；false 或 null 则解除固定。更改它会重新生成显示播放列表的屏幕的清单修订，清单以根成员 kiosk 携带它。 |
请求模板和响应
curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 202 | 写入成为审核，等待人员批准（docs/reviews.md），适用于提议权限，或者在任何访问级别下涉及受保护屏幕文件夹中的屏幕时，由第二位审批人决定（docs/screen-scope.md）。人员在控制台的 review.url 处批准、驳回或要求更改。 使用相同 Idempotency-Key 的重放会返回相同的响应体。 | ReviewPending（application/json） |
| 200 | 屏幕 | 屏幕（application/json） |
| 402 | feature_not_in_plan — 视频墙属于 Plus：设置屏幕自身之外的视频墙需要它，在每个计划中，null 都可将其清除。该问题指明功能、项目的计划和 required_plan。 | 问题 (application/problem+json) |
| 403 | outside_screen_scope，同 OutsideScreenScope；或 approver_required - 不能审批审核的、限定屏幕范围的成员不能更改屏幕播放什么或何时播放（docs/screen-scope.md）。 | 问题 (application/problem+json) |
| 409 | protected_target - 此更改涉及受保护屏幕文件夹中的屏幕，且没有审核表单（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) |
删除屏幕
软删除符合条件的屏幕并立即撤销其 cookie 凭证和运行时授权。普通读取随后返回 not_found；墓碑行至少保留 90 天后清理。If-Match 保护修订，Idempotency-Key 重放结果。
原生的、绑定身份的屏幕返回 screen_archive_required：请使用归档来保留该绑定；已归档的绑定身份屏幕保持归档状态（同一问题，并如此说明）。此路由不授予管理性的紧急权限来释放原生注册。受保护屏幕文件夹中的屏幕为 protected_target（409）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求模板和响应
curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 204 | 屏幕已软删除；其墓碑至少保留 90 天。 | 无正文 |
| 404 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
| 409 | 原生的、绑定身份的屏幕返回 screen_archive_required；或当屏幕位于受保护屏幕文件夹中时返回 protected_target（docs/screen-scope.md）。 | 问题 (application/problem+json) |
| 412 | revision_conflict — If-Match 已过期；错误的 current_revision 包含当前版本。 | 问题 (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) |
补丁屏幕标签
已登录用户设置屏幕的标签。tags 是完整的新集合：空数组表示清除，格式错误或重复的标签在 tags[i] 处为 invalid_request。
这是仪表盘会话中标签变更 updateScreen：屏幕版本递增 1，screen.updated 携带 details.tags 和执行者，清单版本不变。pairing_pending 的活动或归档屏幕均接受。
请求体没有其他成员：会话使用 patchScreenName 重命名屏幕，使用 patchScreenPlaylist 为其分配播放列表，但不能更改其时区。If-Match 携带屏幕修订版本且为必需（缺失时返回 invalid_request，过时时返回 revision_conflict）。
仅限控制台会话；智能体用 updateScreen 或 set_tags、add_tags、remove_tags 设备组操作更改标签。带 tag 的 listScreens 按新标签找到该屏幕。在受保护的屏幕上，更改为 protected_target（409）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| id | 路径 | 必填 | |
| If-Match | header | 必填 | 屏幕当前版本，带引号或无引号（最后读取的 ETag）。过时版本为 revision_conflict 与 current_revision。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| 标签（必填，ScreenTags） | 设备组选择器标签，0 到 16 个唯一且精确的标签，每个标签符合媒体标签语法。在 ScreenPatch 中，数组替换整个集合，空数组则清空；重复或格式错误的标签为 invalid_request。更改标签会提升屏幕版本（If-Match 保护），并附加 screen.updated，详情见 details.tags；不会更改清单版本。 标签永远不会出现在运行时清单中，也不会用于授权。 |
请求模板和响应
curl --request PATCH --cookie cookies.txt --cookie-jar cookies.txt --header 'If-Match: "REVISION"' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID/tags'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 当前存储的屏幕；ETag 表示其修订版本。 | 屏幕（application/json）；头部：ETag |
| 412 | revision_conflict — If-Match 已过期；错误的 current_revision 包含当前版本。 | 问题 (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) |
部分更新屏幕字段
已登录成员通过 updateScreen 的合并补丁更改屏幕的字段：字符串值设置字段，null 移除字段，fields 为 null 则清除所有字段。被拒绝的名称或值，或第 33 个字段，会在 fields 或 fields.NAME 处返回 invalid_request。
屏幕修订版本递增 1，显示播放列表的屏幕会获得新的清单修订版本，事件携带 details.fields，并以该成员为操作者。请求体没有其他成员。If-Match 携带屏幕修订版本，且为必需（缺失时返回 invalid_request，过期时返回 revision_conflict）。
仅限控制台会话；智能体使用 PATCH /api/screens/{id}（updateScreen）。在受保护的屏幕上，更改为 protected_target（409）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| id | 路径 | 必填 | |
| If-Match | header | 必填 | 屏幕当前版本，带引号或无引号（最后读取的 ETag）。过时版本为 revision_conflict 与 current_revision。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| fields（必填，内联） | 合并到屏幕自身的值中，例如门店编号或区域：字符串表示设置字段，null 表示移除该字段，值为 null 的 fields 会清除所有字段。名称为 1 到 32 个小写字母、数字或下划线；值在去除首尾空白后为 1 到 200 个字符；每个屏幕最多有 32 个字段。 |
请求模板和响应
curl --request PATCH --cookie cookies.txt --cookie-jar cookies.txt --header 'If-Match: "REVISION"' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID/fields'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 当前存储的屏幕；ETag 表示其修订版本。 | 屏幕（application/json）；头部：ETag |
| 412 | revision_conflict — If-Match 已过期；错误的 current_revision 包含当前版本。 | 问题 (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) |
部分更新屏幕位置
已登录成员通过 updateScreen 的 location 设置或清除屏幕所在位置：包含 latitude、longitude 以及可选 name 和 address 的对象会整体替换该位置，null 则清除。缺少或类型错误的成员、超出范围的坐标、超过 40 个字符的 name 或超过 200 个字符的 address，会在 location.MEMBER 处返回 invalid_request。
屏幕修订版本递增 1，显示播放列表的屏幕会获得新的清单修订版本，事件携带 details.location，并以该成员为操作者。请求体没有其他成员。If-Match 携带屏幕修订版本，且为必需（缺失时返回 invalid_request，过期时返回 revision_conflict）。
仅限控制台会话；智能体使用 PATCH /api/screens/{id}（updateScreen）。在受保护的屏幕上，更改为 protected_target（409）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| id | 路径 | 必填 | |
| If-Match | header | 必填 | 屏幕当前版本，带引号或无引号（最后读取的 ETag）。过时版本为 revision_conflict 与 current_revision。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| location（必填，内联） | 屏幕所在位置：该对象会整体替换位置，null 则清除。 |
请求模板和响应
curl --request PATCH --cookie cookies.txt --cookie-jar cookies.txt --header 'If-Match: "REVISION"' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID/location'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 当前存储的屏幕；ETag 表示其修订版本。 | 屏幕（application/json）；头部：ETag |
| 412 | revision_conflict — If-Match 已过期；错误的 current_revision 包含当前版本。 | 问题 (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) |
修改屏幕的详细程度
已登录的人通过 updateScreen 的 log_level（debug、info、warn、error）和 toast_level（info、alert、error）设置或清除屏幕的日志级别和提示级别：字符串设置级别，null 清除，省略的成员保持不变。其他任何值，在 log_level 或 toast_level 上都是 invalid_request。
屏幕修订加一，显示播放列表的屏幕会得到新的清单修订，播放器从清单的 verbosity 成员读取这些级别。请求体至少包含两个成员之一，且不含其他成员。If-Match 携带屏幕修订，且为必填（缺少时为 invalid_request，过期时为 revision_conflict）。
仅限控制台会话；智能体使用 PATCH /api/screens/{id}（updateScreen）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| id | 路径 | 必填 | |
| If-Match | header | 必填 | 屏幕当前版本，带引号或无引号（最后读取的 ETag）。过时版本为 revision_conflict 与 current_revision。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| log_level（可选，内联） | 屏幕的播放器生成的最低日志级别；错误行始终会生成。null 会清除它（播放器的默认值）。更改它会重新生成清单修订。 |
| toast_level（可选，内联） | 屏幕的播放器显示的最低提示级别；错误提示始终显示。null 会清除它（显示所有提示）。更改它会重新生成清单修订。 |
请求模板和响应
curl --request PATCH --cookie cookies.txt --cookie-jar cookies.txt --header 'If-Match: "REVISION"' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID/verbosity'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 当前存储的屏幕；ETag 表示其修订版本。 | 屏幕（application/json）；头部：ETag |
| 412 | revision_conflict — If-Match 已过期；错误的 current_revision 包含当前版本。 | 问题 (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) |
修改屏幕设备设置
已登录的人员可通过 updateScreen 的 display 和 kiosk 成员设置或清除屏幕的空闲变暗和亮度设置及其自助终端锁定：display.idle {after_s 30 to 86400, wake touch, presence or both}、display.brightness {mode auto or fixed} 和 kiosk.lock。
你发送的成员会替换它，null 会清除它，省略的成员保持原样；display 为 null 会同时清除两者。超出范围或类型错误的值会返回 invalid_request，并指明路径（display.idle.after_s）。
屏幕修订版本加一，显示播放列表的屏幕会获得新的清单修订，播放器从清单成员 display（idle、brightness）和 kiosk 中读取这些设置。请求体至少包含 display 和 kiosk 之一，不含其他成员。
If-Match 携带屏幕修订版本，且为必填（缺失时为 invalid_request，过期时为 revision_conflict）。在受保护的屏幕上，对 display 的更改会返回 protected_target (409)。仅限控制台会话；智能体使用 PATCH /api/screens/{id}（updateScreen）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| id | 路径 | 必填 | |
| If-Match | header | 必填 | 屏幕当前版本，带引号或无引号（最后读取的 ETag）。过时版本为 revision_conflict 与 current_revision。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| display（可选，内联） | display.idle 和 display.brightness，与 updateScreen 的 display 相同：你发送的成员会替换它，null 会清除它，省略的成员保持不变；display 为 null 会同时清除两者。更改其中任何一项都会重新生成显示播放列表的屏幕的清单修订。在受保护的屏幕上，会返回 protected_target。 |
| kiosk（可选，内联） | kiosk.lock，与 updateScreen 的 kiosk 相同：lock true 将播放器固定在屏幕上，false 或 null 则解除固定。 |
请求模板和响应
curl --request PATCH --cookie cookies.txt --cookie-jar cookies.txt --header 'If-Match: "REVISION"' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID/device-settings'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 当前存储的屏幕；ETag 表示其修订版本。 | 屏幕（application/json）；头部：ETag |
| 412 | revision_conflict — If-Match 已过期；错误的 current_revision 包含当前版本。 | 问题 (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) |
修改屏幕名称
已登录的人员使用 updateScreen 的 name 重命名屏幕。名称会去除首尾空白，必须为 1 到 120 个字符且不含控制字符，否则在 name 处返回 invalid_request（缺少名称或名称为 null 时同样如此）。
屏幕修订版本加一，事件为 screen.manifest_changed，发送给该屏幕，操作者为该人员；清单修订版本保持不变，因此播放不受影响，Player 会根据变化后的 ETag 刷新名称。重命名为相同名称仍会推进修订版本并追加 screen.updated。请求体没有其他成员。
If-Match 携带屏幕修订版本且为必需（缺失时返回 invalid_request，过时时返回 revision_conflict）。仅限控制台会话；智能体使用 PATCH /api/screens/{id}（updateScreen）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| id | 路径 | 必填 | |
| If-Match | header | 必填 | 屏幕当前版本，带引号或无引号（最后读取的 ETag）。过时版本为 revision_conflict 与 current_revision。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| 名称（必填，字符串） | 屏幕名称，已去除首尾空白；去除后为 1 到 120 个字符，不含控制字符。minLength: 1 maxLength: 120 |
请求模板和响应
curl --request PATCH --cookie cookies.txt --cookie-jar cookies.txt --header 'If-Match: "REVISION"' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID/name'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 当前存储的屏幕；ETag 表示其修订版本。 | 屏幕（application/json）；头部：ETag |
| 412 | revision_conflict — If-Match 已过期；错误的 current_revision 包含当前版本。 | 问题 (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) |
修改屏幕播放列表
已登录的用户通过 updateScreen 的分配来指定屏幕的播放列表：该播放列表必须属于该项目且有已批准的版本（playlist_not_approved），带格式的播放列表需要视频墙形状相同的屏幕（409 playlist_format_mismatch）。
The screen revision moves by one and the manifest is reissued from the new playlist; while a takeover, a campaign or a schedule entry is effective the playlist becomes the default behind it. Events carry the person as their actor.
The write is live, so only the project owner or a member who can approve makes it (approver_required); a staff session needs its write lease. The body has no other member. If-Match carries the screen revision and is required (invalid_request when absent, revision_conflict when stale).
仅限控制台会话；智能体使用 PATCH /api/screens/{id}（updateScreen）。在受保护的屏幕上，审批人的分配是由第二位审批人决定的审核（202 pending_review）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| id | 路径 | 必填 | |
| If-Match | header | 必填 | 屏幕当前版本，带引号或无引号（最后读取的 ETag）。过时版本为 revision_conflict 与 current_revision。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| playlist_id（必填，内联） | 屏幕的默认播放列表；null 清除其自身的分配。接管、活动、排程条目或从文件夹继承的默认值仍可显示内容；否则已配对的 Player 显示待机画面。 |
请求模板和响应
curl --request PATCH --cookie cookies.txt --cookie-jar cookies.txt --header 'If-Match: "REVISION"' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID/playlist'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 当前存储的屏幕；ETag 表示其修订版本。 | 屏幕（application/json）；头部：ETag |
| 412 | revision_conflict — If-Match 已过期；错误的 current_revision 包含当前版本。 | 问题 (application/problem+json) |
| 403 | outside_screen_scope，同 OutsideScreenScope；或 approver_required - 不能审批审核的、限定屏幕范围的成员不能更改屏幕播放什么或何时播放（docs/screen-scope.md）。 | 问题 (application/problem+json) |
| 202 | 写入成为审核，等待人员批准（docs/reviews.md），适用于提议权限，或者在任何访问级别下涉及受保护屏幕文件夹中的屏幕时，由第二位审批人决定（docs/screen-scope.md）。人员在控制台的 review.url 处批准、驳回或要求更改。 使用相同 Idempotency-Key 的重放会返回相同的响应体。 | ReviewPending（application/json） |
| 默认 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
轮换屏幕公钥 ID
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求模板和响应
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/public-id/rotate'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 公共 URL 凭证已轮换；播放器公钥注册保留。每个运行时会话因新的 content_access_generation 失效，实时期望和活动授权在该版本针对未变更的清单修订重新发放，因此重新生成会话的配对播放器继续授权其已显示的内容。 | 屏幕（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) |
获取屏幕链接
屏幕的链接，即在不保留存储的浏览器（如 vMix 或 OBS 的浏览器源）中打开此屏幕的 Player URL。url 是一种凭据：在有效 Manage 以下为空，且 url_redacted 为 true。需要 screens 能力本身。屏幕没有链接时返回 screen_link_not_found。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/screens/RESOURCE_ID/link'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 屏幕的链接。 | ScreenLink（application/json）；头部：Cache-Control |
| 404 | 屏幕不在项目内时返回 not_found；屏幕没有链接时返回 screen_link_not_found。 | 问题 (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) |
创建屏幕链接
签发屏幕的链接并返回其 url，替换屏幕已有的任何链接（replaced 表明是否替换）。屏幕必须处于活动状态，并已用其配对码配对过一次（尚无已配对 Player 时为 resource_conflict，已归档时为 screen_archived）。
替换会递增屏幕的 content_access_generation 并重新签发其有效授权，与公开 ID 轮换相同，因此旧链接打开的每个会话都会立即结束；绑定密钥的该屏幕 Player 会自行重新签发会话。首个链接不会递增任何内容。链接不是设备绑定：屏幕的密钥不受影响。
追加 screen.link_changed（details.action 为 created 或 replaced）。If-Match 为可选。url 是一种凭据：请只在一处打开它。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求模板和响应
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/screens/RESOURCE_ID/link'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 屏幕的新链接。 | ScreenLink（application/json）；头部：ETag，Cache-Control |
| 409 | resource_conflict（尚无已配对的 Player）或 screen_archived。 | 问题 (application/problem+json) |
| 412 | revision_conflict — If-Match 已过期；错误的 current_revision 包含当前版本。 | 问题 (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) |
删除屏幕链接
关闭屏幕的链接。旧 url 立即失效，它打开的每个会话都会结束，与替换时相同。屏幕没有链接时操作成功且不更改任何内容。链接存在时追加 screen.link_changed（details.action 为 deleted）。If-Match 为可选。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求模板和响应
curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/screens/RESOURCE_ID/link'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 204 | 已删除，或原本没有。 | 无正文 |
| 412 | revision_conflict。 | 问题 (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) |
确认屏幕恢复
确认待处理屏幕恢复。启动本地配对时，若主机duid或序列号与恰好一个项目中恰好一个屏幕完全匹配，且绑定了不同的公钥，则在该屏幕记录一个提议（Screen.recovery_pending，项目事件screen.recovery_offered）。
主机对象是提示，绝非凭证：只有所属项目调用此路由时才会重新绑定。DUID 可被面板上任何应用读取，因此报价是钓鱼攻击面。
通过活跃检测（绑定密钥最近十分钟内活跃则不报价）、每屏幕每滚动小时最多三次报价限制及同项目确认来缓解。recovery_pending.host 和事件包含发起设备的平台、型号、固件和制造商，便于操作员确认显示器信息后确认。
确认完成待处理本地配对到现有屏幕：配对设备照常接收pairing.claimed并用pairing.complete证明持有，新的密钥成为屏幕身份，旧密钥有15分钟宽限期，其运行时会话继续有效且仍可铸造，之后被拒绝。
播放列表、标签、时区、排程和历史记录均被保留。仅限同一项目；其他项目的屏幕显示not_found。If-Match为可选。发出screen.recovered。当无待处理项时为recovery_not_offered，配对会话过期时为recovery_expired，标识符附加于多个位置时为recovery_ambiguous。
问题响应绝不回显设备标识符。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则创建或覆盖键；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求模板和响应
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/recovery/confirm'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 屏幕已恢复到配对设备的密钥；响应携带当前 ETag。 | 屏幕（application/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) |
| 410 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
| 412 | 稳定的 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) |
替换屏幕
将配对为项目中另一个屏幕的设备移到此屏幕上，并归档那个屏幕，这样此屏幕在新硬件上保留其名称、标签、时区、播放列表、排程、接管、显示器排程与覆盖、视频墙、评论和历史记录。
设备的公钥（或浏览器凭证）现在可打开此屏幕，该屏幕采用替换设备的主机和播放器；其健康状态、状态、存储、观测数据和排队的命令重新开始。此屏幕原先持有的密钥随恢复宽限窗口退役：它在十五分钟内仍可铸造会话，之后被拒绝（key_retired）。不会解除任何绑定。
被替换的屏幕会被归档，archive_reason 为 replaced，且不保留绑定或主机。两个屏幕都会递增 content_access_generation，因此二者持有的所有会话都会结束；设备会收到发给其原屏幕的 player.reload（details.reason 为 replaced，有效期 24 小时），并以此屏幕的身份重新铸造会话。
两个屏幕都必须处于活动状态且已配对播放器（pairing_pending 屏幕或未配对的替换屏幕返回 resource_conflict，已归档屏幕返回 screen_archived）；with 必须指明项目中的另一个屏幕（否则返回 invalid_request；其他项目的屏幕返回 not_found）；带视频墙的屏幕需要声明了 display.wall 的替换播放器（wall_unsupported）。
If-Match 可选，用于检查此屏幕的修订版本。发出项目事件 screen.replaced（details.from_screen_id），不发出 screen.archived。使用相同 Idempotency-Key 的完全重试在 24 小时内返回相同响应。
限定屏幕范围的调用方（docs/screen-scope.md）需要屏幕和 with 都在其范围内（outside_screen_scope；不会归档任何内容）。任一屏幕受保护的替换为 protected_target。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则创建或覆盖键；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| with（必填，字符串） | 同一项目中另一个屏幕的 id，其已配对设备将接替路径中的屏幕。它必须是另一个已配对播放器的活动屏幕；它会被归档，archive_reason 为 replaced。minLength：1 maxLength：256 |
请求模板和响应
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/screens/RESOURCE_ID/replace'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 设备现在打开的是此屏幕；响应是带有新修订版本和当前 ETag 的此屏幕。 | 屏幕（application/json） |
| 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 | resource_conflict、screen_archived、wall_unsupported；或当任一屏幕位于受保护屏幕文件夹中时返回 protected_target。 | 问题 (application/problem+json) |
| 412 | 稳定的 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) |
归档屏幕
将屏幕从默认列表中隐藏，并在实体屏幕上显示“屏幕已归档”状态。不会解除播放器公钥的绑定。释放 screen_count 配额。取消屏幕队列中的 reboot、clear_cache、restart_app 和 update 命令；队列中的 reload 仍会送达。位于受保护屏幕文件夹中的屏幕会返回 protected_target (409)。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求模板和响应
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/archive'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 屏幕已归档。 | 屏幕（application/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 | 当屏幕位于受保护屏幕文件夹中时返回 protected_target（docs/screen-scope.md；通过审核清除该文件夹的保护，完成更改，再次保护），或该操作的其他冲突。 | 问题 (application/problem+json) |
| 412 | 稳定的 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) |
取消归档屏幕
恢复归档的屏幕至默认列表并重新生成正常清单。必须通过屏幕入场审核。不更改绑定的公钥。
清单再次发布，屏幕播放列表如同任务分配时被检查；引用缺失或未准备内容的播放列表返回 resource_conflict 并指明播放列表，屏幕保持归档状态直到播放列表修复。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求模板和响应
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/unarchive'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 屏幕已取消归档。 | 屏幕（application/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) |
| 412 | 稳定的 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) |
| 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) |
重新加载屏幕
请求指定的活动或归档屏幕的播放器重新加载（docs/player-compatibility.md §6.3）。可选的请求体设置 expires_in_s，即重新加载保持可执行的时长（60 到 86400 秒，默认 86400，即 24 小时）；超出范围的值返回 invalid_request 并指明 expires_in_s。
在线屏幕会立即收到持久的每屏 player.reload 事件（details.reason 为 project、新的 reload_id、spread_s 为 0、expires_at），该重新加载在 Screen.commands 中记录为 sent。
离线屏幕将重新加载保持为 queued 且不产生事件；当后端在 expires_at 之前处理该屏幕的下一次上线状态转换时，会追加该事件（reload_id 和 expires_at 相同），命令变为 sent。较新的重新加载会取代仍在排队的较旧重新加载。
超过 expires_at 的排队重新加载读取时显示为 expired，POST /api/screens/{id}/commands/{command_id}/cancel 可取消仍在排队的重新加载。运行时 SSE 流会把该事件转发给每个运行时会话。播放器会忽略距其上次执行的重新加载不到十分钟的重新加载。
网页播放器在下一个页面边界重新加载；原生播放器重新铸造会话、重新获取其清单并检查更新。屏幕修订版本不变。If-Match 和 Idempotency-Key 可选，与归档相同；使用相同 Idempotency-Key 的完全重试在 24 小时内返回原始响应体。
pairing_pending 屏幕尚无播放器，返回 resource_conflict。屏幕消息免于 1 额度 API 计量。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| expires_in_s（可选，整数） | 命令保持可执行的时长，自请求起算，单位为秒。排队的命令只会在过期前发送；播放器会忽略 expires_at 之后的命令。默认：86400 最小值：60 最大值：86400 |
请求模板和响应
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/screens/RESOURCE_ID/reload'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 202 | 已接受。重新加载发送到在线屏幕的播放器时 state 为 sent，等待屏幕上线时为 queued。重新加载在 expires_at 之前保持可执行。ETag 是未更改的屏幕修订版本。 | ScreenReloadAccepted（application/json）；头部：Cache-Control，ETag，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) |
| 412 | 稳定的 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) |
获取屏幕播放列表排程
返回屏幕服务器评估的播放列表计划：按优先级顺序的条目（屏幕无条目时为空）、updated_at及其当前生成的effective_playlist。ETag为屏幕修订。pairing_pending、活动和归档屏幕可读；其他项目的屏幕为not_found。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/playlist-schedule'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 播放列表排程。 | ScreenPlaylistScheduleView（application/json）；头部：ETag |
| 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) |
| 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) |
设置屏幕播放列表排程
替换屏幕的播放列表排程。服务器评估排程，播放器不评估：第一个规则匹配屏幕本地时间（screenrig.schedule/v1窗口及from/until，含夏令时和跨午夜窗口）的条目为有效播放列表；无匹配时使用分配的playlist_id。
接管仍胜过所有条目。屏幕必须有时区和分配的默认 playlist_id（否则 invalid_request），确保始终有回退。
每个引用的播放列表都像分配一样针对屏幕进行验证（拥有、准备好的引用、页面可见性需要时区，且带格式的播放列表需要屏幕墙面形状相同，否则返回 409 playlist_format_mismatch），因此屏幕拒绝的播放列表此处也被拒绝；该检查会写入播放列表文档，因此并发删除播放列表会冲突而非竞态。
如果计划播放列表后续无法显示（例如内容无法解析），评估时跳过其条目，并追加 screen.playlist_unavailable（警告，详情包含 playlist_id、entry_ids、代码）。
当有效播放列表更改时，从中重新生成清单，并向播放器发送 screen.manifest_changed 信号，如同分配一样，并附加 screen.playlist_switched。屏幕版本号增加（受 If-Match 保护），并附加 screen.updated，包含 details.playlist_schedule_entries。
归档屏幕响应 screen_archived；其排程、接管和默认仍被引用（阻止播放列表删除），取消归档时重新解析。速率限制：screen-control-org 600，screen-control-screen 20，screen-control-ip 60 每分钟，与 DELETE 和接管路由共享。
在受保护的屏幕上，排程是由第二位审批人决定的审核（202 pending_review），在任何访问级别都是如此。带有 paused true 的新条目（草稿）属于排程变更控制，Enterprise 计划包含该功能；计划不含该功能的项目会被拒绝并返回 feature_not_in_plan（402）。
已存储的条目可以保持暂停，暂停已存储的条目在每个计划中都开放。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| Screenrig-Review-Note | header | 可选 | 审查类写入时的可选提议者备注，以百分号编码的 UTF-8 发送（JavaScript 的 encodeURIComponent 写入内容）。服务器进行百分号解码（无效转义为 400 invalid_request）；解码后的备注为纯文本，修剪后最多 280 字符，无控制字符（否则 400 invalid_request）。 写入成为审核时存储；实时应用时忽略。 |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| 条目（必填，数组） | 优先顺序：第一个匹配条目获胜。DELETE 清除计划。 |
请求模板和响应
curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/playlist-schedule'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 202 | 写入在提议访问下变为审核，等待人员批准（docs/reviews.md）。Idempotency-Key 重放响应相同主体。 | ReviewPending（application/json）；头部：RateLimit-Policy，RateLimit |
| 200 | 带有存储的排程及其 effective_playlist 的屏幕。ETag 是新的修订版本。 | 屏幕（application/json）；头部：ETag，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 — 排程变更控制属于 Enterprise 计划；该问题指明功能、账户所在的计划和 required_plan。将播放列表锁定到视频墙第 2 块或更靠后显示器（displays）的条目，若不同于屏幕已存储的条目，则属于 Plus。该问题指明功能、项目的计划和 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) |
| 409 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
| 412 | 稳定的 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) |
清除屏幕播放列表排程
移除屏幕的播放列表排程；此后由接管生效，没有接管则由生效中的广告活动生效，再没有则由已分配的播放列表生效，清单变更信号的发送方式与 PUT 相同。没有排程的屏幕会返回 200 且保持不变（不递增修订号，也不产生事件）。
在受保护的屏幕上，清除排程是由第二位审批人决定的审核（202 pending_review），在任何访问级别都是如此。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| Screenrig-Review-Note | header | 可选 | 审查类写入时的可选提议者备注，以百分号编码的 UTF-8 发送（JavaScript 的 encodeURIComponent 写入内容）。服务器进行百分号解码（无效转义为 400 invalid_request）；解码后的备注为纯文本，修剪后最多 280 字符，无控制字符（否则 400 invalid_request）。 写入成为审核时存储；实时应用时忽略。 |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求模板和响应
curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/playlist-schedule'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 202 | 写入在提议访问下变为审核，等待人员批准（docs/reviews.md）。Idempotency-Key 重放响应相同主体。 | ReviewPending（application/json）；头部：RateLimit-Policy，RateLimit |
| 200 | 无播放列表排程的屏幕。 | 屏幕（application/json）；头部：ETag，RateLimit-Policy，RateLimit |
| 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) |
| 412 | 稳定的 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) |
预览屏幕播放列表排程
用 entries 替换屏幕播放列表排程会更改什么（不实际执行）。
条目按 PUT 的检查方式检查（语法、屏幕的时区和显示器、默认播放列表，以及每个播放列表作为分配：它存在、有已批准的版本、适合屏幕的视频墙及其覆盖的区域，且其引用可解析），因此预览会拒绝 PUT 所拒绝的内容。
返回屏幕会在其堆栈上获得或失去其排程的哪些层级（已暂停的条目不在任何堆栈上，因此发布它会获得该层级），以及屏幕的排程日历，包括现状（before）和之后的状态（after），覆盖 from 到 to（默认：从现在起一周；最多 93 天）。读取访问：不写入任何内容。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 |
请求主体字段
| 字段 | 描述 |
|---|---|
| 条目（必填，数组） | |
| from (可选, string) | 日历的开始时间；默认为现在。format: "date-time" |
| to（可选，字符串） | 日历的结束时间；默认为 from 之后一周，最晚为 from 之后 93 天。format: "date-time" |
请求模板和响应
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/playlist-schedule/preview'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 预览结果。 | SchedulePreview（application/json） |
| 400 | 稳定的 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) |
| 默认 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
列出屏幕播放列表排程修订
屏幕播放列表排程的修订，最新的在前：每次写入（PUT、DELETE、恢复、排程导入）后存储的完整 entries 列表，附带变更类型和变更者。修订以写入时屏幕的修订编号，因此屏幕以其他方式变更时，编号会出现空缺。
历史尚无记录行的屏幕按其当前状态列出其排程，change 为 baseline。修订随屏幕的清除一并删除。每页最多 50 条；还有更多时返回 next_cursor，最后一页为 null。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| after | 查询 | 可选 | 同一列表上一页的 next_cursor，使用相同过滤条件。省略时从最新行开始。非此类游标值为 invalid_request。 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/screens/RESOURCE_ID/playlist-schedule/revisions'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 屏幕的排程修订，最新的在前。 | ScreenScheduleRevisionList（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) |
恢复屏幕播放列表排程修订
将更早修订的条目放回为屏幕的排程：与使用这些条目执行 PUT /api/screens/{id}/playlist-schedule 相同的写入（若该修订没有条目则为 DELETE），并按现在的标准检查（此后被删除的播放列表会使其被拒绝），因此在提议访问下，恢复会变成与 PUT 所变成的相同的 screen_change 审核。
If-Match 是必需的，并指明屏幕的当前修订。更早的修订保持原样。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| 修订 | 路径 | 必填 | 记录的一个修订，编号与其修订列表一致。 |
| Screenrig-Review-Note | header | 可选 | 审查类写入时的可选提议者备注，以百分号编码的 UTF-8 发送（JavaScript 的 encodeURIComponent 写入内容）。服务器进行百分号解码（无效转义为 400 invalid_request）；解码后的备注为纯文本，修剪后最多 280 字符，无控制字符（否则 400 invalid_request）。 写入成为审核时存储；实时应用时忽略。 |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求模板和响应
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/screens/RESOURCE_ID/playlist-schedule/revisions/REVISION/restore'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 202 | 写入在提议访问下变为审核，等待人员批准（docs/reviews.md）。Idempotency-Key 重放响应相同主体。 | ReviewPending（application/json）；头部：RateLimit-Policy，RateLimit |
| 200 | 带有已恢复排程及其 effective_playlist 的屏幕。ETag 是新的修订。 | 屏幕（application/json）；头部：ETag，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) |
| 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) |
| 412 | 稳定的 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) |
设置屏幕接管
以一个播放列表接管屏幕，优先于广告活动、该屏幕的播放列表排程和已分配的播放列表，直到 until 指定的时间（RFC 3339，必须严格晚于当前时间，且最多在 7 天之后）；若 until 为 null 或省略，则直到接管被清除。reason 为可选项，最多 120 个字符。
屏幕必须已分配默认的 playlist_id（否则返回 invalid_request）。新的接管会替换先前的接管（screen.takeover_ended，reason 为 replaced；若先前的接管已经结束，则为 expired）。
播放列表会按分配进行校验，包括其格式（带格式的播放列表要求屏幕的视频墙具有相同的形状，否则返回 409 playlist_format_mismatch）。若接管所用的播放列表之后无法显示，该接管会结束（screen.takeover_ended，reason 为 playlist_deleted 或 playlist_unavailable）。
追加 screen.takeover_started；当生效的播放列表发生变化时，还会追加 screen.playlist_switched 以及 Player 的 screen.manifest_changed。until 到期后，边界 worker 会在 60 秒内结束接管（screen.takeover_ended，reason 为 expired）。屏幕修订号会递增（受 If-Match 保护）。
已归档的屏幕返回 screen_archived；取消归档会先重新解析，因此归档期间已结束的接管会在此时结束。适用与排程路由相同的屏幕控制速率限制。在受保护的屏幕上，接管是由第二位审批人决定的审核（202 pending_review），在任何访问级别都是如此。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| Screenrig-Review-Note | header | 可选 | 审查类写入时的可选提议者备注，以百分号编码的 UTF-8 发送（JavaScript 的 encodeURIComponent 写入内容）。服务器进行百分号解码（无效转义为 400 invalid_request）；解码后的备注为纯文本，修剪后最多 280 字符，无控制字符（否则 400 invalid_request）。 写入成为审核时存储；实时应用时忽略。 |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| playlist_id（必填，字符串） | minLength：1 |
| 直到（可选，内联） | 严格未来，最多提前 7 天。空值或省略保持接管状态，直到清除。 |
| 原因（可选，字符串） | 接管及其事件中携带的操作员备注。无控制字符。maxLength：120 |
请求模板和响应
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/takeover'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 202 | 写入在提议访问下变为审核，等待人员批准（docs/reviews.md）。Idempotency-Key 重放响应相同主体。 | ReviewPending（application/json）；头部：RateLimit-Policy，RateLimit |
| 200 | 带有接管及其 effective_playlist 的屏幕。ETag 是新的修订版本。 | 屏幕（application/json）；头部：ETag，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) |
| 412 | 稳定的 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) |
清除屏幕接管
结束接管（screen.takeover_ended，原因 cleared）；计划或分配的播放列表生效并发出相同清单信号。无接管的屏幕返回 200 不变（无版本提升，无事件）。
已归档屏幕的接管也会被清除：屏幕保持归档状态，其 Player 不会收到信号，取消归档时再确定实际生效的播放列表。对于受保护的屏幕，无论访问级别如何，清除接管都需要另一位具有审批权限的人员审核 (202 pending_review)。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| Screenrig-Review-Note | header | 可选 | 审查类写入时的可选提议者备注，以百分号编码的 UTF-8 发送（JavaScript 的 encodeURIComponent 写入内容）。服务器进行百分号解码（无效转义为 400 invalid_request）；解码后的备注为纯文本，修剪后最多 280 字符，无控制字符（否则 400 invalid_request）。 写入成为审核时存储；实时应用时忽略。 |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求模板和响应
curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/takeover'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 202 | 写入在提议访问下变为审核，等待人员批准（docs/reviews.md）。Idempotency-Key 重放响应相同主体。 | ReviewPending（application/json）；头部：RateLimit-Policy，RateLimit |
| 200 | 无接管的屏幕。 | 屏幕（application/json）；头部：ETag，RateLimit-Policy，RateLimit |
| 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) |
| 412 | 稳定的 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) |
开始标签页共享
在屏幕上显示浏览器标签页。创建临时播放列表，每个标签页对应一个1920x1080的全画布iframe页面，并以此接管所有目标屏幕（原因“Shared browser tab”），持续至until，最多24小时后（默认值）。
目标是screen_ids、folder_ids及其子文件夹中的所有活动屏幕，以及带有任意tags的所有活动屏幕的并集；包含离线屏幕，恢复后显示共享。
限定屏幕范围的调用方（docs/screen-scope.md）只能访问范围内的屏幕；范围外的屏幕会被跳过（outside_screen_scope），请求的其他处理规则相同。
只有一个标签页时持续显示到共享结束；多个标签页在各自的duration_s后前进。reload_s重新加载每个页面。qr在右下角添加页面地址的二维码，高度约为画布的14%。cookies是发送方的页面登录信息：静态存储时密封，任何读取、事件、审计条目或修订都不会返回，仅通过正在显示共享的屏幕运行时清单提供（iframe的cookies成员）。无法设置它们的Player会忽略它们，Web Player及委托给它的外壳也会忽略。
无法接管的目标（受保护文件夹、无默认播放列表、已归档、未找到、格式不匹配、范围外或受到限流）列在skipped中，不会导致整个请求失败。正在显示旧共享的屏幕会被新共享接管；没有屏幕显示旧播放列表后将其删除。
如果没有目标被接管，则删除临时播放列表，返回单个目标的问题，或带有原因的409 resource_conflict。warnings列出后端无法嵌入的标签页地址（embedding_blocked：X-Frame-Options或frame-ancestors拒绝Player Web应用），每个地址以3秒预算检查一次；不会阻止共享。
屏幕控制限流按目标屏幕（组织和屏幕）应用，IP 限制每个请求应用一次。每次调用创建新共享，Idempotency-Key 不提供重放。变更立即生效：Propose 访问返回 insufficient_access 拒绝；控制台通道中无法批准审核的成员返回 approver_required 拒绝。
控制台通道使用会话的当前项目（没有项目时为no_project）。请求可来自控制台或Chrome、Firefox扩展来源（chrome-extension://ID、moz-extension://UUID），Sec-Fetch-Site须缺省、为same-origin或none；若存在X-ScreenRig-CSRF标头，须与GET /api/session中的csrf_token一致。
只有此路由、DELETE /api/tab-shares/{id}、POST /api/playlists/{id}/pages和POST /api/screens/{id}/screenshot接受扩展来源。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| 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。 |
请求模板和响应
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/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) |
获取标签页共享
读取共享：结束时间及接管播放列表仍属于它的屏幕（此后被他人接管或已归档的屏幕不列出）。共享已结束、已过期或从未存在时返回404 not_found。限定屏幕范围的调用方只能看到范围内的屏幕。读取不适用扩展来源规则。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/tab-shares/RESOURCE_ID'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 共享及仍在显示它的屏幕。 | TabShareState (application/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) |
| 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) |
停止标签页共享
结束共享：清除接管播放列表仍属于该共享的每个屏幕（发出原因为cleared的screen.takeover_ended，并通过相同清单信号使排期或在无排期时使已分配的播放列表生效），然后删除播放列表。允许操作受保护文件夹中的屏幕。
此后被其他人接管的屏幕保持不变。共享已结束时返回404 not_found，客户端将其视为已结束。每个请求消耗各屏幕控制限制的一个单位。限定屏幕范围的调用方只清除范围内的屏幕。通道、访问规则和扩展来源规则与POST /api/tab-shares相同。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 |
请求模板和响应
curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/tab-shares/RESOURCE_ID'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 已清除接管的屏幕。 | TabShareStopped (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) |
| 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) |
播放屏幕页面
请求屏幕的播放器启动当前播放列表的一页，使下一次截图显示该页，无需等待轮播（docs/player-compatibility.md §6.3.1）。
该页面必须属于屏幕的生效播放列表，即构建其清单所依据的播放列表，依次取自：进行中的接管，否则生效中的广告活动，否则当前的播放列表排程条目，否则已分配的播放列表。不满足时会返回 409 page_not_on_screen，其 detail 会指明该播放列表。
屏幕的主机提示必须声明 play_page 能力，否则返回 409 play_page_unsupported 并且不发送任何内容；请更新播放器。屏幕必须处于活动状态；归档屏幕响应 screen_archived，pairing_pending 屏幕响应 resource_conflict。
追加每屏运行时命令 player.play_page（详情包括 page_id、playlist_id、manifest_revision、expires_at，后者为六十秒后；过期后不投递）。播放器从页面开头开始播放，仿佛轮播已到达该页，并从此继续轮播。屏幕版本不变。
Idempotency-Key 是必需的，与 toast 相同；完全相同的重试会在二十四小时内返回原始响应体。被拒绝的请求、失败的请求和完全相同的重放都不消耗速率限制预算。屏幕消息不计入 1 额度的 API 计量。受保护屏幕文件夹中的屏幕为 protected_target（409）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| Idempotency-Key | header | 必填 |
请求主体字段
| 字段 | 描述 |
|---|---|
| page_id（必填，字符串） | 屏幕当前播放的播放列表页面的 ID（该播放列表页面中的 ID）。minLength：1 maxLength：128 |
请求模板和响应
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/screens/RESOURCE_ID/play-page'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 202 | 已接受。命令在 expires_at 之前可执行。完全幂等的重试返回相同的主体。 | ScreenPlayPageAccepted（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 | 当屏幕位于受保护屏幕文件夹中时返回 protected_target（docs/screen-scope.md；通过审核清除该文件夹的保护，完成更改，再次保护），或该操作的其他冲突。 | 问题 (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) |
标识屏幕
请求屏幕的播放器在其内容之上显示屏幕名称，持续 duration_ms（2000 到 600000，默认 60000），这样站在多块显示器前的人就能分辨某条记录对应的是哪一块（docs/player-compatibility.md §6.3.2）。
追加每屏运行时命令 player.identify（details 含 identify_id、label、screen_id、duration_ms、at，以及 at 之后 60 秒的 expires_at；超过 expires_at 后不再送达）。
播放器在其内容之上绘制全屏覆盖层，屏幕名称非常大，屏幕 id 以小字显示在名称下方，自收到请求起持续 duration_ms；播放在下方继续，较新的标识请求会替换该覆盖层。
屏幕的主机提示必须声明 identify 能力，否则返回 409 identify_unsupported 且不发送任何内容；请更新播放器，或通过提示显示名称。屏幕必须处于活动状态；归档屏幕返回 screen_archived，pairing_pending 屏幕返回 resource_conflict。屏幕修订版本不变。
请求体和 Idempotency-Key 均可选；完全重试在 24 小时内返回原始响应体。被拒绝的请求、失败的请求和完全重放都不消耗速率限制预算。屏幕消息免于 1 额度 API 计量。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| duration_ms（可选，整数） | 覆盖层保持显示的时长，自播放器收到请求起算，单位为毫秒。省略时默认为 60000。默认：60000 最小值：2000 最大值：600000 |
请求模板和响应
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/screens/RESOURCE_ID/identify'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 202 | 已接受。命令在 expires_at 之前可执行。完全幂等的重试返回相同的主体。 | ScreenIdentifyAccepted（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) |
| 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) |
暂停屏幕
暂停屏幕：其播放器显示 message 以代替其内容（docs/player-compatibility.md §6.9）。message 在去除首尾空白后为 1 到 280 个字符；换行符是唯一允许的控制字符。
其他一切不变：播放列表、排程、接管、显示控制和所有其他设置都会保留并继续演进，恢复后显示屏幕此刻应显示的内容。Screen.suspension 携带 message 和 since。对已暂停的屏幕再次暂停会替换 message 并保留 since。
已暂停屏幕的运行时清单中 pages 为 []，带有 suspension 成员和自己的清单修订版本，无论是否分配了播放列表；播放器会被告知立即重新获取。追加仅限项目的 screen.suspended（details 含 message）。归档屏幕返回 screen_archived。If-Match 和 Idempotency-Key 可选，与归档相同。
受保护屏幕文件夹中的屏幕为 protected_target（409）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| message（必填，字符串） | 屏幕显示的通知，去除首尾空白后为 1 到 280 个字符。换行符是唯一允许的控制字符；播放器会对文本自动换行并保留换行符。minLength：1 maxLength：280 |
请求模板和响应
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/screens/RESOURCE_ID/suspend'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 屏幕已暂停。ETag 是新的屏幕修订版本。 | 屏幕（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) |
| 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 | 当屏幕位于受保护屏幕文件夹中时返回 protected_target（docs/screen-scope.md；通过审核清除该文件夹的保护，完成更改，再次保护），或该操作的其他冲突。 | 问题 (application/problem+json) |
| 412 | 稳定的 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) |
恢复屏幕
结束屏幕的暂停：其播放器重新显示屏幕自身的内容，内容取自屏幕此刻应得到的清单（docs/player-compatibility.md §6.9）。播放器会被告知立即重新获取。追加仅限项目的 screen.resumed。恢复一个未暂停的屏幕会返回 200 且屏幕不变：修订版本不递增，也没有事件。
归档屏幕返回 screen_archived。无请求体。If-Match 和 Idempotency-Key 可选，与归档相同。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求模板和响应
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/resume'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 屏幕已恢复，或本来就未暂停。ETag 是屏幕修订版本。 | 屏幕（application/json）；头部：ETag |
| 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) |
| 412 | 稳定的 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) |
重启屏幕
请求屏幕的播放器重启设备（docs/player-compatibility.md §6.5）。可选的请求体设置 expires_in_s，即重启保持可执行的时长（60 到 86400 秒，默认 86400，即 24 小时）；超出范围的值返回 invalid_request 并指明 expires_in_s。始终追加仅限项目的 screen.reboot_requested。
在线屏幕会立即收到每屏运行时命令 player.reboot（details 含 reboot_id、reason 为 project、at、expires_at；超过 expires_at 后不再送达），该重启在 Screen.commands 中记录为 sent。
离线屏幕将重启保持为 queued 且不产生事件；当后端在 expires_at 之前处理该屏幕的下一次上线状态转换时，会追加该事件（reboot_id 和 expires_at 相同），命令变为 sent。已发送的重启在携带 uptime_s 的健康报告表明开机时间晚于其发送时间时变为 done。
较新的重启会取代仍在排队的较旧重启。超过 expires_at 的排队重启读取时显示为 expired，POST /api/screens/{id}/commands/{command_id}/cancel 可取消仍在排队的重启。屏幕必须处于活动状态；归档屏幕返回 screen_archived，pairing_pending 屏幕返回 resource_conflict。
屏幕的主机提示必须声明 reboot 能力，否则返回 409 reboot_unsupported 且不记录任何内容。屏幕修订版本不变。If-Match 和 Idempotency-Key 可选；完全重试在 24 小时内返回相同响应体。
每屏每 10 分钟最多 2 次；被拒绝的请求（reboot_unsupported、not_found、冲突）、失败的请求以及使用相同 Idempotency-Key 的完全重放都不占用此限额。
从发出重启起，直到健康报告证明其完成或十分钟过去，屏幕不会触发 screen_offline、display_disconnected 或 crashing 提醒或警报；届时仍成立的条件会正常开启。重启排程（PUT /api/screens/{id}/reboot-schedule）发出相同的重启，source 为 schedule。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| expires_in_s（可选，整数） | 命令保持可执行的时长，自请求起算，单位为秒。排队的命令只会在过期前发送；播放器会忽略 expires_at 之后的命令。默认：86400 最小值：60 最大值：86400 |
请求模板和响应
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/screens/RESOURCE_ID/reboot'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 202 | 已接受。重启发送到在线屏幕的播放器时 state 为 sent，等待屏幕上线时为 queued。重启在 expires_at 之前保持可执行。ETag 是未更改的屏幕修订版本。 | ScreenRebootAccepted（application/json）；头部：Cache-Control，ETag，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) |
| 412 | 稳定的 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) |
清除屏幕缓存
请求屏幕的播放器清除其缓存（docs/player-compatibility.md §6.5.1）。播放器删除已下载的媒体、应用包和数据缓存，保留其配对、身份和设置，然后重新获取清单和内容。
可选请求体设置 expires_in_s，即命令保持可执行的时长（60 到 86400 秒，默认 86400，即 24 小时）；超出范围的值返回 invalid_request 并指明 expires_in_s。总会追加仅限项目的 screen.command_requested。
在线屏幕会立即收到按屏幕的运行时命令 player.clear_cache（details 为 command_id, command, reason project, at, expires_at；过了 expires_at 绝不送达），并且该命令在 Screen.commands 中记录为 sent。
离线屏幕将命令保存为 queued 且没有事件；当后端在 expires_at 之前处理该屏幕的下一次上线状态转换时，会追加该事件（command_id 和 expires_at 相同），命令变为 sent。
播放器报告其结束情况：命令在 Screen.commands 中变为 done 或 failed，附带播放器报告的原因（cause, detail），并追加仅限项目的 screen.command_result。没有报告的 sent 命令保持 sent。
同类型的较新命令会取代仍在排队的命令，POST /api/screens/{id}/commands/{command_id}/cancel 可取消仍在排队的命令。屏幕必须处于活动状态；归档屏幕返回 screen_archived，pairing_pending 屏幕返回 resource_conflict。
屏幕的主机提示必须声明 clear_cache 能力，否则返回 409 command_unsupported 且不记录任何内容。屏幕修订版本不变。If-Match 和 Idempotency-Key 是可选的；完全相同的重试在二十四小时内返回相同的响应体。
清除缓存、重启应用和更新合计每屏每 10 分钟最多 2 次；被拒绝的请求（command_unsupported, not_found, 冲突）、失败的请求，以及完全相同的 Idempotency-Key 重放，不消耗额度。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| expires_in_s（可选，整数） | 命令保持可执行的时长，自请求起算，单位为秒。排队的命令只会在过期前发送；播放器会忽略 expires_at 之后的命令。默认：86400 最小值：60 最大值：86400 |
请求模板和响应
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/screens/RESOURCE_ID/clear-cache'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 202 | 已接受。命令发送到在线屏幕的播放器时 state 为 sent，等待屏幕上线时为 queued。命令在 expires_at 之前可执行。ETag 是未改变的屏幕修订版本。 | ScreenMaintenanceAccepted（application/json）；头信息：Cache-Control, ETag, 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) |
| 412 | 稳定的 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) |
重启屏幕应用
请求屏幕的播放器重启其应用，而非设备（docs/player-compatibility.md §6.5.1）。播放器进程重启并从新进程报告。可选请求体设置 expires_in_s，即命令保持可执行的时长（60 到 86400 秒，默认 86400，即 24 小时）；超出范围的值返回 invalid_request 并指明 expires_in_s。
总会追加仅限项目的 screen.command_requested。在线屏幕会立即收到按屏幕的运行时命令 player.restart_app（details 为 command_id, command, reason project, at, expires_at；过了 expires_at 绝不送达），并且该命令在 Screen.commands 中记录为 sent。
离线屏幕将命令保存为 queued 且没有事件；当后端在 expires_at 之前处理该屏幕的下一次上线状态转换时，会追加该事件（command_id 和 expires_at 相同），命令变为 sent。
播放器报告其结束情况：命令在 Screen.commands 中变为 done 或 failed，附带播放器报告的原因（cause, detail），并追加仅限项目的 screen.command_result。没有报告的 sent 命令保持 sent。
同类型的较新命令会取代仍在排队的命令，POST /api/screens/{id}/commands/{command_id}/cancel 可取消仍在排队的命令。屏幕必须处于活动状态；归档屏幕返回 screen_archived，pairing_pending 屏幕返回 resource_conflict。
屏幕的主机提示必须声明 restart_app 能力，否则返回 409 command_unsupported 且不记录任何内容。屏幕修订版本不变。If-Match 和 Idempotency-Key 是可选的；完全相同的重试在二十四小时内返回相同的响应体。
清除缓存、重启应用和更新合计每屏每 10 分钟最多 2 次；被拒绝的请求（command_unsupported, not_found, 冲突）、失败的请求，以及完全相同的 Idempotency-Key 重放，不消耗额度。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| expires_in_s（可选，整数） | 命令保持可执行的时长，自请求起算，单位为秒。排队的命令只会在过期前发送；播放器会忽略 expires_at 之后的命令。默认：86400 最小值：60 最大值：86400 |
请求模板和响应
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/screens/RESOURCE_ID/restart-app'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 202 | 已接受。命令发送到在线屏幕的播放器时 state 为 sent，等待屏幕上线时为 queued。命令在 expires_at 之前可执行。ETag 是未改变的屏幕修订版本。 | ScreenMaintenanceAccepted（application/json）；头信息：Cache-Control, ETag, 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) |
| 412 | 稳定的 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) |
更新屏幕播放器
请求屏幕的播放器立即检查最新的播放器版本并安装（docs/player- compatibility.md §6.5.1）。当最新版本已在运行时，结果 cause 为 up_to_date，安装了新版本时为 updated；由商店管理或设备管理的安装不声明 update 能力。
可选请求体设置 expires_in_s，即命令保持可执行的时长（60 到 86400 秒，默认 86400，即 24 小时）；超出范围的值返回 invalid_request 并指明 expires_in_s。总会追加仅限项目的 screen.command_requested。
在线屏幕会立即收到按屏幕的运行时命令 player.update（details 为 command_id, command, reason project, at, expires_at；过了 expires_at 绝不送达），并且该命令在 Screen.commands 中记录为 sent。
离线屏幕将命令保存为 queued 且没有事件；当后端在 expires_at 之前处理该屏幕的下一次上线状态转换时，会追加该事件（command_id 和 expires_at 相同），命令变为 sent。
播放器报告其结束情况：命令在 Screen.commands 中变为 done 或 failed，附带播放器报告的原因（cause, detail），并追加仅限项目的 screen.command_result。没有报告的 sent 命令保持 sent。
同类型的较新命令会取代仍在排队的命令，POST /api/screens/{id}/commands/{command_id}/cancel 可取消仍在排队的命令。屏幕必须处于活动状态；归档屏幕返回 screen_archived，pairing_pending 屏幕返回 resource_conflict。
屏幕的主机提示必须声明 update 能力，否则返回 409 command_unsupported 且不记录任何内容。屏幕修订版本不变。If-Match 和 Idempotency-Key 是可选的；完全相同的重试在二十四小时内返回相同的响应体。
清除缓存、重启应用和更新合计每屏每 10 分钟最多 2 次；被拒绝的请求（command_unsupported, not_found, 冲突）、失败的请求，以及完全相同的 Idempotency-Key 重放，不消耗额度。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| expires_in_s（可选，整数） | 命令保持可执行的时长，自请求起算，单位为秒。排队的命令只会在过期前发送；播放器会忽略 expires_at 之后的命令。默认：86400 最小值：60 最大值：86400 |
请求模板和响应
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/screens/RESOURCE_ID/update'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 202 | 已接受。命令发送到在线屏幕的播放器时 state 为 sent，等待屏幕上线时为 queued。命令在 expires_at 之前可执行。ETag 是未改变的屏幕修订版本。 | ScreenMaintenanceAccepted（application/json）；头信息：Cache-Control, ETag, 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) |
| 412 | 稳定的 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) |
列出屏幕命令
列出对活跃或已归档屏幕发出的每个重启和重新加载请求，最新的在前：包括 Screen.commands 保存的命令（最新 10 条）和所有更早的命令，以及各自达到的状态。超过 expires_at 仍在排队的命令读作 expired。屏幕设备被更换时仍在排队的命令读作 cancelled。
用 POST /api/screens/{id}/commands/{command_id}/cancel 取消仍在排队的命令。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| 游标 | 查询 | 可选 | 上一页的 next_cursor。 |
| 限制 | 查询 | 可选 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/commands'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 屏幕命令的一页。 | ScreenCommandPage (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) |
取消屏幕命令
取消屏幕上仍在排队的重启或重新加载，使其永不发送（docs/player-compatibility.md §6.3、§6.5）。command_id 是 Screen.commands 中的 id，或 202 响应中的 reboot_id 或 reload_id。只有 state 为 queued 的命令可以取消；取消后变为 cancelled。
已发送的命令（sent、done）返回 409 resource_conflict 并附带 "The command was already sent."；不再排队的命令（expired、cancelled、superseded）返回 409 resource_conflict 并附带 "The command is no longer queued."；屏幕未列出的 id 返回 404 not_found。屏幕的列表保留最新的 10 条命令。
屏幕修订版本不变。If-Match 和 Idempotency-Key 可选；完全重试在 24 小时内返回同一个屏幕。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| command_id | 路径 | 必填 | 屏幕某条命令的 id：Screen.commands 中的 id，或 202 响应中的 reboot_id 或 reload_id。 |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求模板和响应
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/commands/COMMAND_ID/cancel'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 命令已取消的屏幕。ETag 是未更改的屏幕修订版本。 | 屏幕（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) |
| 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) |
| 412 | 稳定的 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) |
设置屏幕显示
请求立即开启或关闭显示：手动覆盖显示计划（docs/player-compatibility.md §6.5）。power为开或关。until（RFC 3339，严格为未来时间，最多提前7天）结束覆盖；无until时，启用计划时在下一个计划边界结束，否则保持覆盖直到被替换。
存储覆盖（Screen.display.override），重新生成清单（其显示成员携带覆盖，离线播放器保留），追加运行时命令 player.display（详情包括 override_id、power、until、at、expires_at）和仅项目可见的 screen.display_changed，并提升屏幕版本（If-Match 保护）。屏幕必须处于激活状态。
播放器的健康 display.power（Screen.display.reported）报告了其达成的结果。成功后会保存意图，无需等待报告；Screen.display.override_status 会比较后续观察结果，Screen.display.control 指明所公布的控制方式。
仅使用遮罩层的 Player 在收到开启请求时会移除其叠加层，而不发送硬件唤醒命令。
无结束时间且未来八天内无计划边界（无启用计划或无变更），覆盖将持续有效，直到 DELETE /api/screens/{id}/display 或替换操作；后续的显示计划 PUT 或 DELETE，或时区变更，会将无结束时间的覆盖重新绑定到新的下一个边界。
被拒绝或失败的请求，以及完全相同的 Idempotency-Key 重放，不会消耗预算。受保护屏幕文件夹中的屏幕为 protected_target（409）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| 电源（必填，字符串） | 允许值："on"、"off" |
| 直到（可选，内联） | 严格未来，最多提前 7 天。省略或空值：直到显示计划的下一个边界，否则直到被替换。 |
请求模板和响应
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/screens/RESOURCE_ID/display'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 带显示状态的屏幕。 | 屏幕（application/json）；头部：ETag，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 | 当屏幕位于受保护屏幕文件夹中时返回 protected_target（docs/screen-scope.md；通过审核清除该文件夹的保护，完成更改，再次保护），或该操作的其他冲突。 | 问题 (application/problem+json) |
| 412 | 稳定的 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) |
清除屏幕显示
结束手动显示覆盖，使显示计划（否则开启）再次生效。重新生成清单（其显示成员移除覆盖；播放器遵循 screen.manifest_changed），追加 screen.display_changed 并带有更改 override_cleared，提升版本。无活动覆盖的屏幕返回 200 不变。
受保护屏幕文件夹中的屏幕为 protected_target（409）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求模板和响应
curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/display'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 带显示状态的屏幕。 | 屏幕（application/json）；头部：ETag，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 | 当屏幕位于受保护屏幕文件夹中时返回 protected_target（docs/screen-scope.md；通过审核清除该文件夹的保护，完成更改，再次保护），或该操作的其他冲突。 | 问题 (application/problem+json) |
| 412 | 稳定的 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) |
获取屏幕显示排程
返回 display_schedule（无时为 null）和屏幕的显示状态。ETag 是屏幕修订版本。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/display-schedule'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 显示计划。 | ScreenDisplayScheduleView（application/json）；头部：ETag |
| 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) |
| 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) |
设置屏幕显示排程
替换显示排程：启用且包含1至16个screenrig.schedule/v1窗口（天数，开始/结束HH:MM，结束<=开始表示跨午夜且归属开始日，无边界表示全天），显示开启时生效；窗口外播放器将显示器置于待机。
在屏幕时区的设备上评估（必需，否则为 invalid_request），因此离线时仍可工作：清单的 display 成员携带它。enabled false 保持窗口并保持显示开启。重新生成清单，追加 screen.display_changed，提升修订号（If-Match 保护）。屏幕必须为 pairing_pending 或活动状态。
尚无清单的屏幕（从未生成，或没有播放列表）会存储该排程，其第一份清单将带上它；没有播放列表的屏幕在分配播放列表后应用一次。没有 until 的覆盖会重新限定到新排程的下一个边界。受保护屏幕文件夹中的屏幕为 protected_target（409）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| 启用（必填，布尔值） | |
| windows（必填，数组） | 在 Windows 上。 |
请求模板和响应
curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/display-schedule'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 带显示状态的屏幕。 | 屏幕（application/json）；头部：ETag，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 | 当屏幕位于受保护屏幕文件夹中时返回 protected_target（docs/screen-scope.md；通过审核清除该文件夹的保护，完成更改，再次保护），或该操作的其他冲突。 | 问题 (application/problem+json) |
| 412 | 稳定的 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) |
清除屏幕显示排程
移除显示排程（除非被覆盖，否则显示保持开启）。清除不存在的排程返回 200 unchanged。受保护屏幕文件夹中的屏幕为 protected_target（409）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求模板和响应
curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/display-schedule'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 带显示状态的屏幕。 | 屏幕（application/json）；头部：ETag，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 | 当屏幕位于受保护屏幕文件夹中时返回 protected_target（docs/screen-scope.md；通过审核清除该文件夹的保护，完成更改，再次保护），或该操作的其他冲突。 | 问题 (application/problem+json) |
| 412 | 稳定的 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) |
获取屏幕重启排程
返回 reboot_schedule（无则为 null）和 next_reboot_at，即后端下次重启屏幕的窗口的开始时间（没有则为 null）。ETag 是屏幕修订版本。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/reboot-schedule'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 重启排程。 | ScreenRebootScheduleView (application/json); headers: ETag |
| 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) |
| 默认 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
设置屏幕重启排程
替换重启排程：enabled 和 1 到 16 个 screenrig.schedule/v1 窗口（days、start/end HH:MM，end <= start 表示跨越午夜并归属于开始日，无边界则为全天），每个窗口长 5 分钟到 24 小时。
在屏幕时区（必填，否则 invalid_request）的每个窗口开始时，后端发出与 POST /api/screens/{id}/reboot 相同的重启，source 为 schedule，记录在 Screen.commands、screen.reboot_requested 和 player.reboot 详情中。
落在春季拨快间隙内的开始时间，在窗口的第一个有效分钟触发；若当天窗口因完全位于间隙内而没有有效分钟，则会被跳过，记为 screen.reboot_skipped，reason 为 window_missed（next_reboot_at 显示间隙结束的那一分钟）。秋季回拨造成的重复时间，每个窗口每个本地日期只触发一次。
在线的屏幕会立即收到重启；离线的屏幕只在其窗口结束（expires_at）之前保持排队，因此迟到的重启绝不会落在窗口之外。排程的某次执行绝不会取代人工请求且仍在等待屏幕的重启：该次会被跳过，记为 screen.reboot_skipped，reason 为 reboot_pending。
时区变更会取消仍在等待的计划重启，并将 next_reboot_at 移到新时区。
重启，无论是计划内还是人工请求的，在发出后十分钟内不会触发 screen_offline、display_disconnected 或 crashing 警报；这段时间内到期的这些条件的提醒，会等到该时段结束再加上其保持时间后才发出（crashing 提醒会作为 planned_reboot 被跳过）。enabled false 保留窗口，但不重启任何设备。
没有间隙、以致之后没有开始时间的时间窗口为 invalid_request。屏幕的主机提示必须声明 reboot 能力，否则返回 409 reboot_unsupported 且不存储任何内容；之后失去该能力的屏幕会以 screen.reboot_skipped 跳过每个窗口，并保留其排程。
追加 screen.reboot_schedule_changed，递增修订版本（If-Match 对其进行保护），且绝不重新生成清单。屏幕必须处于 active 状态。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| 启用（必填，布尔值） | |
| windows（必填，数组） | 重启窗口：后端在每个窗口开始时按屏幕时区重启屏幕。每个窗口长 5 分钟到 24 小时。 |
请求模板和响应
curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/screens/RESOURCE_ID/reboot-schedule'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 包含其重启排程和 next_reboot_at 的屏幕。 | 屏幕（application/json）；头部：ETag，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 — 排程重启属于 Plus；enabled true 需要它，enabled false 和 DELETE 则不需要。该问题指明功能、项目的计划和 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) |
| 409 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
| 412 | 稳定的 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) |
清除屏幕重启排程
移除重启排程和 next_reboot_at；已发出的重启不会被取消（POST /api/screens/{id}/commands/{command_id}/cancel 可取消仍在排队的重启）。清除不存在的排程返回 200，不作更改。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求模板和响应
curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://screenrig.ai/api/screens/RESOURCE_ID/reboot-schedule'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 没有重启排程的屏幕。 | 屏幕（application/json）；头部：ETag，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) |
| 412 | 稳定的 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) |
屏幕后提示
向指定屏幕发布一个临时舞台界面提示。提示不是原始画面：不占用画布槽，无图层，且不参与就绪或交叉淡入。持久事件类型为现有运行时SSE流上的screen.toast。运行时扫描在expires_at之后不再发送提示，因此持久化游标无法重放。
级别颜色是播放器界面元素，不是API字段。文本长度为1到120个字符，换行符是唯一接受的换行方式，最多接受三行；播放器在一行内显示提示，换行符显示为空格。
识别出的ScreenRig凭证材料和其他控制字符将被拒绝。duration_ms默认为60000，必须在2000到60000之间（含）。相同 Idempotency-Key 的精确重试在 24 小时内返回原始 expires_at。最新优先：无队列，无取消动词。屏幕消息免除 1 信用 API 计量。
受保护屏幕文件夹中的屏幕为 protected_target（409）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| Idempotency-Key | header | 必填 |
请求主体字段
| 字段 | 描述 |
|---|---|
| 级别（必填，字符串） | 已关闭严重性令牌。播放器界面选择填充色；API 从不携带颜色。允许值：“error”、“alert”、“info” |
| 文本（必填，字符串） | 1 到 120 个字符。仅允许换行符作为换行。最多三行；播放器在一行内显示该提示，换行符显示为空格。不允许其他控制字符和可识别的 ScreenRig 凭证内容。minLength：1 maxLength：120 |
| duration_ms（可选，整数） | 可见持续时间，单位毫秒。省略值默认为 60000。默认值：60000 最小值：2000 最大值：60000 |
请求模板和响应
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/screens/RESOURCE_ID/toast'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 202 | 已接受。提示在 expires_at 之前持久有效。完全幂等的重试返回相同的过期时间。 | ScreenToastAccepted（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 | 当屏幕位于受保护屏幕文件夹中时返回 protected_target（docs/screen-scope.md；通过审核清除该文件夹的保护，完成更改，再次保护），或该操作的其他冲突。 | 问题 (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) |
预测屏幕存储
预分配适配干运行：回答一个播放列表在分配前是否适合指定屏幕，目标选择与Screen.storage_forecast相同（屏幕最后报告容量，仅计划A.3，无过渡预测，无本地处理）。
不写入任何内容：无分配、无屏幕版本、无事件，屏幕的 storage_forecast 读取模型不变。项目持有者为权威；非本项目的屏幕或播放列表返回 not_found。屏幕无存储报告或播放列表内容引用未准备好且字节数均为 null 时，适配度未知。
可选的playlist_revision会拒绝自调用者读取后发生更改的播放列表，返回revision_conflict。接收时间超过24小时的报告虽过时，但仍可用于预测，行为与Screen.storage_forecast相同。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 |
请求主体字段
| 字段 | 描述 |
|---|---|
| playlist_id（必填，字符串） | minLength：1 |
| playlist_revision（可选，整数） | 可选的预期播放列表修订。存储的不同修订为 revision_conflict，且不返回预测。最小值：1 |
请求模板和响应
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/storage-forecast'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 干运行预测。fit unknown 表示无可预测数据；字节计数和 received_at 均为空。 | ScreenStorageForecastDryRun（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) |
| 412 | revision_conflict — playlist_revision 不是播放列表的当前版本；不返回预测。 | 问题 (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) |
说明屏幕活动
项目的每个活动为何在此屏幕上播放或不播放，按优先顺序列出，并附屏幕的有效播放列表。items 和 effective_playlist 是屏幕的当前状态。
给出 at（可选再给出 to）时，会向边界扫描所运行的同一解析器查询该时刻，返回对接管、每个活动和每个排程条目的判定（won、outranked、not_started、ended、outside_hours、off）、该时刻的播放列表，以及回答不作判断的内容。
同时给出 to 时，at.timeline 会列出 at 与 to 之间播放列表不变的时间段。排程、接管和活动按其现在的状态读取。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| 于 | 查询 | 可选 | 要解释的时刻，可以是带时区的 RFC 3339（2026-03-08T09:30:00Z 或 2026-03-08T01:30:00-08:00），也可以是屏幕自身时钟上的时间（2026-03-08T09:30，秒可选）。夏令时跳过或重复的时钟时间会被拒绝，返回指明 at 的 invalid_request，重复的时间会给出可供选择的两个时刻。 仅给出 to 时默认为现在。 |
| 至 | 查询 | 可选 | 从 at 开始的切换时间线的结束时间，形式与 at 相同。晚于 at，距离不受限制；一次回答最多列出 500 个时间段，无变化的八天算作一个，timeline_truncated 表示在到达 to 之前停止。 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/screens/RESOURCE_ID/campaigns'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 每个活动在该屏幕上的状态。 | ScreenCampaigns (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) |
获取屏幕截图
返回指定屏幕当前就绪的静态 WebP。可选的 capture_id 必须匹配该就绪槽。已过期且无上传的指定 capture_id 为 screenshot_unavailable。被后续请求替代的指定 capture_id 为 resource_conflict。图像字节从不为签名 URL 或对象键。不接受范围请求。
屏幕消息免于 1 额度 API 计量。ETag 是存储的 WebP 的强 SHA-256。控制台会话响应为私有、无缓存，且控制台的 If-None-Match 与当前图像匹配，在屏幕和捕获解析会话项目后检查，返回 304 且不打开存储字节。
项目持有者响应保持私密，不存储。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| capture_id | 查询 | 可选 | |
| If-None-Match | header | 可选 | 此路由返回的截图强 ETag。仪表板会话中生效。 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/screenshot'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 当前就绪的静态 WebP。 | 字符串（image/webp）；头部：Content-Type、Content-Length、ETag、X-ScreenRig-Capture-ID、X-ScreenRig-Captured-At、Cache-Control、Content-Disposition |
| 304 | 仅限控制台会话。当前图片的ETag与If-None-Match匹配。不产生主体且不读取对象存储。捕获头部命名当前捕获，可能与存储响应的捕获不同，后者编码为相同字节。 | 无正文；头部：ETag、Cache-Control、X-ScreenRig-Capture-ID、X-ScreenRig-Captured-At |
| 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) |
| 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) |
请求屏幕截图
请求指定活动屏幕的一张静态截图。最新请求优先：新请求替换任何正在进行的 capture_id，不返回 409。当前就绪槽保持，直到后续上传成功。capture_id 为可选环境前缀，后接 shot_ 和随机后缀。expires_at 为接受后 30 秒。
持久事件类型是现有运行时 SSE 流上的 screen.screenshot_requested；运行时扫描在 expires_at 后永远不会传递它。事件详情命名 capture_id、expires_at、max_width_divisor 2、max_height_divisor 2，格式 image/webp，质量 80，和 max_bytes 2097152。图像字节永远不会出现在 SSE 上。
预付剩余额度不是门槛，此屏幕消息路径免于1额度API计量。精确的Idempotency-Key重试在24小时内返回原始的capture_id和expires_at。
在控制台通道，请求可像POST /api/tab-shares一样来自Chrome或Firefox扩展来源，以确认共享标签页（GET /api/screens/{id}/screenshot/status和GET /api/screens/{id}/screenshot不需要来源规则）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| Idempotency-Key | header | 必填 |
请求模板和响应
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Idempotency-Key: REQUEST_ID' 'https://screenrig.ai/api/screens/RESOURCE_ID/screenshot'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 202 | 已接受。请求在 expires_at 之前持久有效。完全幂等的重试返回相同的 capture_id 和过期时间。 | ScreenScreenshotAccepted（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) |
| 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) |
获取屏幕截图状态
返回指定屏幕的截图状态机（若该项目存在）。idle 表示无请求且无就绪槽。pending 是当前 capture_id，未上传且未过期。ready 表示最后一次成功上传匹配当前 capture_id。timed_out 表示当前 ID 到达 expires_at 且未上传。
超时是懒惰的：过期后首次状态 GET 或下一次 POST 会记录它，并附加一次 screen.screenshot_failed，原因是过期。超时请求不会删除旧的就绪槽。屏幕消息免于 1 额度 API 计量。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/screenshot/status'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 此项目屏幕的截图状态。 | ScreenScreenshotStatus（application/json）；头部：Cache-Control |
| 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) |
| 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) |
获取屏幕实时会话
Returns the screen's live session after lazy expiry: idle when it has none, requested while the Player has been asked to publish, publishing once the media relay holds its video, ended with ended_reason (stopped, expired, consent_denied, consent_timeout, capture_failed, connection_failed or player_stopped; an open enum) for ten minutes after it ended. publisher.connected is true only while the Player's last report, at most 45 seconds old, said it is connected; it is the Player's own word, not proof of picture. 404 feature_unavailable when the server has no media relay configured.
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/live'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 屏幕的实时会话。 | LiveSession（application/json）；头信息：Cache-Control |
| 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) |
| 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) |
启动屏幕实时会话
Starts live view of the named screen, or renews the one it has (docs/player-compatibility.md §6.10): sub-second video of what the screen plays, from the Player through a media relay to the dashboard. A screen has one live session, shared by every viewer.
Its lease runs duration_s from now (30 to 300, default 300) and a start or renewal sets lease_until to the later of its current end and that instant, never past max_until, five minutes after the session began. The session ends by itself at the latest then: nothing renews or restarts it, and a new session needs a new start.
租约到期且未续期、收到 DELETE 或 Player 结束会话时，会话会提前结束；Player 会在租约结束后约 20 秒内停止推流。
With live_id the request only renews that session: when it is not the screen's live session (it ended, or the screen started another) the answer is 409 live_unavailable naming ended_reason, and no session starts or is extended.
新会话会追加按屏幕的运行时命令 player.live_publish（details 含 live_id、at、六十秒后的 expires_at、max_until；超过 expires_at 后绝不投递）；续期仅在 Player 从未加入且上一条命令已过期时才再次发送。
The screen must be active and online and its host hint must declare the live_view capability: 409 live_unsupported (update the Player, or use a screenshot), 409 live_unavailable (offline), screen_archived. 404 feature_unavailable when the server has no media relay configured. 201 is a new session, 200 a renewed one; both return the LiveSession with a viewer_url that opens the dashboard viewer.
requested 状态会持续到 Player 开始推流：请轮询 GET，直到 publisher.connected。实时视图免费，与截图一样不计入 1 积分的 API 计量。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 |
请求主体字段
| 字段 | 描述 |
|---|---|
| duration_s（可选，整数） | 租约自现在起持续的时长（秒）。无论租约多长，会话最长五分钟。default: 300 minimum: 30 maximum: 300 |
| live_id（可选，字符串） | Renew this session only. When it is not the screen's live session, the answer is live_unavailable (the detail names ended_reason) and nothing starts or is extended. Without it, a start begins a session when the screen has none. pattern: "^lv_[a-z2-7]{26}$" |
请求模板和响应
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/screens/RESOURCE_ID/live'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 201 | 新的实时会话；已要求 Player 推流。 | LiveSession（application/json）；头信息：Cache-Control, RateLimit-Policy, RateLimit |
| 200 | 已续期的屏幕实时会话。 | LiveSession（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) |
| 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) |
停止屏幕实时会话
Ends the screen's live session (ended_reason stopped), appends player.live_stop (details live_id, at, expires_at sixty seconds later), and closes its tracks on the media relay. 204 also when the screen has no live session. A Player that misses the command stops at its next heartbeat. 404 feature_unavailable when the server has no media relay configured.
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 |
请求模板和响应
curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/live'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 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) |
| 404 | 稳定的 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) |
创建屏幕实时查看者
打开屏幕实时会话的一个查看者：一个订阅 Player 视频的新媒体中继会话，以及中继的 WebRTC 提议。
Apply offer with setRemoteDescription on an RTCPeerConnection built with ice_servers (short-lived credentials), create the answer, wait for ICE gathering to complete or two seconds, then PUT the answer to /api/screens/{id}/live/viewers/{viewer_id} within two minutes.
Candidates travel inside the SDP; there is no separate candidate call. 409 live_not_ready while the session is requested, 409 live_unavailable when the screen has no live session or it ended (the detail names ended_reason). 404 feature_unavailable when the server has no media relay configured.
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 |
请求模板和响应
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/screens/RESOURCE_ID/live/viewers'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 201 | 一个查看者和中继的提议。 | LiveViewer（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) |
| 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) |
应答屏幕实时查看者
Applies the viewer's WebRTC answer to the relay's offer. A viewer answers once, within two minutes of its offer; an unknown, expired, already answered or another screen's viewer_id is 404 not_found. 204 once the relay accepts the answer; media then flows from the relay to the viewer. 404 feature_unavailable when the server has no media relay configured.
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| viewer_id | 路径 | 必填 |
请求主体字段
| 字段 | 描述 |
|---|---|
| answer（必填，SessionDescription） |
请求模板和响应
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/screens/RESOURCE_ID/live/viewers/VIEWER_ID'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 204 | 中继已接受该应答。 | 无正文；头部：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) |
| 404 | 稳定的 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) |
启动屏幕实时帧
Starts JPEG frames of the screen's live session, for an agent that has HTTPS and no WebRTC: the media relay decodes the Player's published video and delivers one JPEG about every second, and GET /api/screens/{id}/live/frame returns the latest.
会话必须正在推流（在此之前返回 409 live_not_ready；没有会话或会话已结束时返回 409 live_unavailable；请用 POST /api/screens/{id}/live 启动一个）。
Frames are started once per session: asking again answers the same adapter's progress, and a Player that reconnects ends its frames, so ask again. state is starting until the first frame arrives, streaming while frames arrive, and silent when the adapter is older than fifteen seconds and none has arrived in that time (last_frame_at, when present, says when frames last came).
The frames end with the session. 404 feature_unavailable when the server has no media relay or no frames origin configured. Live frames are free and exempt from the 1-credit API meter, like a screenshot. They are what the Player's encoder sent, scaled and lossy; they do not replace a screenshot as proof of layout.
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 |
请求模板和响应
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/live/frames'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 202 | 帧适配器及其进度。 | LiveFrames（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) |
| 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) |
获取屏幕实时帧
返回屏幕实时会话的最新 JPEG 帧。
Without after it returns the latest frame there is; with after (the ScreenRig-Captured-At of the frame you already have) it returns the first frame captured later, waiting up to five seconds for one, so a loop that passes each answer's ScreenRig-Captured-At back as after receives every new frame once.
ScreenRig-Captured-At 表示后端收到该帧的时间。
When no new frame comes in time the answer is 409 live_not_ready with Retry-After: 1; 409 resource_conflict answers a session whose frames were not started (POST /api/screens/{id}/live/frames first, and again after the Player reconnects); 409 live_unavailable answers a session that has ended or whose adapter is silent.
Frames are relay-decoded JPEGs of the live stream, at most 1280 by 720: they show what the Player encoded and sent, not a screenshot. They end with the session (max_until at the latest). 404 feature_unavailable when the server has no media relay or no frames origin configured. Free and exempt from the 1-credit API meter.
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| after | 查询 | 可选 | 返回在此时刻之后捕获的帧（RFC 3339，与 ScreenRig-Captured-At 相同）。 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/screens/RESOURCE_ID/live/frame'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 该帧。 | string（image/jpeg）；头信息：Content-Type, Content-Length, ETag, Cache-Control, ScreenRig-Live-Id, ScreenRig-Captured-At, ScreenRig-Frame-Width, ScreenRig-Frame-Height, 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 - 调用方限定于屏幕，且请求所指明或涉及的屏幕、屏幕文件夹、选择器或受众超出了这些屏幕（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) |
连接实时帧
The media relay's frame adapter connects here with a WebSocket upgrade; no client, agent or Player calls it. The token is the credential: POST /api/screens/{id}/live/frames hands it to the relay inside the adapter's endpoint and stores only its SHA-256.
Each binary message the relay sends is one protobuf Packet (field 1 sequenceNumber, field 2 timestamp, field 5 payload) whose payload is one whole JPEG of at most 2 MiB; anything else is skipped. The backend keeps the latest frame for fifteen seconds. One connection per token: a newer one replaces the older.
The connection is closed with 1000 when the live session ends, and a token of an ended session is refused with 401 before the upgrade. 404 feature_unavailable when the server has no frames origin configured.
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| 令牌 | 查询 | 必填 | 适配器的令牌，43 个字符。 |
请求模板和响应
curl --request GET 'https://api.screenrig.ai/live/frames?token=TOKEN'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 101 | 切换协议至 WebSocket。 | 无正文 |
| 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) |
| 默认 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
获取屏幕健康历史
屏幕随时间报告的健康状况。resolution=raw（默认）按时间顺序返回每个接受的报告，格式如 Screen.health，无过期；resolution=hour 返回每个 UTC 小时的汇总（报告数、峰值和平均温度、峰值负载和内存比率、最弱 Wi-Fi 信号、显示器是否断开连接、峰值崩溃和渲染器重启计数）。from（包含）和 to（不包含）默认为最近 24 小时；raw 最多 31 天，hour 最多 93 天。
页面最多包含 limit 行（默认 100，最多 500），带有 next_cursor，末尾为 null。历史记录保留计划的事件保留期限。原始报告几秒内可见，小时汇总约 5 分钟内可见。其他项目的屏幕返回 not_found。Screen.health（最新报告）保持不变。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| 格式 | 查询 | 可选 | json（默认）以 JSON 返回报告。csv、xlsx 和 pdf 以附件形式返回相同的行（分页报告的每一页，最多 50000 行）。 |
| 起始 | 查询 | 可选 | 报告时间的包含下限。默认为 to 之前 24 小时。 |
| 至 | 查询 | 可选 | 报告时间的独占上限。默认为当前时间。 |
| 分辨率 | 查询 | 可选 | raw 返回每个报告；hour 返回每个 UTC 小时的汇总。 |
| 限制 | 查询 | 可选 | 页面大小。 |
| 游标 | 查询 | 可选 | 上一页的 next_cursor，使用相同过滤条件。不透明。 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/health/history'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 报告或小时汇总页面。 | ScreenHealthHistory（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) |
| 404 | 稳定的 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) |
获取屏幕正常运行时间
单个屏幕在包含的 UTC 天数内的每日可用性（day_to 默认为今天，day_from 默认为 29 天前，最多 366 天）。每行包含当天记录的在线和离线秒数、可用性（在线时间占记录时间比例，未记录时为 null）和覆盖率（当天有记录状态的时间比例）。
无记录状态的时间从不计为停机时间：它只降低覆盖率。屏幕当前的开放区间包含至今的时间，并标记其在线天数。无记录的天数无行显示。屏幕离线是在无法访问60秒后记录。其他项目的屏幕为not_found。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| 格式 | 查询 | 可选 | json（默认）以 JSON 返回报告。csv、xlsx 和 pdf 以附件形式返回相同的行（分页报告的每一页，最多 50000 行）。 |
| day_from | 查询 | 可选 | 首个 UTC 天（含）。默认从 day_to 向前 29 天。与 day_to 一起最多跨 366 天。 |
| day_to | 查询 | 可选 | 最后的UTC日，含当日。默认为今天（UTC）。 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/uptime'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 每日在线时间行，最早日期优先。 | ScreenUptime（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) |
| 404 | 稳定的 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) |
获取屏幕状态
屏幕的在线和离线转换，最新优先，来自其 screen.online 和 screen.offline 事件，无论日志通道存储什么。since（包含）和 until（不包含）限定事件时间；until 默认为现在，since 最多为 30 天前，最长 366 天。转换保留符合计划的事件保留期。
页面最多包含 limit 个转换（默认 100，最多 500），带有 next_cursor，末尾为 null；请按原样返回。服务器仅在屏幕重新连接时发现的离线转换带有 detected_on_reconnect，其 at 字段为存在租约结束时间。屏幕离线记录在无法访问 60 秒后。
另一个项目的屏幕是 not_found。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| 自从 | 查询 | 可选 | 转换事件时间的包含下限。默认为 until 之前 30 天。 |
| 直到 | 查询 | 可选 | 转换事件时间的独占上限。默认为当前时间。until - since 最多366天。 |
| 限制 | 查询 | 可选 | 页面大小。超出 1-500 范围的值将被拒绝，返回 invalid_request 并命名 limit。 |
| before | 查询 | 可选 | 上一页的 next_cursor，使用相同的 since 和 until。 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/screens/RESOURCE_ID/presence'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 在线状态变更，最新优先。 | ScreenPresenceHistory（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) |
| 404 | 稳定的 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) |
获取 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 是单个屏幕的形式。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| 格式 | 查询 | 可选 | json（默认）以 JSON 返回报告。csv、xlsx 和 pdf 以附件形式返回相同的行（分页报告的每一页，最多 50000 行）。 |
| 起始 | 查询 | 可选 | 报告时间的包含下限。默认为 to 之前 24 小时。 |
| 至 | 查询 | 可选 | 报告时间的独占上限。默认为当前时间。 |
| 限制 | 查询 | 可选 | 页面大小。 |
| 游标 | 查询 | 可选 | 上一页的 next_cursor，使用相同过滤条件。不透明。 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/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) |
获取项目正常运行时间
项目屏幕在包含的 UTC 天数内的每日可用性（默认及范围同 GET /api/screens/{id}/uptime）。每行汇总当天有记录状态的屏幕的在线和离线秒数；覆盖率为这些屏幕当天有记录状态的时间比例。
间隔在结束时计数，因此今天的行涵盖迄今结束的间隔；实时在线计数显示在控制台摘要中。限定屏幕范围的调用方会被拒绝（outside_screen_scope）；GET /api/screens/{id}/uptime 是单个屏幕的形式。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| 格式 | 查询 | 可选 | json（默认）以 JSON 返回报告。csv、xlsx 和 pdf 以附件形式返回相同的行（分页报告的每一页，最多 50000 行）。 |
| day_from | 查询 | 可选 | 首个 UTC 天（含）。默认从 day_to 向前 29 天。与 day_to 一起最多跨 366 天。 |
| day_to | 查询 | 可选 | 最后的UTC日，含当日。默认为今天（UTC）。 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/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) |
列出车队链接
列出项目的设备链接，按最旧优先（最多 50 个）。在有效的“管理”下，每个 URL 为空且 url_redacted 为 true，因为 URL 用于创建屏幕。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/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) |
创建车队链接
创建车队链接：一个播放器 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 小时内返回相同答案。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| 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" |
请求模板和响应
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/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) |
获取车队链接
一个舰队链接。下方有效的管理 URL 为空且 url_redacted 为 true。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/fleet-links/RESOURCE_ID'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 一个舰队链接。 | FleetLink（application/json）；头部：ETag，Cache-Control |
| 默认 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
更新车队链接
可更改 label、enabled、tags、fields、playlist_id、max_screens 和 expires_at 中的任意项；null 会清除 fields、playlist_id、max_screens 或 expires_at。已禁用或已过期的链接不会创建或恢复任何屏幕；打开它的设备会改为显示其配对码。更改只适用于链接此后创建的屏幕，不影响已创建的屏幕。
追加 fleet_link.updated。If-Match 保护修订版本。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| label（可选，字符串） | minLength：1 maxLength：80 |
| 启用（可选，布尔值） | |
| 标签（可选，ScreenTags） | 设备组选择器标签，0 到 16 个唯一且精确的标签，每个标签符合媒体标签语法。在 ScreenPatch 中，数组替换整个集合，空数组则清空；重复或格式错误的标签为 invalid_request。更改标签会提升屏幕版本（If-Match 保护），并附加 screen.updated，详情见 details.tags；不会更改清单版本。 标签永远不会出现在运行时清单中，也不会用于授权。 |
| fields（可选，对象） | 替换整个预设；{} 或 null 会清除它。 |
| playlist_id（可选，字符串） | null 清空播放列表。 |
| max_screens（可选，整数） | null 取消限制。最小值：1 最大值：10000 |
| expires_at（可选，字符串） | null 表示移除到期时间。format: "date-time" |
请求模板和响应
curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/fleet-links/RESOURCE_ID'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 已更新车队链接。 | FleetLink（application/json）；头部：ETag |
| 400 | invalid_request。 | 问题 (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) |
删除车队链接
删除车队链接。其 URL 立即停止工作；其创建的屏幕保留，连同其播放列表、标签和字段。附加 fleet_link.deleted。If-Match 保护版本。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求模板和响应
curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/fleet-links/RESOURCE_ID'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 204 | 已删除。 | 无正文 |
| 412 | revision_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) |
轮换 Fleet Link
替换链接密钥并返回新URL。旧URL立即失效；已创建的屏幕继续播放，因为配对播放器不会再次展示该链接。附加fleet_link.updated，details.rotated为true。If-Match保护版本。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求模板和响应
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/fleet-links/RESOURCE_ID/rotate'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 舰队链接及其新 URL。 | FleetLink（application/json）；头部：ETag，Cache-Control |
| 412 | revision_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) |