OpenAPI YAMLOpenAPI JSON问题 YAMLAPI 概览
此分组有 10 个操作，由 api/openapi.yaml 生成。可按路径、操作或认证筛选。每个端点都会列出其输入；展开后可查看请求模板和响应代码。模板需要您自己的值和符合架构的请求体。
用你的值替换大写占位符。对于JSON请求，请保存符合request.json模式的请求体。Cookie示例使用经过身份验证会话的本地Cookie存储。
活动
列出活动
按优先级顺序列出项目的活动（最多 100 个），即解析时读取它们的顺序。每个活动都有 reserved。
限定屏幕范围的调用方（docs/screen-scope.md）可以看到每个活动，只有整个受众都在其范围内且调用方可以更改所播放的内容时，editable 才为 true（标签叶节点和根上的“每个屏幕”规则永远不算；all 规则需要一个被包含的子项，any 规则需要每个子项都被包含）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/campaigns'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 项目的活动。 | CampaignList (application/json) |
| 默认 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
创建活动
创建活动：在屏幕所在时区内，只要 from、until 和 windows 成立（screenrig.schedule/v1；三者都省略表示始终生效），其 audience 中的每个屏幕就切换到 playlist_id，不再成立时切换回来。
屏幕按以下顺序确定播放列表：先是接管播放列表，然后是按优先顺序（priority 高者在前，其次是最近创建者）第一个适用的活动，再是播放列表计划，最后是默认播放列表。活动仅适用于有默认播放列表的屏幕；带有 from、until 或 windows 的活动需要屏幕的时区。
播放列表必须存在且已批准（playlist_not_approved）。屏幕会在一分钟内切换；GET /api/campaigns/{id}/screens 显示每个屏幕的状态。一个组织跨其所有项目最多有 100 个活动（campaign_limit_reached）。
追加 campaign.created。reserved true 预留该活动，只有可以审批的人员才能设置（智能体、服务客户端或其他任何人返回 reserved_item），并追加 campaign.reserved_changed。
限定屏幕范围的调用方（docs/screen-scope.md）只能为其范围内的受众创建活动（folder 和 screen_id 叶节点；不能用标签，也不能用“每个屏幕”），否则返回 outside_screen_scope，并且只能以可以审批的人员身份创建（approver_required）。
涉及受保护屏幕的活动在任何访问级别都属于 protected_change 审核，由第二位审批人决定（202 pending_review）。reserved true 属于受保护的文件夹，新活动（草稿）上的 paused true 属于排程变更控制，二者都属于 Enterprise 计划；计划不含该功能的项目会被拒绝并返回 feature_not_in_plan（402）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| 名称（必填，字符串） | minLength：1 maxLength：120 |
| playlist_id（必填，字符串） | minLength：1 |
| audience (必填, CampaignAudience) | 活动定向的屏幕：all（每条规则都匹配）、any（至少一条匹配）、tag（屏幕带有该标签）、screen_id（该屏幕）或 folder（该屏幕文件夹及其内部每个文件夹中的屏幕，GET /api/screen-folders；该文件夹必须存在）中的恰好一个。 规则最多嵌套 3 层，一个 audience 最多有 500 条规则。{"all": []} 表示项目的每个屏幕；在其他位置，all 和 any 至少列出一条规则。 |
| from (可选, string) | pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T([01][0-9]|2[0-3]):[0-5][0-9]$" |
| until (可选, string) | 晚于 from。 pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T([01][0-9]|2[0-3]):[0-5][0-9]$" |
| windows (可选, array) | |
| monthly（可选，数组） | |
| dates（可选，数组） | |
| except（可选，数组） | 民用日期，按升序存储且每个仅一次。例外会移除在该日期开始的每次出现，包括跨夜的后续部分；它落在 from 和 until 之间。 |
| data（可选，PageDataCondition） | 卡片数据谓词，在本地时间前评估。缺失或过期数据永不匹配。页面也遵守其普通时间范围。需要 host 功能 page.conditions；旧主机收到禁用页面。 |
| interaction（可选，LevelInteraction） | 该层级在有人使用屏幕期间生效：从一次触摸、点击或按键开始，直到 idle_s 秒内没有任何输入。典型用法：叠在展示循环之上的交互页面。idle_s 会被存储并返回（省略时为 60）。 |
| covers（可选，字符串） | 该层级的播放位置：整页（默认，存储为缺省）或 main（页面本身），用于普通播放列表；header、footer 或 side，即绘制在页面之上的条带，仅用于该区域的区域播放列表（PlaylistRegionFormat）。区域播放列表使用 full 或 main 时会被拒绝，而条带需要布局在目标显示器上的区域播放列表。 允许：“full”、“main”、“header”、“footer”、“side” |
| displays（可选，数组） | 它所播放的视频墙输出；缺省则在每个输出上播放。 |
| start（可选，字符串） | on_time 在边界时刻切换，中断当前项目；next_item（默认，存储为缺省）等待当前项目结束。允许：“next_item”、“on_time” |
| priority (可选, integer) | default: 0 minimum: 0 maximum: 100 |
| paused (可选, boolean) | default: false |
| reserved（可选，布尔值） | 只有可以审批的人员才能预留活动（否则为 reserved_item）。default: false |
请求模板和响应
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/campaigns'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 201 | 已创建。 | Campaign (application/json); headers: ETag |
| 400 | invalid_request，包括项目中不存在的 audience 规则、窗口或 playlist_id。 | 问题 (application/problem+json) |
| 402 | feature_not_in_plan — 受保护的文件夹和排程变更控制属于 Enterprise 计划；该问题指明功能、账户所在的计划和 required_plan。将播放列表锁定到视频墙第 2 块或更靠后显示器（displays）的活动属于 Plus。该问题指明功能、项目的计划和 required_plan。 | 问题 (application/problem+json) |
| 409 | campaign_limit_reached、playlist_not_approved 或 idempotency_mismatch。 | 问题 (application/problem+json) |
| 202 | 写入成为审核，等待人员批准（docs/reviews.md），适用于提议权限，或者在任何访问级别下涉及受保护屏幕文件夹中的屏幕时，由第二位审批人决定（docs/screen-scope.md）。人员在控制台的 review.url 处批准、驳回或要求更改。 使用相同 Idempotency-Key 的重放会返回相同的响应体。 | ReviewPending（application/json） |
| 403 | outside_screen_scope 或 approver_required，同 ScreenScopePlays；或 reserved_item - 预留的活动只能由可以审批审核的人员更改、暂停、删除或取消预留，智能体或服务客户端绝不可以（docs/screen-scope.md）。 | 问题 (application/problem+json) |
| 默认 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
预览活动
活动写入会更改什么（不实际执行）。带 id 时，body 是该活动的 PATCH 请求体；不带时，是新活动的 POST 请求体。请求体按写入的检查方式检查（受众规则、时间窗口、未批准的播放列表、项目没有的屏幕文件夹）。
返回会在其堆栈上获得该活动的屏幕和会失去它的屏幕（count，以及前 500 个屏幕 id），以及旧受众和新受众中屏幕的排程日历，包括现状（before）和之后的状态（after），覆盖 from 到 to（默认：从现在起一周；最多 93 天），分组方式与 GET /api/schedule/calendar 相同。
已暂停的活动不在任何堆栈上，因此发布它会获得其受众；保持活动留在屏幕堆栈上的编辑既不获得也不失去任何屏幕，并显示在日历中。读取访问：不写入任何内容。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| id（可选，字符串） | PATCH 请求体所预览的活动；省略则预览创建。 |
| body（必填，对象） | 带 id 时为 CampaignPatch，不带时为 CampaignWrite。 |
| 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/campaigns/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) |
| 409 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
| 默认 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
获取活动
一个活动。reserved 始终存在；限定屏幕范围的调用方会得到 editable（参见 listCampaigns）。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| 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/campaigns/RESOURCE_ID'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 一个活动。 | Campaign (application/json); headers: ETag |
| 默认 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
更新活动
更改请求体设置的成员；null 会清除 from、until 或 windows。paused true 会使活动在每个屏幕上停止，false 则恢复。已暂停的活动是草稿：它不在任何屏幕的堆栈上，使其保持暂停的写入不会重新解析任何屏幕。
为测试而发布，即为此 PATCH，其中 paused false，且受众为测试文件夹或少数几个屏幕；然后 POST /api/campaigns/{id}/promote 会把该受众复制到正式受众上。旧受众和新受众的每个屏幕会在一分钟内重新解析。追加 campaign.updated。If-Match 用于保护修订。
每次写入都存储在活动的历史中（GET /api/campaigns/{id}/revisions）。campaign.updated。If-Match 用于保护修订。reserved 设置或清除预留标志（预留的活动只能由有权批准的人更改、暂停或取消预留，否则返回 reserved_item）；切换时追加 campaign.reserved_changed。
限定屏幕范围的调用方（docs/screen-scope.md）仅当活动已存储的受众和新受众都在其范围内时才能更改活动（outside_screen_scope；否则该活动对其为只读）。
涉及受保护屏幕的活动属于 protected_change 审核，由第二位审批人决定（202 pending_review）。对未预留的活动设置 reserved true 属于受保护的文件夹，Enterprise 计划包含该功能；计划不含该功能的项目会被拒绝并返回 feature_not_in_plan（402）。
暂停或恢复活动，以及编辑或释放预留的活动，在每个计划中都开放。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| 名称（可选，字符串） | minLength：1 maxLength：120 |
| playlist_id（可选，字符串） | minLength：1 |
| audience (可选, CampaignAudience) | 活动定向的屏幕：all（每条规则都匹配）、any（至少一条匹配）、tag（屏幕带有该标签）、screen_id（该屏幕）或 folder（该屏幕文件夹及其内部每个文件夹中的屏幕，GET /api/screen-folders；该文件夹必须存在）中的恰好一个。 规则最多嵌套 3 层，一个 audience 最多有 500 条规则。{"all": []} 表示项目的每个屏幕；在其他位置，all 和 any 至少列出一条规则。 |
| from (可选, 内联) | null 将其清除。 |
| 直到（可选，内联） | null 将其清除。 |
| windows (可选, 内联) | null 将其清除。 |
| monthly（可选，内联） | null 将其清除。 |
| dates（可选，内联） | null 将其清除。 |
| except（可选，内联） | null 将其清除。 |
| data（可选，内联） | null 将其清除。 |
| interaction（可选，内联） | null 将其清除。 |
| covers（可选，内联） | null 即整页。header、footer 和 side 需要该区域的区域播放列表（PlaylistRegionFormat）。 |
| displays（可选，内联） | null 表示在每个输出上播放。 |
| start（可选，内联） | null 即 next_item。 |
| priority (可选, integer) | minimum: 0 maximum: 100 |
| paused (可选, boolean) | |
| reserved（可选，布尔值） | 只有可以审批的人员才能预留或释放活动（否则返回 reserved_item）。 |
请求模板和响应
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/campaigns/RESOURCE_ID'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 更新后的活动。 | Campaign (application/json); headers: ETag |
| 402 | feature_not_in_plan — 受保护的文件夹属于 Enterprise 计划；该问题指明功能、账户所在的计划和 required_plan。设置活动自身之外的 displays 属于 Plus；在每个计划中，null 都可将其清除。该问题指明功能、项目的计划和 required_plan。 | 问题 (application/problem+json) |
| 409 | playlist_not_approved 或 idempotency_mismatch。 | 问题 (application/problem+json) |
| 412 | revision_conflict。 | 问题 (application/problem+json) |
| 202 | 写入成为审核，等待人员批准（docs/reviews.md），适用于提议权限，或者在任何访问级别下涉及受保护屏幕文件夹中的屏幕时，由第二位审批人决定（docs/screen-scope.md）。人员在控制台的 review.url 处批准、驳回或要求更改。 使用相同 Idempotency-Key 的重放会返回相同的响应体。 | ReviewPending（application/json） |
| 403 | outside_screen_scope 或 approver_required，同 ScreenScopePlays；或 reserved_item - 预留的活动只能由可以审批审核的人员更改、暂停、删除或取消预留，智能体或服务客户端绝不可以（docs/screen-scope.md）。 | 问题 (application/problem+json) |
| 默认 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
删除活动
删除活动及其修订历史。每个显示该活动的屏幕会在一分钟内恢复为没有它时所显示的内容。追加 campaign.deleted。If-Match 用于保护修订。预留的活动只能由有权批准的人删除（reserved_item）。
限定屏幕范围的调用方（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://api.screenrig.ai/api/campaigns/RESOURCE_ID'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 204 | 已删除。 | 无正文 |
| 412 | revision_conflict。 | 问题 (application/problem+json) |
| 202 | 写入成为审核，等待人员批准（docs/reviews.md），适用于提议权限，或者在任何访问级别下涉及受保护屏幕文件夹中的屏幕时，由第二位审批人决定（docs/screen-scope.md）。人员在控制台的 review.url 处批准、驳回或要求更改。 使用相同 Idempotency-Key 的重放会返回相同的响应体。 | ReviewPending（application/json） |
| 403 | outside_screen_scope 或 approver_required，同 ScreenScopePlays；或 reserved_item - 预留的活动只能由可以审批审核的人员更改、暂停、删除或取消预留，智能体或服务客户端绝不可以（docs/screen-scope.md）。 | 问题 (application/problem+json) |
| 默认 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
列出活动修订
活动的修订，最新的在前：每次由人员、智能体或排程导入（创建、更新、提升、恢复）写入后存储的活动，附带变更类型和变更者。
历史始于活动首次记录修订历史时所持有的修订：在其下一次写入之前，列表仅包含该修订，change 为 baseline。历史中没有 paused false 修订的活动是草稿。修订与活动同在，并随活动一起删除。
每页最多 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/campaigns/RESOURCE_ID/revisions'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 活动的修订，最新的在前。 | CampaignRevisionList（application/json） |
| 默认 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
恢复活动修订
通过与 PATCH 相同的写入，将更早的修订复制为最新一条，使其再次成为当前修订：其 name、playlist、audience、rule、placement、priority 和 paused 成为新的修订（change 为 restored，restored_from 为被复制的修订），并像更新一样进行检查（其播放列表必须仍然存在且已获批准），旧受众和新受众的每个屏幕都会重新解析，除非该活动已暂停并保持暂停。
更早的修订保持原样。If-Match 是必需的，并指明当前修订（缺失时为 invalid_request，过期时为 revision_conflict）。内容与当前内容相同的修订不会更改任何内容，并返回当前活动。访问权限与 PATCH 相同。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| 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/campaigns/RESOURCE_ID/revisions/REVISION/restore'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 已复制修订成为当前修订的活动；ETag 携带其修订。 | Campaign (application/json); headers: ETag |
| 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) |
| 默认 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
提升活动
发布测试。测试发布是对草稿的 PATCH，其中 paused false，且受众为测试文件夹或少数几个屏幕；随后 promote 会通过一次写入把 revision（草稿自己的已暂停修订）的受众复制到活动上（change promoted，restored_from 为被复制的修订），旧受众和新受众的每个屏幕都会重新解析。
当该修订未暂停（因为它不是草稿）以及活动当前已暂停（因为没有可提升的测试）时被拒绝（invalid_request，指明 revision）。If-Match 是必需的，并指明当前修订。受众与当前受众相同的修订不会更改任何内容。访问权限与 PATCH 相同。
提升属于排程变更控制，Enterprise 计划包含该功能；计划不含该功能的项目会被拒绝并返回 feature_not_in_plan（402）。修订历史、恢复和预览在每个计划中都开放。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| revision（必填，整数） | 活动采用其受众的草稿（已暂停）修订。minimum: 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://api.screenrig.ai/api/campaigns/RESOURCE_ID/promote'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 带有草稿受众的活动；ETag 携带其修订。 | Campaign (application/json); headers: ETag |
| 402 | feature_not_in_plan — 排程变更控制属于 Enterprise 计划；该问题指明功能、账户所在的计划和 required_plan。 | 问题 (application/problem+json) |
| 404 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
| 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) |
| 默认 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
列出活动屏幕
活动的覆盖范围。counts 涵盖其 audience 中每个在线屏幕（先是 audience，然后每种状态一个计数）；items 是这些屏幕按屏幕 id 顺序排列的一页，附有活动在每个屏幕上的状态（见 CampaignStatus）。
限定屏幕范围的调用方（docs/screen-scope.md）仅看到并统计其范围内的受众屏幕；计数和分页都基于该集合。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| ScreenRig-Project | header | 可选 | 已弃用一个版本。必须与 JWT 项目授权保持一致；添加弃用和警告头。无令牌交换。 |
| id | 路径 | 必填 | |
| 限制 | 查询 | 可选 | |
| 游标 | 查询 | 可选 | 上一页的 next_cursor。 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/campaigns/RESOURCE_ID/screens'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 活动的受众及状态。 | CampaignScreens (application/json) |
| 默认 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |