OpenAPI YAMLOpenAPI JSON问题 YAMLAPI 概览
此分组有 10 个操作，由 api/openapi.yaml 生成。可按路径、操作或认证筛选。每个端点都会列出其输入；展开后可查看请求模板和响应代码。模板需要您自己的值和符合架构的请求体。
用你的值替换大写占位符。对于JSON请求，请保存符合request.json模式的请求体。Cookie示例使用经过身份验证会话的本地Cookie存储。
数据源：让卡片保持最新的地址
列出数据源预设
列出数据源预设：json 数据源的现成且经过测试的配置 (docs/sources.md，Presets)。每个预设会说明它填充哪些卡片、需要人填写的字段（含帮助、模式和示例）、所需的密钥及各自的获取方式、刷新频率和卡片保留最后数据的时长，以及它读取谁的数据、遵循哪些条款。
用 POST /api/sources 并提供 preset、settings 和 secrets，即可根据预设创建数据源，并用 POST /api/sources/test 预览。
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/source-presets'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 数据源预设，按类别和标题排列。 | SourcePresetList（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) |
获取数据源预设
一个数据源预设，与列表中显示的相同。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| name | 路径 | 必填 | 数据源预设的名称，与 GET /api/source-presets 列出的相同。 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/source-presets/NAME'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 一个数据源预设。 | SourcePreset（application/json）；头信息：Cache-Control |
| 404 | not_found. | 问题 (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 个。数据源按计划从外部地址让某张卡片的动态属性保持最新 (docs/sources.md)。每个数据源都会显示其状态：上次尝试、上次成功、上次写入的更改、下次运行、失败次数和最近的错误。
密钥绝不会返回；每个密钥都以“已设置”加遮蔽提示的形式显示。把 next_cursor 作为 after 传回即可获取下一页，没有更多时为 null。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| after | 查询 | 可选 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/sources'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 项目的数据源。 | SourceList（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) |
创建数据源
创建一个数据源，从外部地址写入某张卡片的动态属性。kind 选择适配器（ics 读取 iCalendar 或 webcal:// 地址）；config 保存该类型的设置，secrets 保存其凭据，凭据会加密存储，只以遮蔽后的提示显示。
或者指定预设 (GET /api/source-presets)，并提供它的 settings 和 secrets，以代替 kind 和 config：该数据源是由预设构建配置的 json 数据源，返回时附带其 preset 和 settings，刷新间隔和过期时长默认取预设的值。预设只填充它所列出的卡片 (source_target_unsupported)。
数据源会在几秒内运行，之后每隔 refresh_seconds 运行一次。运行失败绝不会写入：卡片保留最后一份有效文档，数据源的状态会显示错误。一个数据源只填充一张卡片 (source_target_taken)，该卡片必须是此类型能够填充的 (source_target_unsupported)，一个组织最多有 200 个数据源 (source_limit_reached)。
请先用 POST /api/sources/test 查看该数据源将写入的文档。会追加 source.created。使用相同 Idempotency-Key 的完全相同的重试，在二十四小时内会返回同一响应。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| 名称（必填，字符串） | minLength：1 maxLength：80 |
| kind（可选，SourceKind） | 数据来源。ics 读取 iCalendar 和 webcal:// 地址（其他类型见 /docs/sources）。不可用的类型会在 kind 上返回 invalid_request。允许：“ics”、“sheets”、“csv”、“json”、“microsoft365”、“google_calendar”、“square”、“shopify”、“momentus”、“toast” |
| target（必填，SourceTarget） | |
| preset（可选，字符串） | 用于创建数据源的数据源预设 (GET /api/source-presets)，用来代替 kind 和 config：类型就是预设的类型，配置根据 settings 构建。不使用预设时 kind 和 config 必填；使用预设时它们会被拒绝，除非 kind 就是预设自己的类型。pattern: "^[a-z][a-z0-9]*(-[a-z0-9]+)*$" |
| settings（可选，object） | 预设各字段的值，按字段名给出（文本、选择项中的一项，或对象列表）。必填字段会按预设强制检查，并给出 settings.channel 这样的字段路径。 |
| config（可选，object） | 该类型的设置（/docs/sources）。对 ics：calendars（1 到 60 个，各带一个 key）、days、time_zone、private_title、include、exclude。include 和 exclude（各 1 到 20 个关键词，每个 1 到 100 个字符，与事件标题匹配）也是 microsoft365、google_calendar 和 momentus 的设置。 对 csv 和 json：url、method（GET 或 POST）、body 或 graphql、headers、auth（none、bearer、header、basic、oauth2、token_request）、time_zone、pagination，对 json 还有 format（auto、json、csv、xml）。 |
| secrets（可选，object） | 按名称存放的凭据，加密封存。对 ics：calendar_url.<key>，即日历的地址（webcal://、https:// 或 http://），每个日历一个。对 csv 和 json：token、password、client_secret、header.<Name>（请求头）和 query.<name>（查询参数），以及 token_request 请求体以 {{secrets.<name>}} 读取的密钥。 对于预设：其 secrets 列表给出的名称。 |
| refresh_seconds（可选，integer） | 两次同步之间的秒数；省略或低于下限时采用该类型的默认值和下限（ics：300，至少 60；momentus：60，至少 30）。最小值：30 最大值：86400 |
| stale_after_seconds（可选，SourceStaleAfter） | 数据源无法刷新时，卡片保留其最后一次正常数据的时长，单位为秒。 数据源写入的文档会在最后一次成功刷新后经过这段时间过期：若持续失败，文档会在所有屏幕（包括离线屏幕）上变空，可见性取决于数据的页面会切换到其后的页面；没有失败的数据源会在刷新时顺延截止时间。 至少为 refresh_seconds 的两倍。null 会保留最后一次正常的数据，直到数据源再次刷新（除 momentus 外所有类型的默认值；momentus 在创建时省略该成员则为 1800）。失败的数据源超过该时长后即为已过期（status.stale），并追加 source.stale。 |
| 启用（可选，布尔值） | 默认：true |
请求模板和响应
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/sources'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 201 | 已创建。 | Source（application/json）；头信息：Location, ETag, Cache-Control |
| 400 | 带字段错误的 invalid_request（config.calendars[0].key、secrets.calendar_url.lobby，预设为 settings.channel），或在缺少该类型或预设所需密钥时返回 source_secret_required。 | 问题 (application/problem+json) |
| 402 | feature_not_in_plan — Square、Shopify、Microsoft 365 或 Google Workspace 会议室数据源需要已连接数据源（Plus），Momentus 数据源需要 Momentus 数据源功能（Enterprise）；该问题指明功能和 required_plan。按地址添加的日历、Google Sheets、CSV 和 JSON 数据源每个计划都包含。 | 问题 (application/problem+json) |
| 409 | source_target_taken（该卡片已有数据源，source_id 指出它）、source_limit_reached 或 idempotency_mismatch。 | 问题 (application/problem+json) |
| 422 | source_target_unsupported；supported_cards 列出该类型可以填充的卡片类型。 | 问题 (application/problem+json) |
| 默认 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
测试数据源
预览数据源，不保存也不写入任何内容：获取地址，按目标卡片的需要转换响应，并用卡片校验文档，然后返回文档、卡片是否接受它（valid；若不接受，validation_error 会指出路径）以及本次运行的警告和计数。
传入 source_id 可用其余成员作为覆盖值来测试已保存的数据源（settings 会覆盖由预设创建的数据源自己的 settings）；否则必须提供 target，以及 kind 和 config，或者 preset、settings 和 secrets。已保存数据源保留的密钥按存储值使用，除非覆盖值改变了它指向的位置（source_secret_required）。
获取或整形失败会返回 source_test_failed，并附带固定的 source_error。每个组织每分钟最多 30 次预览。
请求主体字段
| 字段 | 描述 |
|---|---|
| source_id（可选，string） | 要测试的已保存数据源；其他成员会覆盖它。 |
| kind（可选，SourceKind） | 数据来源。ics 读取 iCalendar 和 webcal:// 地址（其他类型见 /docs/sources）。不可用的类型会在 kind 上返回 invalid_request。允许：“ics”、“sheets”、“csv”、“json”、“microsoft365”、“google_calendar”、“square”、“shopify”、“momentus”、“toast” |
| target（可选，SourceTarget） | |
| config（可选，object） | |
| preset（可选，字符串） | 用于测试尚未保存的数据源的数据源预设；它的 settings 和 secrets 会代替 kind 和 config。pattern: "^[a-z][a-z0-9]*(-[a-z0-9]+)*$" |
| settings（可选，object） | 预设的设置；与 source_id 一起使用时，会覆盖已保存数据源的设置。 |
| secrets（可选，object） |
请求模板和响应
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/sources/test'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 预览结果。 | SourceTestResult（application/json）；头信息：Cache-Control |
| 400 | invalid_request 或 source_secret_required。 | 问题 (application/problem+json) |
| 402 | feature_not_in_plan — Square、Shopify、Microsoft 365 或 Google Workspace 会议室数据源需要已连接数据源（Plus），Momentus 数据源需要 Momentus 数据源功能（Enterprise）；该问题指明功能和 required_plan。按地址添加的日历、Google Sheets、CSV 和 JSON 数据源每个计划都包含。 | 问题 (application/problem+json) |
| 404 | 未找到 source_id 所指的已保存数据源。 | 问题 (application/problem+json) |
| 422 | source_test_failed（source_error 包含 code、message 和 upstream_status）或 source_target_unsupported。 | 问题 (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) |
获取数据源
一个数据源及其状态。ETag 即修订版，用于下次更改时的 If-Match。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| source_id | 路径 | 必填 | 项目某个数据源的 id。 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/sources/SOURCE_ID'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 一个数据源。 | Source（application/json）；头信息：ETag, Cache-Control |
| 404 | not_found. | 问题 (application/problem+json) |
| 默认 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
更新数据源
更改数据源。config 会替换整个配置；secrets 会合并（字符串用于设置或替换，null 用于删除）。
由预设创建的数据源接受 settings 而不是 config：指定的每个设置会替换其值，null 会移除可选设置，其余保持不变，并且配置会根据预设重新构建（对这样的数据源提供 config 会在 config 上返回 invalid_request，对其他数据源提供 settings 会在 settings 上返回 invalid_request）。它的密钥按预设所规定的名称命名。
未发送的密钥保留原值，除非此次更改使数据源指向了其已存储作用域之外的位置（secrets.<name> 处的 source_secret_required：请重新输入）。
更改目标、config、密钥、refresh_seconds 或 enabled 会重置失败次数，并在几秒内运行数据源；重命名则不会。enabled 设为 false 会停止计划，卡片保留最后一份文档。If-Match 用于保护修订版。会追加 source.updated。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| source_id | 路径 | 必填 | 项目某个数据源的 id。 |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求主体字段
| 字段 | 描述 |
|---|---|
| 名称（可选，字符串） | minLength：1 maxLength：80 |
| target（可选，SourceTarget） | |
| config（可选，object） | 替换整个配置。由预设创建的数据源改为接受 settings。 |
| settings（可选，object） | 对于由预设创建的数据源：合并到其 settings 中（值会替换原值，null 会移除可选设置），并且配置会重新构建。 |
| secrets（可选，object） | 合并到已存储的密钥中：字符串用于设置或替换，null 用于删除。由预设创建的数据源按预设的命名来命名它们。 |
| refresh_seconds（可选，integer） | 最小值：30 最大值：86400 |
| stale_after_seconds（可选，SourceStaleAfter） | 数据源无法刷新时，卡片保留其最后一次正常数据的时长，单位为秒。 数据源写入的文档会在最后一次成功刷新后经过这段时间过期：若持续失败，文档会在所有屏幕（包括离线屏幕）上变空，可见性取决于数据的页面会切换到其后的页面；没有失败的数据源会在刷新时顺延截止时间。 至少为 refresh_seconds 的两倍。null 会保留最后一次正常的数据，直到数据源再次刷新（除 momentus 外所有类型的默认值；momentus 在创建时省略该成员则为 1800）。失败的数据源超过该时长后即为已过期（status.stale），并追加 source.stale。 |
| 启用（可选，布尔值） |
请求模板和响应
curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/sources/SOURCE_ID'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 更改后的数据源。 | Source（application/json）；头信息：ETag, Cache-Control |
| 400 | invalid_request 或 source_secret_required。 | 问题 (application/problem+json) |
| 402 | feature_not_in_plan — Square、Shopify、Microsoft 365 或 Google Workspace 会议室数据源需要已连接数据源（Plus），Momentus 数据源需要 Momentus 数据源功能（Enterprise）；该问题指明功能和 required_plan。按地址添加的日历、Google Sheets、CSV 和 JSON 数据源每个计划都包含。 仅替换密钥的更改（单独提交或与 enabled false 一同提交）始终允许，因此令牌已过期的数据源仍保持最新。 | 问题 (application/problem+json) |
| 404 | not_found. | 问题 (application/problem+json) |
| 409 | source_target_taken 或 idempotency_mismatch。 | 问题 (application/problem+json) |
| 412 | revision_conflict。 | 问题 (application/problem+json) |
| 422 | source_target_unsupported. | 问题 (application/problem+json) |
| 默认 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
删除数据源
删除数据源。卡片保留该数据源写入的最后一份文档。If-Match 用于保护修订版。会追加 source.deleted。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| source_id | 路径 | 必填 | 项目某个数据源的 id。 |
| If-Match | header | 可选 | 可选正资源修订。省略则写入当前资源；提供的过期修订为 revision_conflict。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求模板和响应
curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/sources/SOURCE_ID'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 204 | 已删除。 | 无正文 |
| 404 | not_found. | 问题 (application/problem+json) |
| 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) |
获取数据源的房间
读取预订系统房间的数据源（类型 momentus）的房间映射：它提供但没有任何屏幕显示的房间（summary.unmapped_rooms），以及读取房间或区域文档却没有指向其中之一的值的屏幕（状态为 missing 或 unknown 的屏幕；当值是写法不同的房间时会给出建议）。
房间取自数据源最后一次成功刷新，不会获取任何内容。没有房间的类型返回 source_has_no_rooms。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| source_id | 路径 | 必填 | 项目某个数据源的 id。 |
请求模板和响应
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/sources/SOURCE_ID/rooms'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 房间映射报告。 | SourceRooms（application/json）；头信息：Cache-Control |
| 404 | not_found. | 问题 (application/problem+json) |
| 409 | source_has_no_rooms. | 问题 (application/problem+json) |
| 默认 | 稳定的 RFC 9457 问题响应。421 server_draining 携带 1 秒的 Retry-After，500 not_ready 或 dependency_unavailable 携带 5 秒，500 manifest_degraded 携带 60 秒，除非处理程序设置了更具体的值。 | 问题 (application/problem+json) |
立即同步数据源
立即在线同步数据源（最长 60 秒），并返回其新状态。同步失败时会返回 200，其中 status.state 为 error 并附带错误；它绝不会写入。刷新会让数据源从头开始：失败次数清零，并完整读取地址。当计划的同步正在占用该数据源时返回 source_busy (Retry-After)。
每个数据源每分钟最多同步 6 次。
参数
| 名称 | 发送 | 必需？ | 描述 |
|---|---|---|---|
| source_id | 路径 | 必填 | 项目某个数据源的 id。 |
| Idempotency-Key | header | 可选 | 省略以进行新操作。提供并重用密钥以去重重试；CLI 自动管理密钥。 |
请求模板和响应
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/sources/SOURCE_ID/refresh'响应
| 状态 | 含义 | 正文和头部 |
|---|---|---|
| 200 | 同步后的数据源。 | Source（application/json）；头信息：ETag, Cache-Control |
| 404 | not_found. | 问题 (application/problem+json) |
| 409 | source_busy. | Problem（application/problem+json）；头信息：Retry-After |
| 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) |