架构索引

架构索引

• AccessLevel — 必填: none

  读取（只读）< 提议 < 管理。提议可以读取、贡献（媒体、备注、评论、支持、反馈、截图、广告草稿），并将播放列表和屏幕更改转化为审核（docs/reviews.md）。

• AccessLimitedBy — 必填: none

  为什么 effective_access 低于凭证访问权限。项目 - 项目要求对智能体更改进行审核。人员 - 智能体的负责人是无法批准审核的成员。

• AdslotPageWrite — 必填: id, type, adslot_id

  整页广告位。最多 16 个广告位页面，至少一个无可见性的普通页面是服务器检查，不在此表达。

• AdvertisingAvailability — 必填: estimated_plays, booked_plays, available_plays, screens, observed_from, observed_to, flight_start, flight_end

  估算值：目标屏幕在观察窗口内产生的广告位出现次数，按投放期推算，再减去同一批屏幕上其他直接目标仍需的播放次数。

• AdvertisingAvailabilityQuery — 必填: flight_start, flight_end
• AdvertisingCampaign — 必填: id, revision, name, state, pause_reasons, price_change_pending, daily_cap_mcr, lifetime_cap_mcr, reserved_mcr, spent_mcr, flight_start, flight_end, networks, created_at, updated_at
• AdvertisingCampaignDraft — 必填: name, daily_cap_mcr, lifetime_cap_mcr, flight_start, flight_end, networks
• AdvertisingCampaignList — 必填: campaigns
• AdvertisingCampaignNetwork — 必填: seller_project_id, membership_id, admission_generation, screen_ids, slot_ids, creative_ids, network_cap_mcr, network_reserved_mcr, network_spent_mcr, accepted_pricing_generation, price_change_pending, barrier_generation, enabled
• AdvertisingCampaignNetworkDraft — 必填: seller_project_id, screen_ids, slot_ids, creative_ids
• AdvertisingCategory — 必填: none

  广告主类别。同一类别的两则广告不会在屏幕的同一个广告时段内播放；没有类别的广告不会被分隔。

• AdvertisingCreative — 必填: id, revision, media_id, media_revision, sha256, kind, content_type, duration_ms, width, height, bytes, state, created_at
• AdvertisingCreativeCreate — 必填: media_id
• AdvertisingCreativeList — 必填: creatives
• AdvertisingCreativeReview — 必填: id, seller_project_id, creative_revision, state, created_at
• AdvertisingDaypart — 必填: start, end
• AdvertisingDeliveryReport — 必填: gross_mcr, fee_mcr, net_mcr, completed, interrupted, unbillable, rows, coverage
• AdvertisingDeliveryRow — 必填: screen_id, slot_id, reservation_id, gross_mcr, fee_mcr, net_mcr, completed_at
• AdvertisingDirectCampaign — 必填: id, revision, name, advertiser, state, flight_start, flight_end, reserved_plays, delivered_plays, media_ids, image_duration_ms, screen_ids, slot_ids, venue_types, cities, tags, dayparts, overbooked, pace, created_at, updated_at
• AdvertisingDirectCampaignDraft — 必填: name, advertiser, flight_start, flight_end, media_ids

  直接广告活动：卖方为外部广告主在自己的广告库存上达成的交易。不涉及资金往来。

• AdvertisingDirectCampaignList — 必填: direct_campaigns
• AdvertisingDirectPace — 必填: status, expected_plays

  相对于目标的投放进度，目标在投放期内均匀累计。

• AdvertisingDirectPrice — 必填: model, amount, currency

  卖方记录的交易价格。screenRIG 从不收取该费用；它用于计算报告的价值。

• AdvertisingDirectReport — 必填: campaign_id, name, advertiser, from, to, delivered_plays, reserved_plays, pace, plays, played_ms, not_played, rows
• AdvertisingDirectReportRow — 必填: day, screen_id, slot_id, media_id, plays, played_ms
• AdvertisingDirectValue — 必填: model, amount, currency

  应用于已投放播放次数的记录价格：cpm 按每千次播放计，flat 为整笔费用。

• AdvertisingFillStats — 必填: from, to, occurrences, direct, marketplace, vast, unfilled, fill_rate, unfilled_reasons, days

  卖方在与请求窗口重叠的所有UTC小时内的广告位供给：请求的出现次数、按来源的填充及带有首次请求原因的未填充出现次数。请求最长35天；有效边界可覆盖35天加1小时。

• AdvertisingFillStatsDay — 必填: day, occurrences, direct, marketplace, vast, unfilled, fill_rate
• AdvertisingInventory — 必填: screen_id, revision, ads_enabled, audience_tags, rate_override_mcr_per_15s, rate_revision, created_at, updated_at
• AdvertisingInventoryList — 必填: inventory
• AdvertisingInventoryWrite — 必填: ads_enabled
• AdvertisingJoinedInventory — 必填: inventory, slots
• AdvertisingJoinedNetwork — 必填: seller_project_id, membership_id, policy, admission_generation, scope, price_change_pending, default_rate_mcr_per_15s
• AdvertisingJoinedNetworkList — 必填: networks
• AdvertisingMembership — 必填: id, seller_project_id, admission_generation, policy_revision, policy, scope, state, revision, created_at, updated_at
• AdvertisingMembershipList — 必填: memberships
• AdvertisingMembershipScope — 必填: policy, screen_ids, slot_ids
• AdvertisingNetwork — 必填: id, revision, enabled, rate_revision, pricing_generation, seller_fee_bps, seller_fee_revision, created_at, updated_at
• AdvertisingNetworkCreate — 必填: name
• AdvertisingQuote — 必填: id, campaign_id, campaign_revision, revision, state, expires_at, items, pricing_generations, created_at
• AdvertisingQuoteAccept — 必填: quote_id
• AdvertisingQuoteItem — 必填: seller_project_id, screen_id, slot_id, creative_id, duration_ms, rate_mcr_per_15s, play_price_mcr, pricing_generation, fee_bps, fee_revision
• AdvertisingRate — 必填: rate_mcr_per_15s
• AdvertisingReportCoverage — 必填: mode, outcomes_complete

  播放结果计数覆盖。货币总额始终来自不可变结算。outcomes_complete 为假时，计数为观察到的下限，缺失历史不可用，不是零。

• AdvertisingReview — 必填: id, creative_id, creative_revision, state, created_at
• AdvertisingReviewDetail — 必填: review, creative
• AdvertisingReviewList — 必填: reviews
• AdvertisingReviewRejection — 必填: reason
• AdvertisingScope — 必填: screen_ids, slot_ids
• AdvertisingSellerCampaign — 必填: id, buyer_project_id, name, state, flight_start, flight_end, screen_ids, slot_ids, creative_ids, review_state, enabled, price_change_pending, updated_at

  仅投影到调用卖方网络上的已提交买方广告活动。

• AdvertisingSellerCampaignDelivery — 必填: completed, reserved_mcr, gross_mcr, fee_mcr, net_mcr

  调用卖方网络上累计已结算的播放次数和金额，以及当前的保留金额。

• AdvertisingSellerCampaignDetail — 必填: campaign, delivery
• AdvertisingSellerCampaignList — 必填: campaigns
• AdvertisingSlot — 必填: id, revision, name, enabled, accepted_media, max_image_duration_ms, max_video_duration_ms, muted, rate_override_mcr_per_15s, rate_revision, created_at, updated_at
• AdvertisingSlotList — 必填: slots
• AdvertisingSlotWrite — 必填: name, accepted_media, max_image_duration_ms, max_video_duration_ms
• AdvertisingSpendReport — 必填: campaign_id, spent_mcr, reserved_mcr, completed, unbillable, pending, coverage
• Agent — 必填: id, name, agent_type, capabilities, state, authenticated_requests, metered_credits, created_at
• AgentCapability — 必填: none

  一个代理凭证能力区域。凭证铸造时能力固定；要更改，需连接新代理并断开旧代理。规范顺序为此枚举顺序；能力列表永不包含重复项。

• AgentConnection — 必填: connection_id, name, agent_type, status, capabilities, expires_at, created_at
• AgentDisconnectRequest — 必填: none
• AgentInput — 必填: none
• AgentList — 必填: items
• AgentScreenScopeUpdate — 必填: screen_scope
• AgentSelfStatus — 必填: agent, connection_ready
• Alert — 必填：id, screen_id, condition, state, since, muted, attention

  持续期间的一个屏幕条件。读取方会把未知条件当作无法命名的条件处理。

• AlertAcknowledge — 必填: none
• AlertActor — 必填: kind, id
• AlertList — 必填：items, next_cursor, counts
• AlertMute — 必填：id, screen_ids, tags, until, created_at
• AlertMuteList — 必填: items
• AlertMuteWrite — 必填：until

  至少一个屏幕 ID 或标签。

• AppStoreNotificationAcknowledgement — 必填: acknowledged
• AppStoreNotificationRequest — 必填: signedPayload
• AppStoreOffer — 必填: account_token, products, education_eligible, education_eligibility_source, can_purchase, current_plan_id, subscription
• AppStoreProduct — 必填: product_id, plan_id
• AppStoreSubscription — 必填: organization_id, plan_id, product_id, original_transaction_id, environment, expires_at, auto_renews, status

  组织的 App Store 订阅。

• AppStoreTransactionRequest — 必填: signed_transaction
• Application — 必填: id, name, revision, created_at, updated_at
• ApplicationEventContext — 必填: primitive_id, code
• ApplicationEventReport — 必填: severity, code, context
• ApplicationList — 必填: items
• ApplicationPlacement — 必填: playlist_id, playlist_name, page_id, primitive_id, release_id, release, controller, rect, canvas, screen_count

  一个播放列表某一页面上的一个应用原语。

• ApplicationRename — 必填: name
• ApplicationUploadCommit — 必填: sha256, compressed_bytes

  再次命名已声明的归档；命名其他字节的提交以 invalid_request 被拒绝。

• ApplicationUploadDeclaration — 必填: sha256, compressed_bytes, expanded_bytes, file_count

  声明一个由 CLI 生成的 tar.gz，附带流式上传作为头信息发送的元数据。

• ApplicationUploadSession — 必填: id, application_id, release_id, operation, upload_url, method, headers, expires_at
• ApplicationUsage — 必填: placements, screens
• ArchivedProjectDevice — 必填: screen_id, label, host
• AuditActor — 必填: kind
• AuditActorKind — 必填: none
• AuditClient — 必填: kind
• AuditEntry — 必填: id, scope, at, actor, source, action, resource, changes
• AuditFieldChange — 必填: path, before, after
• AuditHead — 必填: scope, seq, hash, floor_seq, floor_hash, unsealed, format
• AuditList — 必填: items, next_cursor
• AuditProblem — 必填: seq, code, detail
• AuditResource — 必填: type
• AuditRevision — 必填: type
• AuditSource — 必填: none

  变更的来源界面：仪表板会话、HTTP API、screenrig CLI、MCP 工具调用、持有写入租约的员工、已签名的设备调用、传入的 Webhook，或服务器自身（应用已批准变更的工作进程）。

• AuditVerifyResult — 必填: ok, scope, checked, head, problems
• AutoTopUpDisabledSettings — 必填: enabled

  关闭会保留已保存的金额和本月支出。可选的金额字段会被忽略，包括未完成的草稿。

• AutoTopUpEnabledSettings — 必填：enabled, threshold_cents, amount_cents, monthly_limit_cents
• AutoTopUpSettings — 必填: none
• AutoTopUpView — 必填：enabled, threshold_cents, amount_cents, monthly_limit_cents, paused, this_month_cents
• BIBrowse — 必填: items, next_cursor

  Grafana: dashboards (uid, title, folder, tags), or with dashboard set that dashboard's panels (id, title, type) and the dashboard itself. Power BI: workspaces (id, name), or with workspace set that workspace's reports (id, name, embed_url) and the workspace itself. Tableau: views (path as Workbook/View, name).

• BICheck — 必填: name, ok
• BIConnection — 必填: id, project_id, kind, name, config, embed_origin, secret, last_test, revision, created_at, updated_at

  项目对某个 BI 系统的访问。每个连接只属于一个项目。

• BIConnectionConfig — 必填: none
• BIConnectionList — 必填: items, next_cursor
• BIConnectionPatch — 必填: none
• BIConnectionWrite — 必填: name, kind, config
• BISecret — 必填: set, hint

  已存储密钥的显示方式。密钥本身绝不会返回。

• BITarget — 必填: none

  视图显示的内容。带连接的 Grafana：dashboard_uid（以及可选的单个面板）。带连接的 Power BI：workspace_id 和 report_id，以及 pages 或 rotate_all_pages。带连接的 Tableau：view（Workbook/View），以及 rotate_sheets。带连接的 Web：url。不带连接时：只有 public_url（Tableau 还有 rotate_sheets）。

• BITestReport — 必填: at, ok, checks
• BIView — 必填: id, project_id, kind, name, target, refresh_s, rotate_s, fit, revision, status, embed_url, created_at, updated_at
• BIViewError — 必填: at, code, detail
• BIViewList — 必填: items, next_cursor
• BIViewPatch — 必填: none
• BIViewStatus — 必填: last_ok_at, last_error

  该视图上次在屏幕上的表现。仅在结果变化时才会变化。

• BIViewTest — 必填: at, ok, checks
• BIViewWrite — 必填: name

  设置 connection_id 时，url 与 target 只能二选一（Tableau 的 url 可以与仅含 rotate_sheets 的 target 同时出现；Web 视图只接受 url，不接受 target）；或者使用 kind（grafana、powerbi 或 tableau），并且只带 target.public_url。

• BIWebCookie — 必填: name, value, domain

  从已登录浏览器导出的 Cookie 集中的一个 Cookie。

• BIWebSession — 必填: state, cookies, cookies_updated_at, last_login_at, login_failures, retry_at

  Web 连接的 Cookie 和登录。state：idle（尚无内容；第一次截图会登录）、active、login_needed（页面显示了登录页；下一次截图会登录）、paused（一次登录未成功；下一次要等到 retry_at）、stopped（连续五次登录被拒绝；请更改凭据）或 expired（仅有 Cookie 的连接，其 Cookie 已失效；请给它一个新的 Cookie 集）。

• BIWebStep — 必填: action

  脚本化登录的一个步骤。goto：url（https，公开）。fill：selector 和 value。click 和 wait_for：selector。press：value，即 Enter 或 Tab 之类的按键名，以及可选的 selector（先聚焦）。wait_ms：ms。

  值中可以包含 {{username}}、{{password}} 和 {{otp}}，渲染器会根据登录信息填入；不要在值中放入密码或验证码，只放占位符。

• BillingBalance — 必填: wallet_revision, remaining_mcr, reserved_mcr, available_mcr, sources, withdrawal
• BillingPayer — 必填: kind, id
• BillingPaymentMethod — 必填：brand, last4, exp_month, exp_year
• BillingPayoutStatus — 必填: rails_available, unavailable_reason
• BillingPlanSubscription — 必填: subscription_id, plan, status, entitlement, cancel_at_period_end
• BillingPortalSession — 必填: url
• BillingSourceBucket — 必填: remaining_mcr, reserved_mcr
• BillingSources — 必填: nonredeemable, purchased, ad_earned
• BillingStatement — 必填: entries, next_cursor
• BillingStatementEntry — 必填: sequence, journal_id, kind, amount_mcr, amount_credits, amount_usd, occurred_at
• BillingUsageAllowance — 必填：storage_bytes, api_events, storage_mcr_per_gb_month

  单个付款方免费获得的内容，以规范十进制字符串表示。带宽从不收费，因此没有配额。

• BillingUsageAmounts — 必填：bandwidth_bytes, storage_mcr, api_events
• BillingWithdrawal — 必填: eligible_earned_mcr, amount_usd_cents, threshold_exclusive_usd_cents, allowed, blockers, rails_available
• BrowserLinkClaim — 必填: session_id, status, screen
• BrowserLinkClaimRequest — 必填: code
• BrowserLinkClaimScreen — 必填: id, public_id, state, public_url
• BrowserLinkEvent — 必填: session_id, status, event_id, expires_at
• BrowserLinkSession — 必填: session_id, code, display_code, status, expires_at
• BrowserLinkStatus — 必填: session_id, code, display_code, status, continuation_path, expires_at
• BrowserProvisioningCompletion — 必填: screen, public_url
• BrowserProvisioningExchange — 必填: provisioning_token, exchange_id
• CLIEnrollment — 必填: project, agent, connection_ready, token, issuance_id, issuance_expires_at, invitation
• CLIEnrollmentOAuth — 必填: project, agent, connection_ready, issuance_id, issuance_expires_at, invitation, access_token, token_type, expires_in, refresh_token, refresh_expires_at, scope

  以 oauth 凭证格式注册。注册的授权（客户端 screenrig-cli，在新项目上拥有所有权限的 Manage 身份访问）发出首个令牌对；在 issuance_expires_at 之前的精确重试返回相同令牌对，之后重试返回 credential_issuance_expired。

• CLIEnrollmentRequest — 必填: client_id
• Campaign — 必填: id, name, playlist_id, audience, priority, paused, reserved, revision, created_at, updated_at

  内容活动：在屏幕所在时区内，只要 from、until 和 windows 成立，audience 中的每个屏幕都显示 playlist_id。from、until 和 windows 均缺失表示始终生效。

• CampaignAudience — 必填: none

  活动定向的屏幕：all（每条规则都匹配）、any（至少一条匹配）、tag（屏幕带有该标签）、screen_id（该屏幕）或 folder（该屏幕文件夹及其内部每个文件夹中的屏幕，GET /api/screen-folders；该文件夹必须存在）中的恰好一个。

  规则最多嵌套 3 层，一个 audience 最多有 500 条规则。{"all": []} 表示项目的每个屏幕；在其他位置，all 和 any 至少列出一条规则。

• CampaignList — 必填: items
• CampaignPatch — 必填: none
• CampaignPreviewRequest — 必填: body
• CampaignPromote — 必填: revision
• CampaignReach — 必填: published, current, at, empty_groups

  受众匹配的活动屏幕数量；配对中的屏幕不计入。

  它统计的是受众匹配数，而不是活动实际播放的位置：没有默认播放列表的活动屏幕也会匹配，但不播放任何内容。published 是活动上次发布时的计数（创建时，或更新时受众、playlist_id 或 paused 不同）；current 是最新计数。

  活动屏幕的标签、文件夹或状态发生更改，或文件夹被移动后，大约在更改停止 15 秒后，会对受众中提到所更改内容的活动重新计数，并追加 campaign.reach_changed（published、previous、current；由发布触发时 republished 为 true）；对于受众中开始或停止匹配屏幕的每个标签或文件夹，还会追加 campaign.group_changed（kind、value、matched）；发布时若从受众中移除空标签或文件夹，则追加 removed 为 true、matched 为 0 的 campaign.group_changed。

  对于在引入触达之后既未发布也未重新计数的活动，则不存在。

• CampaignRevision — 必填: revision, created_at, change, current, campaign

  活动的一个已存储修订：某次写入之后的活动状态。change 说明它由什么产生：created、edited（更新或排程导入）、restored 或 promoted（更早修订的副本，由 restored_from 指明），或 baseline（活动历史开始时所持有的修订，早于任何已记录的写入）。

  读取方不认识的值按 edited 处理。

• CampaignRevisionList — 必填: items
• CampaignScreens — 必填: campaign_id, counts, items
• CampaignStatus — 必填: campaign_id, screen_id, status

  一个活动在一个屏幕上的状态。

  在 Player 解析并接收自身堆栈（schedule.stack）的屏幕上，满足时间条件的活动位于堆栈指定的位置：条带或主活动在其区域播放，显示器锁定在其目标显示器上播放；堆栈中没有的活动为 pending 或 blocked（playlist_unavailable）。playing：屏幕正在显示它。pending：它应当显示，且会在一分钟内切换。waiting：当前不在 from、until 或 windows 范围内（如果在八天内开始，next_start 表示开始时间）。ended：已过 until。outranked：它生效，但屏幕接管（reason takeover）或另一活动（reason campaign、by）获胜。conditional：它满足时间条件，并在仅由 Player 观察的条件也满足时播放（reason interaction：有人正在操作屏幕；data：其数据条件）。paused。blocked：它无法在此显示（reason no_default_playlist、no_timezone 或 playlist_unavailable：播放列表缺失、未经批准或不适合此屏幕；region_not_laid_out：未布局在此屏幕的任何显示器上，并被排除在堆栈之外（条带不适合任何目标显示器，或显示器锁定未指定屏幕的任何输出）；或 stack_only：屏幕的 Player 不解析自身堆栈，只有解析自身堆栈的 Player 才会遵循区域、显示器锁定、交互或数据条件）。not_in_audience。

• CampaignWrite — 必填: name, playlist_id, audience
• CanvasBackground — 必填: none

  纯正规范大写 #RRGGBBAA，或自上而下线性渐变。

• CanvasColor — 必填: none

  规范大写 sRGB RRGGBBAA。

• CapPull — 必填: none

  CAP 来源平台读取触发器，包含目标屏幕位置和计数警报：cap-alert 卡片放置参数（docs/feeds.md “CAP 警报”）。每个源 URL 每分钟为每个触发器和放置请求一次。

  如果没有来源，平台将读取覆盖该位置的公共信息源（NWS、加拿大 NAAD 和带有区号的 MeteoAlarm）。最严重的匹配警报会像推送消息一样完全接管目标屏幕；当来源显示无警报（取消或过期）时，拉取的警报结束。

  过期或失败的源不会结束警报。除非提供了 sources，否则 location 是必需的。

• Capabilities — 必填: api_version, protocol_version, application_compressed_bytes, application_expanded_bytes, application_package_bytes, application_file_count, application_file_bytes, application_path_depth, application_path_bytes, media_image_bytes, media_audio_bytes, media_video_bytes, playlist_max_pages, playlist_max_items_per_page, playlist_max_media_per_selector, transition_max_duration_ms, screens_per_project, project_content_bytes, founding_period_ends_at, features
• CardCatalogue — 必填: cards
• CardCreate — 必填: type, params
• CardDataEntry — 必填: key, document, bytes, sha256, revision, created_at, updated_at
• CardDataList — 必填: items, next_cursor
• CardDataSummary — 必填: key, bytes, sha256, revision, created_at, updated_at
• CardDataWrite — 必填: document
• CardDetails — 必填: id, major, version, params_schema, data_schema, feed, tier, layouts, example
• CardFile — 必填: src, sha256
• CardInstance — 必填: id, project_id, type, major, params, created_at, updated_at, revision
• CardKVWebhook — 必填: id, card_id, description, mapping, enabled, signing, url, created_at, updated_at

  写入卡片数据文档的传入 webhook。

• CardKVWebhookCreate — 必填: none
• CardKVWebhookList — 必填: items
• CardKVWebhookRotate — 必填: none
• CardKVWebhookUpdate — 必填: none
• CardKVWebhookWithSecrets — 必填: none
• CardKVWebhookWriteResult — 必填: status
• CardRequirements — 必填: cardml, features
• CardSummary — 必填: id, title, short, category, tags, tier, layouts, majors
• Comments — 必填: comments
• CommentsWrite — 必填: comments
• Connection — 必填: id, project_id, provider, mode, name, status, last_error, config, secret, last_test, revision, created_at, updated_at

  项目可重复使用的 Microsoft 或 Google 访问权限。数据源、Power BI 连接和 SharePoint 媒体同步账号，在 config.connection_id 中指明一个连接，而不是自带凭据。

• ConnectionCheck — 必填: name, ok, detail
• ConnectionConfig — 必填: none

  连接在密钥之外指明的内容；只包含其提供商和模式用到的成员。密钥、密钥文件或刷新令牌绝不会出现在这里。

• ConnectionConfigWrite — 必填: none

  Microsoft，own_app 模式：两个成员都要提供。Google 连接和 screenrig_app 模式不接受。

• ConnectionConsent — 必填: none

  附带一次性授权链接的连接，只有生成该链接的写入才会带有它：以 screenrig_app 模式创建连接，以及 POST /api/connections/{id}/connect。授权的人在 consent_expires_at 之前打开 consent_url。它是一次授权的链接：只发送给那个人。读取连接绝不会带有它。

• ConnectionError — 必填: code, message, at

  连接无法工作的原因。消息是一句固定的句子，Microsoft 还会加上 AADSTS 代码；它绝不会重复调用方发送的文本。

• ConnectionList — 必填: items, next_cursor
• ConnectionPatch — 必填: none
• ConnectionSecret — 必填: set, hint

  响应如何显示连接的密钥、密钥文件或刷新令牌。其值绝不会返回。

• ConnectionTest — 必填: at, ok, checks
• ConnectionWrite — 必填: provider, mode, name
• CreatedProject — 必填: project, organization
• CreditPurchase — 必填: id, status, amount_cents, credits, credited
• DashboardAgentAction — 必填: project_id
• DashboardApplicationPreviewLaunch — 必填: release_id, launch_url, expires_at
• DashboardApplicationSummary — 必填: count
• DashboardBalance — 必填: credit_remaining, credit_included, credit_reset
• DashboardBoot — 必填: none

  用于控制台外壳的一次请求。每个成员都是所指路由为这同一个会话返回的响应体；当该路由不会对其返回 2xx 时，该成员缺失。项目没有网络时，advertising_network 为 null。

• DashboardDisplayName — 必填: none

  修剪后的可打印显示名称，最多80个UTF-8字节。拒绝控制字符、URL样式文本、@、www.、://和凭证材料。绝不包含授权信息。

• DashboardEmail — 必填: email, email_verified, email_revision

  当前用户自己的电子邮件视图。验证地址在更改待处理时仍有效，待处理候选仅对其所有者可见。

• DashboardEmailVerificationAccepted — 必填: status
• DashboardHealthSummary — 必填: display_disconnected, hot, crashing, stale

  具有健康报告的活跃屏幕，按状态计数；一个屏幕可计入多个状态。display_disconnected、hot 和 crashing 仅计入最新报告为当前（非过期）的在线屏幕；stale 计入报告超过 35 分钟且无其他状态的在线屏幕。

• DashboardMe — 必填: user_id, display_name, email, password, passkeys, created_at
• DashboardMediaSummary — 必填: count, bytes

  会话所属项目的就绪媒体计数器。bytes 只统计已存储的媒体字节，不是项目的 used_bytes 总数（后者还包括发布树和键值条目）。image_bytes、video_bytes 和 audio_bytes 按原语拆分 bytes；只要 image、video 和 audio 是仅有的原语，三者之和就始终等于 bytes；如果今后存储了其他原语，三者之和会小于 bytes。

• DashboardMember — 必填: user_id, display_name, joined_at, passkeys, password, owner, external
• DashboardMemberList — 必填: items, viewer_user_id, viewer_is_owner
• DashboardPasskey — 必填: id, name, credential_id, provider, created_at, last_used_at
• DashboardPasskeyAssertion — 必填: ceremony_id, request_options
• DashboardPasskeyAssertionComplete — 必填: ceremony_id, credential
• DashboardPasskeyComplete — 必填: ceremony_id, credential
• DashboardPasskeyList — 必填: rp_id, user_handle, items
• DashboardPasskeyPatch — 必填: name
• DashboardPasskeyProof — 必填: type, ceremony_id, credential
• DashboardPasskeyRegistration — 必填: ceremony_id, creation_options
• DashboardPasswordLogin — 必填: email, password
• DashboardPasswordProof — 必填: type, password
• DashboardPasswordSet — 必填: password, proof
• DashboardPendingEmail — 必填: email, expires_at
• DashboardProject — 必填: status, created_at, email, screen_count, screen_limit, used_bytes, reserved_bytes, content_limit_bytes, event_retention_days, name

  一个项目的状态、联系地址、强制限制、使用情况、保留和公共全额度状态。内部计划标识符未公开。

• DashboardProjectList — 必填: items
• DashboardProjectListItem — 必填: id, name, last_used_at
• DashboardProjectReference — 必填: id, name
• DashboardProjectSwitch — 必填: project_id
• DashboardProof — 必填: none
• DashboardProofRequest — 必填: proof
• DashboardReauthentication — 必填: ceremony_id, options
• DashboardReauthenticationRequest — 必填: kind
• DashboardSSOProof — 必填: type

  凭最近一次单点登录给出的证明。当前会话在 10 分钟内通过组织的身份提供者登录时有效，不含仪式也不含密钥。否则该路由返回 reauthentication_required，人员需再次通过其提供者登录（POST /api/session/sso-starts，intent reauth）。

• DashboardScreenSummary — 必填: total, online, pairing_pending, active, archived

  会话项目的屏幕计数器。total 是 pairing_pending 加上 active，且不包括归档，匹配项目的 screen_count。online 来源于实时配对运行时事件流，完全等同于 Screen.online；它不是存储的布尔值，也不是播放器心跳。

• DashboardSession — 必填: user_id, display_name, email, project, auth_method, authenticated_at, expires_at, dev_auth, staff, shadow, passkey_enrollment_required, email_verification_required

  人员会话。标识符为描述性；会话 Cookie 建立权限。无项目的人员项目字段为 null。

• DashboardSessionOrganization — 必填: id, name, managed

  此人的主组织。

• DashboardSessionSSO — 必填: organization_id, provider_name, linked

  人员的单点登录上下文。只要人员的已验证地址所在域名的组织有身份提供者连接，就会出现；在人员通过该连接登录或关联之前，linked 为 false。SSO 会话自登录起持续 24 小时，不会因使用而延长。

• DashboardStaffWriteMode — 必填: request_id, project_id, expires_at
• DashboardSummary — 必填: screens, media, applications
• DeletedProject — 必填: id, screens, paired_screens_active, paired_screens_archived, paired_screens_completed_pending, agents, media, applications, playlists, memberships
• DemoRequestInput — 必填: email, country, screen_range, organization, budget, timezone, source, flow_id
• DemoResult — 必填: route, booking, review_requested, video_url, email, country, timezone, flow_id, source
• DemoSlots — 必填: slots, timezone
• DemoSource — 必填: none
• DeviceSessionRequest — 必填: none

  Cookie 配对浏览器铸造。主体可选。未知成员忽略（docs/player-compatibility.md §1.1）。

• DisplayWindow — 必填: days
• DocsPage — 必填: url, title, markdown, truncated, sections, corpus_commit
• DocsSearchResponse — 必填: results, corpus_commit
• DocsSearchResult — 必填: url, title, section, snippet, score
• EducationEligibilitySource — 必填: none

  谁决定了 education_eligible。staff 是员工的决定，无论结果如何都是最终的。school_email 是根据管理员已验证的 K-12 学校邮箱地址自动做出的判定（学校域名，如 k12.ca.us 或 sch.uk；绝不是 .edu 或 .ac.uk 这类通用教育域名）。空字符串表示尚无人决定。

• EmailVerifyRequest — 必填: token
• EmailVerifyResult — 必填: purpose, status
• EmptyPaymentRequest — 必填: none
• EnrollmentInvitation — 必填: id, status, expires_at
• Event — 必填: cursor, type, severity, message, at
• EventActor — 必填: user_id, display_name

  导致此变更的控制台用户。可选字段，且在每个由智能体、CLI、播放器或工作线程产生的事件中均不存在，因此该字段区分控制台变更，而非标记所有流量。仅为描述性归属，绝非授权。display_name是用户注册时选择的名称，未经验证。

• EventAgent — 必填: agent_id, name, agent_type

  仅当事件由经过身份验证的智能体持有者直接引起时，才存在安全的智能体主体归属。它绝不是授权。

• EventCommand — 必填: name, method

  导致此事件的代理请求。可选，且在仪表板用户、播放器或工作线程产生的每个事件中均缺失。仅为描述性归属，绝非授权。每个字段由服务器根据匹配的路由或问题注册表填写。

  命令对象不能携带参数向量、请求体、头部或调用者选择的任何文本，且故意没有对应字段。name 和 method 出现在每个智能体请求提交的事件中。

  结果字段仅出现在 agent.command 事件中，该事件记录未提交任何域事件的请求：已提交的域事件本身即证明请求成功。

• EventList — 必填: items, next_cursor
• FeedDocument — 必填: schema, fetchedAt, attribution
• FeedPending — 必填: key, state, retry_after_seconds
• FeedbackContext — 必填: none

  已关闭诊断信封。每个成员为可选受限标量，结构上不允许嵌套，未知成员将被拒绝并返回 invalid_request。该结构存在以防客户端持久化参数值、凭证或自由格式环境数据。

• FeedbackList — 必填: items
• FeedbackReplyWrite — 必填: text
• FeedbackResponse — 必填: id, text, status, created_at

  一个不可变的员工或代理回复。缺失作者标识为员工回复。纯文本（显示时需转义）；凭证形文本存储前替换为[已编辑]。

• FeedbackStatus — 必填: none

  员工对提交的处理状态。waiting_on_user 请求提交智能体提供信息；智能体回复可重新打开或关闭报告。"planned" 报告保持其状态。

• FeedbackSubmission — 必填: id, kind, title, body, created_at

  一个项目范围的提交。其自身字段（id、kind、title、body、context、created_at）写入后永不更改。status 在员工响应前为 open，之后为最新响应的状态；代理回复会重新打开等待输入或关闭的报告，“planned”报告保持其状态。

  响应是员工和智能体的回复，按时间从旧到新，最多 20 条，且不可编辑或删除。每条回复还会向项目事件流附加 feedback.responded 事件（resource.id 是提交 ID；详情包含 response_id、状态、fixed_in 和作者，仅限智能体回复，不含文本）。

  提交 ID 从不作为授权：只有所属项目可以读取。

• FeedbackWrite — 必填: title, body
• FleetLink — 必填: id, label, enabled, tags, screens_created, revision, created_at, updated_at

  一个播放器 URL，将打开它的每个设备变成该项目中的独立屏幕。

• FleetLinkList — 必填: items
• FleetLinkPatch — 必填: none
• FleetLinkWrite — 必填: label
• GroupBinding — 必填: binding_id, group_id, group_name, role, created_at
• GroupBindingCreate — 必填: group_id, role
• GroupBindingGroup — 必填: id, display_name, member_count
• GroupBindingList — 必填: bindings, groups
• HLSStreamSource — 必填: protocol, url
• HealthResponse — 必填: status
• HealthTrend — 必填: items, next_cursor
• HealthTrendHour — 必填: hour, screens_reporting, hot, display_disconnected, crashing
• HostContext — 必填: platform

  播放器运行的外壳和硬件，由播放器报告。HINT 指定设备名称；绝非凭证，绝非授权。仅 Ed25519 密钥授权。

  每屏幕存储，由携带的每个会话令牌替换，屏幕删除时删除，绝不写入操作日志，绝不在问题响应中回显，且仅返回给所有者项目。项目 API 只读；ScreenPatch 无法写入。

• HostDevice — 必填: none

  可选硬件标识符。duid 和 serial 是恢复提示咨询的唯一两个；播放器读取失败时省略该字段。

• IceServer — 必填: urls

  一个 RTCIceServer。端口 53 的 URL 已被移除，因为浏览器会阻止它们，且不会逐步传递候选。

• IdentityProvider — 必填: connection_id, kind, preset, name, jit, service_provider, ready_to_require, policy, revision, created_at, updated_at

  组织的单点登录连接。其中不含任何密钥。

• IdentityProviderCertificate — 必填: sha256, subject, not_after
• IdentityProviderOIDC — 必填: issuer, client_id, client_secret_set, scopes
• IdentityProviderOIDCWrite — 必填: client_id
• IdentityProviderSAML — 必填: idp_entity_id, idp_sso_url, certificates
• IdentityProviderSAMLWrite — 必填: none
• IdentityProviderServiceProvider — 必填: oidc_redirect_uri, saml_entity_id, saml_acs_url, saml_metadata_url

  要在身份提供者处输入的值，由控制台源和连接 id 派生。

• IdentityProviderTest — 必填: at, ok, subject_present

  通过该连接进行的最近一次测试登录的结果。

• IdentityProviderWrite — 必填: kind, preset, name, proof
• Invitation — 必填: id, kind, delivery, status, project_id, created_at, expires_at
• InvitationAcceptRequest — 必填: token, mode

  新凭证用于 create_login 和重置。链接 create_login 需要验证的注册 cookie，并使用其显示名和电子邮件。

  电子邮件 create_login 需要 display_name。signed_in 需在十分钟内登录，或将 invitation_accept 证明绑定到邀请 ID。buyer 仅适用于 ad_buyer；新 buyer 项目额度为零。

• InvitationAccepted — 必填: kind, project_id, next
• InvitationAdvertising — 必填: screen_ids, slot_ids, policy

  卖方拥有的范围：至少一个屏幕或广告位。仅屏幕、仅广告位或两者皆可。

• InvitationBuyer — 必填: none
• InvitationCreate — 必填: kind

  邮件投递需要电子邮件。链接投递仅限 project_member，不包含电子邮件和广告。ad_buyer 需要广告。每个组织最多可有 50 个未完成的成员和买方邀请；同类型同地址的未完成邮件邀请将被复用。

• InvitationCreated — 必填: invitations
• InvitationCredential — 必填: none
• InvitationEmailVerificationAccepted — 必填: status, expires_at
• InvitationEmailVerificationRequest — 必填: token, display_name, email
• InvitationInspect — 必填: id, kind, delivery, project, expires_at, person, modes, methods

  非消耗性检查。链接的 person 为 null。永不报告注册验证状态，但登录重置（其链接只发送到该地址）会说明完成它是否会替换未验证的账户（replaces_unverified_account）。电子邮件模式为 create_login 或 signed_in；链接提供两者，重置提供 reset。

• InvitationInspectRequest — 必填: token
• InvitationIssued — 必填: id, kind, delivery, status, project_id, created_at, expires_at
• InvitationKind — 必填: none
• InvitationList — 必填: items, next_cursor
• InvitationPasskeyOptionsRequest — 必填: token, mode
• InvitationPasswordCredential — 必填: type, password
• InvitationSignup — 必填: email, display_name, verified, expires_at
• InvitationStatus — 必填: none
• KVEntry — 必填: application_id, key, value_base64, content_type, bytes, sha256, revision
• KVList — 必填: items, next_cursor
• KVSummary — 必填: application_id, key, content_type, bytes, sha256, revision
• KVWebhook — 必填: id, application_id, key, description, url, created_at

  一个传入的键值webhook。其密钥仅由创建和轮换密钥操作返回。

• KVWebhookCreate — 必填: key
• KVWebhookDelivery — 必填: at, outcome, status, bytes, request_id
• KVWebhookDeliveryList — 必填: items
• KVWebhookList — 必填: items
• KVWebhookWithSecret — 必填: none
• KVWebhookWriteResult — 必填: key, revision, bytes, sha256, content_type, updated_at
• KVWrite — 必填: value_base64
• LevelDate — 必填: date

  一个具体的民用日期，全天，或像窗口一样介于 start 和 end 之间。它在 from 和 until 之间开始，且不是例外日期。

• LevelInteraction — 必填: none

  该层级在有人使用屏幕期间生效：从一次触摸、点击或按键开始，直到 idle_s 秒内没有任何输入。典型用法：叠在展示循环之上的交互页面。idle_s 会被存储并返回（省略时为 60）。

• LevelMonthly — 必填: none

  屏幕时区内的每月重复：day（1 到 31；没有该日的月份会跳过），或 nth（1 到 4，-1 表示最后一个）加 weekday。start 和 end 与窗口相同；重复归属于其开始的日期。

• LinearGradientBackground — 必填: type, stops

  从上到下线性渐变。无角度字段。stops 有 2 到 8 个条目，严格递增，范围在 [0, 1]，首个 at=0，末尾 at=1。

• LinearGradientStop — 必填: at, color

  自上而下线性画布背景上的一个停靠点。at=0 是顶部边缘，at=1 是底部边缘。

• LiveFrames — 必填: live_id, state

  实时会话帧适配器的进度。开放模式。

• LiveSession — 必填: state, screen_id, viewer_url

  屏幕的实时会话。开放模式。

• LiveStartRequest — 必填: none
• LiveViewer — 必填: viewer_id, live_id, offer, ice_servers, expires_at

  查看者的中继提议。开放模式。

• LiveViewerAnswer — 必填: answer
• ManifestActivatedContext — 必填: manifest_revision
• ManifestActivatedReport — 必填: severity, code, context
• ManifestUpgradeContext — 必填: manifest_revision, state
• ManifestUpgradePlaylist — 必填: id, name, revision

  已发布或排队的期望修订背后的播放列表身份：desired_playlist 使用其确切的期望授权或当前有效分配前的只读共享内容目标。active_playlist 始终使用确切的已确认历史授权，绝不使用更新的分配或内容编辑。id 加修订是操作员读取的播放列表版本，如目标 v42 / 播放 v41；name 是播放列表的显示名称，当播放列表不再存在或无法解析时为 null。

  缺失的历史活动授权为 null，绝非伪造修订。排队的期望目标不授予内容访问。

• ManifestUpgradeReport — 必填: severity, code, context

  会话屏幕的一个最新优先的清单升级生命周期快照。

  服务器为每个屏幕存储一个插槽，并从中派生项目读取模型 Screen.manifest_upgrade；接受过时、被替代或激活前报告，无更改（202），绝不因冲突拒绝，且无报告提升授权。严重性仅为信封级：派生项目事件严重性来自状态。

• McrString — 必填: none

  精确的整数毫信用额度，采用规范十进制字符串。1 额度等于 1000 mcr。

• Media — 必填: id, filename, primitive, content_type, operation_id, sha256, bytes, revision, state, created_at, updated_at
• MediaAvailability — 必填: none

  动态选择器何时可以选取该媒体，按每个屏幕的时区：处于 [from, until) 内，且在 windows、monthly 或 dates 的某次出现上（三者都没有：每天），其日期不在 except 中。即排程的层级语法，不含 data 和 interaction。

• MediaAvailabilityPatch — 必填: availability
• MediaCommit — 必填: content_type, bytes, sha256

  仅声明服务器可以逐字节重新验证存储对象的内容。此处不声明编解码器身份：服务器在异步验证期间从容器推导，因此客户端无法断言驱动播放器行为的编解码器。

• MediaFolder — 必填: id, name, parent_id, revision, created_at, updated_at

  一个媒体库文件夹。按文件夹选择的播放列表直接播放其内部准备好的文件，不包括子文件夹的文件。

• MediaFolderCreate — 必填: name
• MediaFolderList — 必填: items
• MediaFolderPatch — 必填: none
• MediaGenerationReference — 必填: none

  media_id 或 b64 中恰好一个。拒绝 HTTP URL。

• MediaGenerationRequest — 必填: prompt

  请求一张静态图像。提示为客户字节，绝不返回、记录或在项目 SSE 上发布。aspect_ratio 默认为 16:9。quality 为 low、medium 或 high，默认为 medium。tag 存储在就绪媒体对象上，类似上传标签。可选引用为内联 base64 或项目 media_id；拒绝 HTTP URL。

  一个请求中所有引用的总大小（包括内联和 media_id）不得超过 25165824 字节（24 MiB）；超过限制的请求将被拒绝。

  在 Standard 上，在入门底线（2027-01-01 前为负 1,000,000 额度，之后为零）之后，余额不足以覆盖静态图像供应商成本的两倍（向上取整为整数额度）时返回 payment_required，开发环境除外。其他套餐从不因余额被拒绝。

• MediaGenerationUsage — 必填: quality, credits, usd

  客户面向的单张静态图像扣费，即 media.generate 的 Operation 为 succeeded 时其 result 中的 usage。quality 是请求的质量，影响图像，不是固定价格。额度是该静态图像供应商成本的两倍，向上取整为完整 ScreenRig 额度。usd 是这些额度的美元等价。

  绝不包含供应商名称、供应商成本或令牌数。

• MediaList — 必填: items
• MediaMove — 必填: folder_id

  media_ids 和 folder_ids 中至少有一个 ID，总数最多 1000。

• MediaMoveResult — 必填: media, folders
• MediaReplace — 必填: upload_id
• MediaRestore — 必填: none
• MediaRestorePending — 必填: status, review, warnings
• MediaRestored — 必填: media, warnings
• MediaSelectorTagFilter — 必填: none
• MediaSelectorWeights — 必填: none

  加权选择器的占比，以媒体 ID 或 tag:NAME 为键。

  条目的权重是其媒体 ID 键（若存在）；否则取它所带标签中按字母顺序第一个 tag:NAME 键，该权重在所选条目中带有该键的条目之间平均分配，因此无论赞助商有多少素材，其占比都保持不变；否则该条目自成一组，权重为 1。

  每个完整周期中，每个条目恰好按其占比播放。

• MediaSingleTagPatch — 必填: tag
• MediaSync — 必填: id, project_id, account_id, provider, name, folder_id, every_s, state, source, next_run_at, revision, created_at, updated_at

  与一个媒体文件夹保持同步的一个源文件夹。

• MediaSyncAccount — 必填: id, project_id, kind, name, config, secret, state, revision, created_at, updated_at

  同步通过它读取：项目自己的 Microsoft Entra 应用的凭据（microsoft365）、某位用户与 Canva（canva）或 Dropbox（dropbox）的连接，或文件夹所共享给的 Google 服务账号（google_drive）。客户端密钥、令牌和服务账号密钥均加密封存，绝不会返回。

• MediaSyncAccountConfig — 必填: none
• MediaSyncAccountConnect — 必填: none

  附带一次性授权链接的账户：创建 Canva 或 Dropbox 账户以及 media sync account connect 的响应。Canva 或 Dropbox 账户的所有者需在 authorize_expires_at 之前，登录 Canva 或 Dropbox 后打开 authorize_url。它是一次授权的链接：只发送给那个人。读取账户绝不会带有它。

• MediaSyncAccountList — 必填: items, next_cursor
• MediaSyncAccountPatch — 必填: none
• MediaSyncAccountWrite — 必填: kind, name
• MediaSyncCheck — 必填: name, ok, detail
• MediaSyncDesign — 必填: id, title

  已连接的用户可以看到的 Canva 设计。

• MediaSyncDesignList — 必填: items, continuation
• MediaSyncList — 必填: items, next_cursor
• MediaSyncPatch — 必填: none
• MediaSyncRun — 必填: at, status, added, updated, removed, pending_delete, skipped_total

  同步最近一次运行的摘要。

• MediaSyncRunError — 必填: code, detail
• MediaSyncSecret — 必填: set, hint

  响应如何显示账户的客户端密钥、Canva 或 Dropbox 账户的令牌（连接后即已设置，不带 hint），或 Google Drive 账户自己的服务账号密钥（账户有密钥时即已设置；hint 为其 private_key_id 的后四位字符）。其值绝不会返回。

• MediaSyncSkipped — 必填: name, reason
• MediaSyncSource — 必填: web_url

  同步读取的来源，在创建同步时解析。SharePoint 文件夹有 drive_id 和 item_id；Dropbox 文件夹有 item_id 和 path；Google Drive 文件夹有 item_id、位于共享云端硬盘时的 drive_id，以及 shared_by；Canva 设计有 design_id 及其后的成员。

• MediaSyncTest — 必填: at, ok, checks
• MediaSyncWrite — 必填: provider, account_id
• MediaTagPatch — 必填: none
• MediaTagsPatch — 必填: tags
• MediaUploadDeclaration — 必填: filename, content_type, bytes, sha256

  声明一次上传。字节最大值是与计划无关的传输上限，不是可实现的大小。图像内容类型进一步限制为 20971520 字节，即 20 MiB，超过此大小的图像声明将在传输任何字节之前以 invalid_request 拒绝。

  该图像边界仅限字节：声明从不解码图像以强制执行，且对动画 GIF 和动画 WebP 的应用与静态图像完全相同。默认计划无产品存储限制。

  如有自定义存储上限，将首先检查该上限，无法容纳的声明会在传输任何字节之前被以 quota_exceeded 拒绝。

  没有剩余额度的 Standard 项目在 declare 和 commit 时会被 payment_required 拒绝，当其付款方存储的字节数加上本次上传超过 1000000000 字节（1 GB，即 Standard 的免费存储）时；带宽从不计费。

  音频/mpeg（MP3）声明限制为 178257920 字节，170 MiB，超出同样拒绝；读取 media_audio_bytes 预检。

  video/mp4 或 video/webm 声明受项目套餐限制：Standard 为 500000000 字节，500 MB，其他所有套餐为 1000000000 字节，1 GB；超出同样拒绝，并说明适用的限制；读取 GET /api/project/capabilities 中的 media_video_bytes 预检。

  更改套餐只影响之后的声明：已存储的视频继续播放。读取 capabilities 文档中的 media_image_bytes 预检图像限制，及 project_content_bytes 或项目的 content_limit_bytes 了解自定义存储上限。可选标签存储在准备好的媒体对象上，提交时不重新声明。

  可选的source_filename记录客户端转码上传前的原始文件名；准备好的对象的文件名由此派生，确保不同来源不会冲突（photo.png上传为photo.webp存储为photo.png.webp，photo.jpg为photo.jpg.webp，源photo.webp保持photo.webp）。

• MediaUploadSession — 必填: id, operation, upload_url, method, headers, expires_at
• MediaUploadSource — 必填: filename, content_type, sha256, bytes

  当摄取归一化 EXIF 方向时验证原始上传身份。只读；用于识别重试。准备好的媒体摘要、大小和类型描述归一化交付字节。

• MediaUsage — 必填: playlists, screens
• MediaUsagePlaylist — 必填: id, name, uses, screen_count
• MediaUse — 必填: kind, where

  一个播放列表引用或触及该媒体文件的一种方式；同一播放列表在多个页面上以同样方式使用，只算一次使用。

• MediaVersion — 必填: number, current, filename, content_type, sha256, bytes, source, created_at
• MediaVersionActor — 必填: kind
• MediaVersionPage — 必填: items, next_cursor
• MediaWarning — 必填: code, detail, playlists
• MediaWarningPlaylist — 必填: id, name
• MemberActivity — 必填: id, project_id, user_id, display_name, at, kind, action, outcome, status, source
• MemberActivityClient — 必填: kind

  客户端作为边缘请求日志所命名，从 User-Agent 和 Sec-CH-UA-Platform 解析。

• MemberActivityKind — 必填: none

  sign_in 和 sign_in_failed 包含 auth_method；credential_changed 表示添加、重命名或移除 passkey，设置密码，或请求/验证邮箱变更；reauthenticated 表示一次验证证明（操作 reauthentication.<proof kind>）；mutation 表示其他任何控制台更改。

• MemberActivityList — 必填: items, next_cursor, recorded_since
• MemberActivityOutcome — 必填: none

  状态码低于 400 为 ok，4xx 为拒绝，5xx 为失败。

• MemberActivityResource — 必填: type
• MemberApproverUpdate — 必填: can_approve
• MemberScreenScopeUpdate — 必填: screen_scope
• MemberUploadScopeUpdate — 必填: upload_scope
• NativeIdentityChallenge — 必填: nonce, expires_at, aud, op, request_hash

  在签名前比较返回的op和request_hash与本地计算值。每个随机数120秒后过期且只能使用一次。

• NativeIdentityChallengeRequest — 必填: kid, op, request_hash

  为每个挑战提供操作及其 request_hash。未知密钥还需提供 public_key 和 op=pairing.start。创建挑战不会注册密钥。

• NativeIdentityProof — 必填: kid, public_key, signature

  紧凑JWS保护头正好是{"alg":"EdDSA"}。声明包括kid、nonce、aud=screenrig-runtime、op、整数iat/exp、非空jti和request_hash。

  上下文证明最长持续 120 秒，且不晚于其发出挑战时过期。request_hash 是以 screenrig.native.identity.request.v1 和操作符开头，使用 UTF-8 字符串以单个 NUL 连接，无尾部 NUL 的小写 SHA-256 十六进制。

  追加 Idempotency-Key 用于 pairing.start 和 session.mint；追加精确的 srp_ 配对凭证然后 completion_nonce 用于 pairing.complete；identity.reset 不追加。每个证明必须包含 request_hash。缓存的操作结果仍需新发证明或在其短期有效收据期间接受的精确证明。

  拒绝重复或未知的 JWS/JWK 成员、非规范 base64url 和非素数阶密钥。忽略未知请求体成员。

• NativeIdentitySessionRequest — 必填: kid, public_key, signature

  NativeIdentityProof 带 op=session.mint 及可选主机提示。存在的主机替换屏幕上存储的主机，因为固件和外壳版本会随屏幕寿命漂移。提示不影响授权；只有签名证明有效。

  忽略未知成员，主机和播放容错读取（docs/player-compatibility.md §1.1）。

• NativePairingComplete — 必填: completion_nonce, public_key, signature
• NativePairingCompletion — 必填: screen, public_url
• NativePairingFleetLink — 必填: status

  此配对会话中所呈现的舰队链接所做的操作。已认领和已恢复表示屏幕已被选中，播放器完成配对而不显示其代码。任何其他状态下，代码留在玻璃上供普通认领。

• NativePairingRecovery — 必填: offered

  仅当启动请求中的主机duid或序列号精确匹配绑定到不同密钥的一个现有屏幕时出现。无屏幕、标签或项目信息：该提议作为Screen.recovery_pending和screen.recovery_offered事件在项目端显示，且仅拥有项目可确认。

  当标识符模糊、匹配屏幕的密钥在最近十分钟内显示活跃，或该屏幕在滚动小时内已接受三次报价时，均视为无匹配而缺失。配对码仍按无匹配方式发放和显示。播放器仅用于记录 pairing.recovery_offered。

• NativePairingSession — 必填: code, pairing_credential, expires_at
• NativePairingStart — 必填: kid, public_key, signature

  注册或定位器创建前需要私钥持有证明。签署绑定到精确Idempotency-Key的新鲜pairing.start挑战；未签名的启动将被拒绝。可选的主机对象是设备提示，不是凭证；在声明时存储于屏幕，可能在项目端开启恢复提议。

  忽略未知的主体成员。主机提示容错读取。未知主机键被忽略，格式错误的主机字段被丢弃，绝不拒绝（docs/player-compatibility.md §1.1.1）。

• NativeRuntimeSession — 必填: paired, capabilities, event_cursor, public_url, runtime_credential

  运行时拥有的本地会话（docs/player-compatibility.md §8）。读取器忽略未知成员和未知能力值。仅向授权覆盖的新成员发送。

• NextAction — 必填: command, reason
• Note — 必填: id, body, about, state, author, created_at, confirmed_at, review_at, expires_at, resolved_at, resolution, due

  项目备注。上下文由智能体编写，绝非指令或批准；正文以纯文本呈现。

• NoteAbout — 必填: type, id
• NoteAuthor — 必填: agent_id, name, agent_type

  添加备注时的写入代理。归属，不是权限。

• NoteCounts — 必填: open, new, due

  项目未解决备注及其中多少是新出现且需处理的。

• NoteList — 必填: items, next_cursor, review, counts
• NotePage — 必填: items, next_cursor
• NoteResolution — 必填: cause, reason, by
• NoteResolve — 必填: reason
• NoteResolvedBy — 必填: kind, id, name

  谁解决了备注。agent_type 表示智能体。归因，不是权威。

• NoteWrite — 必填: body
• Notification — required: id, channel, conditions, screen_tags, hold_minutes, enabled, revision, status, created_at, updated_at

  组织的通知，以项目或组织读取时的形式呈现。它覆盖组织的所有项目或所选项目（project_ids），并作用于每个被覆盖项目的屏幕、数据源、活动和卡片。

  项目可通过相同的 id 读取覆盖它的通知（当通知仅覆盖该项目时还可更改），并带有其自身的状态和失败时间；组织读取的是通知的完整内容。

  每个条件按屏幕分别跟踪：范围内的屏幕收到其事件时条件打开，持续满 hold_minutes 且该屏幕仍处于该状态时发出提醒；若条件在提醒发出后解除，随后会发出“已解决”提醒。

  在保持时间内解除的条件不发送任何内容；保持时间内其警报被确认或暂缓的条件，以及位于静音所覆盖屏幕上的条件，同样不发送。

  电子邮件：每位收件人会收到一封邮件，汇总约两分钟内到期的全部提醒，列出每个屏幕和条件，并附上指向控制台中该屏幕和此通知的链接；通知电子邮件免费。

  每封告警邮件和测试邮件都带有专属于其收件人的取消订阅链接（List-Unsubscribe 和 List-Unsubscribe-Post 标头，以及页脚），无需登录即可仅对此人停止该通知的邮件；参见 unsubscribed。

  Webhook：每条提醒以 JSON {type: alert.opened 或 alert.resolved, id, notification_id, project_id, condition, screen {id, name}, since, at, event_id, severity} 的形式 POST，其中 id 是投递 id，since 是条件开始的时间，at 是条件持续足够久（opened）或解除（resolved）的时间，event_id 是其背后事件的游标，severity（info、warning 或 error）对 alert.opened 是该条件的严重级别，对 alert.resolved 为 info，适用于每个 webhook 通知。

  活动的提醒还会携带 reach {published, current}（reach_dropped：活动发布时触达的屏幕数，以及发送提醒时触达的屏幕数）或 audience_group {kind: tag 或 folder, value: 标签或文件夹 id}（group_empty）；电子邮件和聊天消息会用文字表达同样的内容。

  设置了 min_severity 或 severity 的通知，也会在其电子邮件、Slack、Telegram 和 Teams 文本中写明。

  Teams 和 PagerDuty 始终显示实际严重级别。screen_offline 的 alert.resolved 还携带 likely_cause，即已结束的中断的原因（ScreenOutage.likely_cause），未知时为 null；它会在屏幕恢复后最多等待两分钟，待第一份健康报告判定，电子邮件中也会写明。

  重启会立即判定；网络或平台原因需要屏幕恢复后收到的健康报告，而 Player 最多可能在 15 分钟后才发送，因此在此之前发出的通知中该值为 null，原因会显示在 ScreenOutage.likely_cause 和 screen.outage_classified 中。

  电子邮件和聊天渠道会把在五分钟内进入同一状态、并共用网络、位置、型号、Player 版本或标签的三块或更多屏幕，作为一条通知、一次恢复来发送（NotificationDeliveryGroup）；其他屏幕的通知会以 grouped 跳过。

  Webhook 仍按每块屏幕发送一条通知。event_types 以与 GET /api/events 返回的相同 JSON 对象的形式 POST。

  每个 POST 请求都带有 ScreenRig-Webhook-Id（通知 id）、ScreenRig-Event-Id（提醒为投递 id，事件为事件游标；重试期间保持不变，请据此去重）、User-Agent，以及 ScreenRig-Signature t=<unix seconds>,v1=<hex HMAC-SHA256 over "<t>.<raw body>" keyed with the secret string>。

  10 秒内返回 2xx 响应即为成功；其他情况会按指数退避重试（间隔从 30 秒起逐次翻倍直至一小时，并加入随机抖动），持续 24 小时后标记为失败；电子邮件发送失败的重试方式相同。

  屏幕提醒和 screen.* 事件免费；其他事件按与 listen-stream 事件相同的方式计量。自 failing_since 以来若没有任何成功，status 即为 failing；连续失败 72 小时后，该通知会被禁用（disabled_reason 为 delivery_failures），并追加 notification.disabled。

• NotificationActiveHours — 必填: timezone, windows

  已开启提醒发出的时间：窗口（screenrig.schedule/v1），按 timezone 解读。窗口关闭期间到期的提醒会等到下一次开启（outside hold，默认），若届时条件仍然成立才发出，因此条件先行解除则不发送任何内容，或者被跳过（outside drop；last_error outside_hours）。

  已发送的已开启提醒对应的已解决提醒始终发出，无论是否在时段内，测试则忽略时段。crashing 与其他条件一样被保留或丢弃。时段在提醒首次发出时判定；失败的提醒按常规计划重试，不论时段。

  添加、更改或移除时段，会立即对为旧时段而保留的提醒重新判定。

• NotificationCondition — 必填: none

  重要的屏幕状态变化。screen_offline：播放器失去连接（screen.offline，在其在线状态失效 60 秒后写入）；在 screen.online 时解除。display_disconnected：播放器报告其显示器已断开（screen.health_changed，change 为 display_disconnected）；在 display_reconnected 时解除。running_hot：设备报告的温度达到或高于过热阈值（temperature_high）；在 temperature_normal 时解除。on_battery：设备带有电池，且其最新健康报告中的供电来源为 none，即未接通电源（screen.health_changed，change 为 on_battery）；当报告给出任何其他来源（plugged_in）时解除。

  该提醒说明屏幕正在使用电池供电，且不指明原因。storage_full：播放器的存储空间无法容纳其内容（screen.storage_shortfall）；在 screen.storage_shortfall_cleared 时解除。content_stuck：屏幕的内容更新正在重试、失败、受阻或不完整（screen.manifest_upgrade）；当后续状态不再是其中任何一种时解除。not_playing：播放器显示 error 级别的状态而不是其内容（level 为 error 的 screen.status_changed，storage_full 除外）；在其状态不再是 error 时解除。loop_stalled：播放器未报告任何异常且内容为最新，但后端已超过屏幕循环允许的时间没有收到任何媒体开始报告（播放判定为 stalled 的 screen.glass_changed；Screen.glass 会说明它何时判定、哪些情况不判定）；在收到媒体开始报告或屏幕不再被判定（例如离线）时解除。glass_blank 和 glass_frozen：后端读取了覆盖屏幕循环的一组截图，所有截图都是同一种纯色（glass_blank）或同一幅画面（glass_frozen）（画面判定为 blank 或 frozen 的 screen.glass_changed；Screen.glass 会说明它何时判定、哪些情况不判定）；在连续两张截图显示画面在变化或屏幕不再被判定时解除。

  不再被判定的屏幕会关闭警报，但电子邮件和聊天通知不会为它发送恢复通知，因为没有观察到任何恢复（已解决的行会以 no_longer_judged 跳过）；媒体开始播放或连续两张正常截图则会发送。crashing：播放器反复崩溃或重启其渲染器（screen.health_changed，change 为 crash_spike 或 renderer_restart_spike）；立即发送，不设保持时间，也不会发出“已解决”提醒。source_failed 和 source_stale 针对的是数据源，而不是屏幕：通知的 screen 成员携带数据源的 id 和名称，链接指向数据源的页面，screen_tags 从不匹配数据源，因此按标签限定范围的通知不会监视它们。source_failed：数据源的一次刷新失败（source.status_changed，state 为 error）；在下一次成功的刷新时清除（state 为 ok）。source_stale：数据源最近一次成功刷新早于其 stale_after_seconds，即其卡片数据过期、依赖它的页面回退的时间点（source.stale）；在下一次成功的刷新时清除。

  两者都不是屏幕警报。reach_dropped 和 group_empty 针对的是活动（排程栈的共享层级）而不是屏幕：提醒的 screen 成员携带活动的 id 和名称，链接是控制台中该活动的日历，而活动属于项目，因此 screen_tags 和 audience 永远不会限制它们。reach_dropped：重新计数发现活动触达的屏幕比上次发布时更少，原因是屏幕离开了其某个标签或文件夹，或被归档或删除（campaign.reach_changed，current 低于 published）；reach_drop 设定多大的减少才发出通知；当活动重新触达同样多的屏幕时解除。

  设定新基线的发布，或删除活动，同样会使其解除，这会关闭 pager 事件和 webhook 的警报，但不发送恢复邮件或聊天提醒 (no_longer_judged)。group_empty：活动受众的某个标签或文件夹不匹配任何屏幕（campaign.group_changed，matched 为 0）；每个标签或文件夹一条提醒 (audience_group)；当它再次匹配屏幕，或发布时将其从受众中移除（removed true）时解除，这会关闭 pager 事件和 webhook 的警报，但不发送恢复邮件或聊天提醒 (no_longer_judged)。

  屏幕自己的排程条目指向播放列表而不是屏幕，因此只有活动才有触达。

  两者都不是屏幕警报。card_data_stale 针对的是卡片而不是屏幕：提醒的 screen 成员携带卡片的 ID 和名称（卡片的类型，如“天气卡片”），链接是控制台中放置该卡片的页面的页面编辑器（没有页面放置它时是该通知自己的页面），since 是其数据过期的时刻。

  当智能体、作业或人写入了带有过期时间（ttl_seconds 或 expires_at，如 card data put --ttl）的卡片数据文档，并且在有屏幕显示该卡片期间，该文档到期时没有其他写入来续期时，它会打开（card.data_expired），因此卡片在该屏幕上为空白；当卡片数据的写入到达时，它会解除（card.data_renewed）。

  数据源的文档不会被通知：它们按数据源的过期时长过期，由 source_stale 覆盖。没有屏幕显示的卡片不会发送任何内容，在通知到期前已被续期、删除或从所有屏幕撤下的卡片也一样。

  删除卡片的数据会在不发送恢复通知的情况下结束该通知，就像发布会结束一次触达减少一样（no_longer_judged）。请按写入方的计划确定 ttl_seconds，以便发现已停止的作业。与数据源一样，卡片没有屏幕标签：限定于 screen_tags 的通知不会监视卡片，它也不是屏幕警报。

  读取方会将未知值视为不存在。

• NotificationConditions — 必填: none
• NotificationDelivery — required: id, notification_id, event_id, event_type, state, attempts, created_at
• NotificationDeliveryAttempt — 必填: attempt, at, status, error, duration_ms
• NotificationDeliveryAttemptList — 必填: items
• NotificationDeliveryGroup — 必填: id, attribute, value, count

  一条通知所代表的一组屏幕。当项目中至少三块屏幕在五分钟内进入同一状态并共用某个值时，电子邮件、Slack、Teams、PagerDuty 或 Telegram 通知会为它们发送一条通知，而不是每块屏幕一条。

  之后进入该状态的屏幕，若其值与已开启分组所依据的值相同，会加入该分组而不触发新通知；当分组的最后一块屏幕恢复时，由一条通知说明该分组。Webhook 通知仍按每块屏幕发送一条。

• NotificationDeliveryList — 必填: items, next_cursor
• NotificationDestination — 必填: none

  仅适用于 Slack、Teams、PagerDuty 和 Telegram，对它们必填。凭据须为服务签发的格式：slack 为传入 Webhook URL（hooks.slack.com）；teams 为 Workflows Webhook URL（logic.azure.com 或 powerplatform.com；Office 365 连接器 URL 已停用）；pagerduty 为 32 位 Events API v2 路由密钥；telegram 为机器人令牌。

  其他格式会返回 notification_destination_rejected。它会被加密封存，绝不会返回，读取时只以 destination_hint 的形式出现。

• NotificationEventTypes — 必填: none

  仅限 Webhook。项目事件发生时也会通过 POST 发送，格式与 Webhook 发送的完全一致：精确类型（如 screen.online），或以 .* 结尾的前缀（如 screen.*）。notification.test 绝不会被分发。

• NotificationList — 必填: items
• NotificationPatch — 必填: none
• NotificationProjectIDs — 必填: none

  组织的活跃项目，每个只出现一次。空列表不覆盖任何项目。

• NotificationReachDrop — 必填: none

  活动触达减少多少时发送 reach_dropped 提醒的最小值：screens 是最少失去的屏幕数（默认 1），percent 设置后是活动发布时所触达屏幕的最小占比；减少必须同时满足两者。

  较小的减少不会排入提醒，已排队的提醒如果到期时减少已低于该阈值，则会被跳过 (condition_cleared)。仅适用于 reach_dropped 条件；未带该条件的通知返回 invalid_request。

• NotificationRecipients — 必填: none

  仅限电子邮件。owner（提醒发送时该项目的所有者）或项目成员的 user_id；不是成员的 user_id 会返回 invalid_request。每位收件人都会通过其已验证的地址收到电子邮件。已离开项目或没有已验证地址的收件人会被跳过。

• NotificationSeverity — 必填: none

  提醒的严重级别，由低到高。已开启的提醒具有其条件的严重级别：screen_offline 为 error，其他每个条件为 warning，除非通知的 severity 另有设置。已解决的提醒和测试为 info。

• NotificationSeverityOverrides — 必填: none

  此通知的条件到严重级别的映射，例如 {"not_playing": "error"}。它计入 min_severity，也是 Teams 和 PagerDuty 为该条件显示的严重级别。未列出的条件保持其默认值。在补丁中，空对象与 null 一样，清除所有覆盖。

• NotificationTelegramChat — 必填: none

  仅适用于 Telegram，对其必填。要发布到的聊天：其数字 id（群组或频道为负数）或 @channelname。不是凭据。

• NotificationUnsubscription — 必填: user_id, at
• NotificationWrite — 必填: channel

  email 发送给收件人，webhook 以签名方式 POST 到 url，而 slack、teams、pagerduty 和 telegram 则借助只写的 destination（telegram 还需要 telegram_chat_id），针对每次中断、每块屏幕向聊天工具或寻呼工具发布一条消息，之后再发一条恢复消息；PagerDuty 会开启一个事件并将其解决。它们至少需要一个条件，且不接受 event_types。

• OAuthAuthorization — 必填: id, client_name, client_registered, redirect_host, access, capabilities, created_at, expires_at
• OAuthAuthorizationRedirect — 必填: redirect_uri
• OAuthError — 必填: error
• OAuthTokenResponse — 必填: access_token, token_type, expires_in
• OnboardingSiteCTA — 必填: label, path, href, at

  该人员在网站上点击的注册或登录链接。

• OnboardingSiteVisit — 必填: path, at
• OnboardingStepName — 必填: none

  入口流程中的一个步骤，按显示顺序排列。email_verified、email_gate_reached 和账户里程碑（agent_connected、screen_paired、playlist_with_content、activated）由服务器写入或关联得出，不是客户端发送的名称。

• OnboardingStepRequest — 必填: journey_id, step
• OnboardingValue — 必填: none

  该人员在某一步骤输入的内容：输入的地址（email_submitted、reset_requested）、姓名（signup_name_entered）、是或否（signup_marketing_choice）、所选选项或后续问题的文本（question_answered、question_follow_up）、在邀请中输入的地址或姓名。绝不包含密码、验证码或令牌。为空则视为缺失。

• Operation — 必填: id, kind, state, created_at, updated_at
• OperationAccepted — 必填: id, release_id, operation_id
• OrganizationAdminInvitation — 必填: id, kind, delivery, status, recipient_email, organization_id, created_at, expires_at
• OrganizationAdminInvitationCreate — 必填: emails
• OrganizationAdminInvitationCreated — 必填: invitations
• OrganizationAdminInvitationList — 必填: items, next_cursor
• OrganizationAdmins — 必填: admins, candidates, revision
• OrganizationAdminsUpdate — 必填: admin_user_ids
• OrganizationBillingUsage — 必填：org_id, period, pool, allowance, stored_bytes, screens, projects, next_cursor
• OrganizationDomainChallenge — 必填: organization_id, challenge_id, domain, name, value, expires_at
• OrganizationDomainInput — 必填: domain
• OrganizationDomainProof — 必填: challenge_id
• OrganizationDomainRemoved — 必填: status
• OrganizationGuestPolicy — 必填: mode, domains

  当前生效的组织访客策略。访客是主组织为其他组织或没有主组织的人；策略绝不会移除已经是成员的人。

• OrganizationGuestPolicyDomain — 必填: none

  至少包含两个标签的小写 DNS 名称，即出现在已验证电子邮件地址 @ 之后的部分（国际化域名采用 xn-- 形式）。

• OrganizationGuestPolicyMode — 必填: none

  allow 准许所有访客。domains 准许已验证电子邮件地址属于所列域名之一的访客（精确匹配）。none 不准许任何访客。主组织成员绝不是访客。

• OrganizationGuestPolicyResult — 必填: mode, domains, outside_policy

  当前生效的访客策略，以及有多少人处于该策略之外。

• OrganizationGuestPolicyUpdate — 必填: mode
• OrganizationLibraryUpdate — 必填: project_id
• OrganizationList — 必填: organizations, new_organization_allowed
• OrganizationMemberInvitation — 必填: id, kind, delivery, status, recipient_email, organization_id, created_at, expires_at
• OrganizationMemberInvitationCreate — 必填: emails
• OrganizationMemberInvitationCreated — 必填: invitations
• OrganizationMemberInvitationList — 必填: items, next_cursor
• OrganizationNotificationList — 必填: items
• OrganizationNotificationPatch — 必填: none

  NotificationPatch 加上 project_ids。

• OrganizationNotificationWrite — 必填: channel

  NotificationWrite 加上通知所覆盖的项目。project_ids 缺省或为 null 时覆盖组织的所有项目，包括之后添加的项目；列表则恰好覆盖这些项目，每个都必须是组织的活跃项目。

• OrganizationPayments — 必填: organization_id, available, local_simulation, purchases
• OrganizationPeople — 必填: projects, people, truncated
• OrganizationPeopleMembership — 必填: project_id, role, can_approve
• OrganizationPeoplePerson — 必填: user_id, display_name, email, admin, member, managed, outside_guest_policy, projects
• OrganizationPeopleProject — 必填: project_id, name
• OrganizationPerson — 必填: user_id, display_name, email
• OrganizationPersonal — 必填: none

  组织仅为其唯一项目的包装：恰有一个活跃项目，无验证域，无当前或计划中的组织计划，且无除该项目所有者外的管理员。仪表板隐藏其组织级别。

• OrganizationProject — 必填: id, name, organization_id, status, screen_count
• OrganizationProjectAccess — 必填: project_id, joined
• OrganizationProjectAccessChange — 必填: project_id, user_id, access
• OrganizationProjectAccessRequest — 必填: changes
• OrganizationProjectAccessResult — 必填: changes
• OrganizationProjectOwner — 必填: project_id, owner_user_id
• OrganizationProjectOwnerUpdate — 必填: user_id
• OrganizationProjectPage — 必填: projects, next_cursor
• OrganizationRename — 必填: name
• OrganizationSummary — 必填: id, name, personal
• OrganizationView — 必填: id, name, personal, revision, admin, home, project_count, plan_id, free, plan_required, education_eligible, education_eligibility_source
• PageDataCondition — 必填: key

  卡片数据谓词，在本地时间前评估。缺失或过期数据永不匹配。页面也遵守其普通时间范围。需要 host 功能 page.conditions；旧主机收到禁用页面。

• PageFailure — 必填: page_id, code, at

  该屏幕最新接受的playback.page_failed报告。播放器未报告前为空。只读项目健康元数据；不改变屏幕版本或清单权限。

• PageVisibility — 必填: enabled

  可选页面可见性计划。它是 advance 的同级，且永不属于 screenrig.canvas/v1；它描述播放编排，而非几何。服务器验证并作为数据携带这些规则。播放器根据清单根处发布的屏幕时区评估它们。

  当 enabled 为 true，当前时间在 [from, until) 范围内，且 windows 字段缺失或至少有一个窗口匹配时，页面即为合格。每个播放列表必须至少保留一个完全无可见性字段的页面，因此始终存在合格内容。评估规则的符合性向量为 packages/schedule-contract 中的 screenrig.schedule/v1 系列。

• PageVisibilityWindow — 必填: days

  一个循环的民用时间窗口。省略开始和结束时选择全天。结束时间小于或等于开始时间时，窗口跨越午夜，开始日拥有该窗口，因此周五 22:00 到 02:00 跨至周六早晨。

• PairScreen — 必填: code
• PairingClaim — 必填: screen, public_url
• PairingClaimedEvent — 必填: type, completion_nonce
• PairingComplete — 必填: completion_nonce
• PairingCompletion — 必填: screen, public_url
• PairingSession — 必填: code, expires_at
• PasskeyAdditionProof — 必填: authorization_ceremony_id, authorization_credential
• PlaybackAggregate — 必填: screen_id, media_id, filename, day, play_count, last_page_id, last_manifest_revision, first_started_at, last_started_at
• PlaybackAggregateCsv — 必填: none

  RFC 4180 CSV，CRLF 记录，UTF-8，带有标题行 screen_id,media_id,filename,primitive,day,play_count,last_page_id,last_manifest_revision,first_started_at,last_started_at。时间为 RFC 3339 UTC。以 =、+、-、@、制表符或回车开头的单元格前加单引号，防止电子表格计算。

  Content-Disposition 命名为 playback-aggregates.csv。标题后流失败时，连接中止。

• PlaybackAggregateList — 必填: items
• PlaybackApplicationStartedContext — 必填: manifest_revision, page_id, primitive_id, release_id
• PlaybackApplicationStartedReport — 必填: severity, code, context

  页面上应用原语的一个可见启动：应用在屏幕上变为可见，由播放器控制器每次页面出现报告一次——应用内容自身不报告可见性，包下载不算启动。

  发送屏幕已认证；页面、原语、发布和清单身份为报告观察，无内容或授权成员检查。存储每次播放的持久记录（GET /api/playback/plays）。项目拥有的发布/应用维护时间戳通过可恢复批量投影跟踪。

  普通播放确认省略可选的额度余额头。应用启动无每日汇总行；播放记录即为证据。

• PlaybackCompleteness — required: day_from, day_to, measured_plays, missing_plays, completeness, days, gaps, truncated

  在 day_from 至 day_to（含首尾）的 UTC 日期范围内，屏幕产生的播放有多少到达了后端。measured_plays 和 missing_plays 是 days 中各日之和，completeness 为 measured_plays 占二者之和的比例，二者均为 0 时为 null。days 按最早在前列出，仅包含有已测量或缺失播放的日期。gaps 按最新在前列出播放编号中的空缺。

  没有编号的播放（较旧的 Player，以及在播放编号出现之前存储的开始记录）不属于这些数字中的任何一项。

• PlaybackCompletenessDay — required: day, measured_plays, missing_plays, completeness

  某个 UTC 接收日的播放编号。

• PlaybackCompletenessShare — 必填: none

  已到达的播放数占已到达与缺失播放数之和的比例，范围为 0 到 1。二者都没有时为 null，例如不对播放进行编号的较旧 Player。

• PlaybackGap — required: screen_id, day, from, to, missing_plays

  Player 跳过的一段连续播放编号：对应数量的播放已经发生，却从未到达。

• PlaybackGrant — 必填: none

  后端授予的播放握手：mint 的 PlaybackHandshake 与此后端支持的交集，已登录会话。无交集时会话中省略，因此无握手生成的会话保持不变。播放器仅在 manifest_versions 包含 3 时使用 /screen/manifest。

• PlaybackHandshake — 必填: none

  播放器在 mint 时声明的可选播放握手。它是选择行为的提示，绝非授权：未知成员和错误类型条目被忽略，非对象值不协商任何内容。mint 响应回显支持的交集为 PlaybackGrant。adslot-v1 仅授予配对会话。

• PlaybackMediaStartedContext — 必填: media_id, manifest_revision, page_id, primitive
• PlaybackMediaStartedReport — 必填: severity, code, context

  页面上图像或视频原语的一个可见启动。播放器每次页面出现媒体时发送一次，对于图像与视频相同；同一出现内的循环不算重新启动。发送屏幕经过认证；媒体、页面、原语和清单身份为观察数据，无内容或权限检查。

  成功表示持久的原始插入；每日计数通过可恢复的批量投影跟踪。普通播放确认省略可选的信用余额头。

• PlaybackPageFailedContext — 必填: page_id, code
• PlaybackPageFailedReport — 必填: severity, code, context

  报告某个页面无法就绪。服务器接受后替换 Screen.last_page_failure，并在同一事务中追加持久的仅项目播放页面失败事件 playback.page_failed。不会更改屏幕版本或清单权限。

• PlaybackPlay — 必填: screen_id, page_id, media_id, primitive, received_at

  播放器报告的图像、视频或应用程序的一个持久启动。

  会话认证屏幕和项目；项目、页面、清单、原语和发布身份为报告观察，不授权内容访问。playlist_id 和 playlist_revision 为可选元数据，异步从匹配屏幕清单丰富；缺失元数据保持缺失。

  应用启动时携带 release_id，media_id 和 primitive 为空。primitive_id 和 started_at 仅在播放器报告时存在；started_at 限制在 [received_at - 24h, received_at + 5m]。

  JSON 页面还会附上其屏幕、媒体、播放列表和应用的名称，作为提供页面时读取的显示文本；CSV 导出以及 xlsx 和 pdf 报告会省略这些名称。

• PlaybackPlayCsv — 必填: none

  RFC 4180 CSV，CRLF 记录，UTF-8，标题行为 screen_id,playlist_id,page_id,primitive_id,media_id,primitive,started_at,received_at,manifest_revision,playlist_revision，顺序固定；缺失值为空单元格。时间为 RFC 3339 UTC。以 =、+、-、@、制表符或回车开头的单元格前加单引号。

  Content-Disposition 命名播放-plays.csv。完整导出在其最后一个 CRLF 记录后结束，无尾部；在头部后失败的流在连接处中止（客户端看到传输错误，永远不会是干净结束），因此从最后的 received_at 重新尝试。

• PlaybackPlayList — 必填: items, next_cursor
• PlaybackTotals — 必填: by, day_from, day_to, truncated

  播放总计，覆盖包含的 UTC 天数 day_from 到 day_to。days（by=day）、screens（by=screen）、media（by=media）或 screen_days（by=screen_day，按屏幕分组，排名顺序，日期升序）中恰有一个存在，为请求指定的。truncated 为 true 表示排名可能遗漏了低于某个切片或商店最佳的键。

• PlaybackTotalsDay — 必填: day, play_count, first_started_at, last_started_at
• PlaybackTotalsMedia — 必填: media_id, play_count, first_started_at, last_started_at
• PlaybackTotalsScreen — 必填: screen_id, play_count, first_started_at, last_started_at
• PlaybackTotalsScreenDay — 必填: screen_id, day, play_count
• PlaybackVideoStartedContext — 必填: media_id, manifest_revision, page_id
• PlaybackVideoStartedReport — 必填: severity, code, context

  报告一次可见视频开始。此报告与playback.media_started的日聚合相同，适用于原始视频。每次开始发送一份报告；同时发送两种事件会计两次开始。报告图像和视频时使用playback.media_started。

• PlayerBrowserIdentity — 必填: kind, version, pwa

  用于浏览器播放器（包括原生外壳）的浏览器引擎和安装模式。格式错误的可选浏览器提示会被忽略，不会导致初始化失败。

• PlayerCardsIdentity — 必填: none

  播放器自带的卡片库（docs/player-compatibility.md §3.1）：库的 CalVer 和每张卡的 semver，主版本决定屏幕渲染的卡片位置。与播放器其他内容一起存储于屏幕。格式错误的条目逐个丢弃；绝不会返回 400。

• PlayerIdentity — 必填: kind

  播放器自我识别，仅在三个 mint 路由上发送（docs/player-compatibility.md §3.1）。它是提示而非授权，且不包含在本地证明中。读取时容错：忽略未知成员，丢弃无效的可选成员，非对象或无有效类型的播放器不声明任何内容。

  永远不会返回 400。配对的 mint 会将其存储在屏幕上以供操作员舰队直方图使用。

• PlayerPublicKey — 必填: kty, crv, x
• PlayerShellIdentity — 必填: kind

  Web 播放器运行的外壳。其兼容令牌被记录，绝不授予。无效类型丢弃外壳。

• Playlist — 必填: id, name, revision, pages
• PlaylistAdvance — 必填: none
• PlaylistAdvanceWrite — 必填: none
• PlaylistApplicationAdvance — 必填: mode, max_ms
• PlaylistApplicationPrimitive — 必填: id, primitive, release_id, rect, layer, content_fit
• PlaylistApplicationPrimitiveWrite — 必填: id, primitive, release_id, layer, content_fit
• PlaylistApproval — 必填: state, review_id

  当此播放列表的审核待处理时出现。播放列表本身为实时（已批准）版本。

• PlaylistAudio — 必填: tracks, loop, volume

  存储的播放列表配乐，已填充默认值。

• PlaylistAudioCue — 必填: track

  普通页面上的可选配乐提示。当页面成为当前页面时，播放器从头开始切换到指定曲目，除非它已在播放；restart true 即使如此也重启。序列从该曲目继续。

  播放器可能忽略提示。track 必须指定播放列表音频中的轨道 ID；无播放列表音频的 cue 为 invalid_request。不允许在广告位页面使用。带 advance mode audio_end 的页面在提示轨道结束时结束；需要此 cue。

• PlaylistAudioEndAdvance — 必填: mode, max_ms
• PlaylistAudioEndAdvanceWrite — 必填: mode

  页面在其 audio_cue 指定的配乐曲目结束时结束。页面必须携带 audio_cue，播放列表必须有音频配乐（docs/playlist-audio.md）。

• PlaylistAudioTrack — 必填: id, media_id
• PlaylistAudioWrite — 必填: tracks

  可选播放列表配乐：有序准备好的音频（MP3）媒体，在页面切换时持续播放（docs/playlist-audio.md）。页面切换永不停止或重启它。PUT 替换整个播放列表，省略音频则移除配乐。

• PlaylistCanvas — 必填: width, height, background
• PlaylistCardPrimitive — 必填: id, primitive, card, major, params, rect, layer, content_fit, controller
• PlaylistCardPrimitiveWrite — 必填: id, primitive, card, layout, content_fit

  播放器原生绘制的内置卡片（时钟、天气、菜单板、跑马灯、KPI 瓷砖及其他供应商卡片目录，screenrig.cards.contract/v1）。布局放置它：full（整个画布）、free（自定义矩形和层）、center（900 x 420）、wide（画布左右各内缩 30，顶部底部各内缩 80）、header（整个顶部边缘，高 80）、footer（整个底部边缘，高 80）、corner（270 正方形）、chip（240 x 70）或 strip（整个边缘，高 120），以 1080p 设计单位按 min(画布宽度，画布高度) / 1080 缩放。corner 和 chip 需锚点角（左上、右上、左下、右下），strip 需锚点边（上、下、左、右）；其他布局无锚点。

  除免费外，服务器从画布或覆盖帧显示中派生 rect 和 layer：省略它们，或发送其确切派生值。

  页面最多包含一张全屏、居中或宽卡片，每个角落最多一张角卡或芯片卡，每条边缘最多一条条带（带存在的卡片可与普通条带共享边缘）；页眉占用顶部边缘的普通条带位置，页脚占用底部边缘的普通条带位置，因此页面最多各有一条，且该边缘无普通条带，带存在的卡片仍可共享该边缘。

  边缘上的角或缺口，承载条带的部分向内移动 120，承载页眉或页脚的部分向内移动 80。

  在有格式的播放列表中，displays 是布局派生的框架（full 是框架，corner 是框架角落；free 拒绝 displays），卡片缩放是瓦片的最小宽高 / 1080 = 1，而非从框架派生；当两个卡片的框架共享显示器（无 displays 是所有显示器）时，两个卡片会争夺一个槽位，或移动到彼此条带之内。

  卡片的层级决定其可用布局（GET /api/card-types）：core 支持全部九种，fullscreen 支持 full。params 保存放置项的静态属性（主题、位置、标题、列定义），仅在重新发布时才会变化。

  params 中的字符串可以包含 {screen.name}、{screen.timezone} 和 {screen.field.NAME}，location 参数也可以是字符串 {screen.location}；后端会为每个屏幕展开它们，因此同一个播放列表可以让每个屏幕显示各自的值。data 指定一个卡片数据文档（GET/PUT /api/card-data/{key}），其中保存卡片的动态属性（菜单分区、滚动字幕条目、KPI 磁贴）；智能体无需重新发布即可修改它。data 键中的 {screen.field.NAME} 会读取每个屏幕各自的文档，例如 menu-{screen.field.store_number}。

  带有数据时，参数不得携带动态属性；无数据时，参数包含整个配置。参数中以 media: 开头的每个字符串都是媒体引用，media:<id>，指向本项目中准备好的图像，卡片会绘制它（聚焦 people[].photo，product-grid products[].photo）；卡片绝不使用图像 URL。

  发布拒绝未知卡片或主要且无效参数（card_invalid）、卡片可能不携带的布局、锚点、矩形或图层（card_layout_invalid）、页面上声明占用一个位置的卡片（card_layout_conflict）、未命名项目任何就绪图像的媒体引用（card_media_invalid）以及卡片拒绝其存储文档的绑定密钥（card_data_invalid）。

  显示该位置的屏幕被授予其媒体，实时写入批准其命名的待处理媒体，如使用 by:id 选择器。带有第三方源（天气）的卡片从服务器根据其静态参数派生的键读取。

• PlaylistCreateRequest — 必填: none

  播放列表的页面、用于创建它的模板，或内置的入门模板。

• PlaylistDisplays — 必填: none

  仅带格式的播放列表。原语覆盖的显示器：在 1..format.displays 范围内、升序且唯一的从 1 开始的显示器编号，它们填满墙面瓦片的一个矩形，如 [2]、[1, 2]，或在 4 列的网格上为 [2, 3, 6, 7]。在行或列中它们是连续的。

  服务器将 rect 推导为这些瓦片的边界框；rect 可省略或与推导值完全相同。存储并在读取时回显。

• PlaylistDurationAdvance — 必填: mode, after_ms
• PlaylistExpandRequest — 必填: none
• PlaylistExpanded — 必填: pages
• PlaylistFormat — 必填: none

  播放列表的创作用途：视频墙（PlaylistWallFormat）或区域（PlaylistRegionFormat），二者不可兼有。没有格式的播放列表是普通播放列表，可作为页面绑定到任何屏幕。

• PlaylistFromTemplate — 必填: playlist_id

  根据模板创建播放列表：使用其当前页面并填入值，按所有播放列表规则验证。媒体值必须是类型正确且就绪的媒体项，地址值必须是 http 或 https 地址。

• PlaylistFromTemplateWrite — 必填: name, from_template

  根据模板创建播放列表。只需发送 name 和 from_template。

• PlaylistIframePrimitive — 必填: id, primitive, src, title, rect, layer, content_fit, controller
• PlaylistIframePrimitiveWrite — 必填: id, primitive, src, title, layer, content_fit
• PlaylistImagePrimitive — 必填: id, primitive, selector, resolved_media, rect, layer, content_fit, controller
• PlaylistImagePrimitiveWrite — 必填: id, primitive, selector, layer, content_fit
• PlaylistInstance — 必填: id, name, revision, template_revision, outdated
• PlaylistInstanceList — 必填: items
• PlaylistIntrinsicSize — 必填: width, height
• PlaylistList — 必填: items
• PlaylistMediaEndAdvance — 必填: mode, max_ms
• PlaylistMediaEndAdvanceWrite — 必填: mode
• PlaylistMediaSelector — 必填: none
• PlaylistMediaSelectorByAll — 必填: by
• PlaylistMediaSelectorByFolder — 必填: by, folder_id

  原始文件直接位于一个媒体文件夹内（GET /api/media-folders），不包括其子文件夹，按 by:all 排序和节奏。像标签一样，每次选择器解析时都会重新读取该文件夹，因此移动文件会从下一轮循环开始改变播放屏幕显示内容。

  写入播放列表要求项目中存在该文件夹；文件夹可为空。未包含原始文件的文件夹或后来被删除的文件夹不匹配任何内容。播放器以 by:all 方式接收，服务器解析文件夹。

• PlaylistMediaSelectorByID — 必填: by, media_id
• PlaylistMediaSelectorByIDs — 必填: by, media_ids
• PlaylistMediaSelectorByTag — 必填: by
• PlaylistPage — 必填: id, canvas, transition, advance, primitives
• PlaylistPageAdd — 必填: page
• PlaylistPageStructure — 必填: id

  一页保持不变，以及个人更改的两个页面设置。advance 在存在时替换页面的 advance，省略时保持；广告位页面无此项。visibility 在为对象时替换页面的 visibility，为 null 时移除，省略时保持。

  仅设置 enabled 为 true 的可见性对象无操作且被拒绝：发送 null 以移除规则。

• PlaylistPageV2 — 必填: none
• PlaylistPageWrite — 必填: id, canvas, transition, advance, primitives
• PlaylistPageWriteV2 — 必填: none
• PlaylistPatch — 必填: none

  省略的字段将被保留。提供的名称、页面、音频和格式替换顶层对应值；音频或格式为 null 则移除。提供的页面在省略格式时会检查存储格式，提供格式在省略页面时会检查存储页面。身份、修订、注释和时间戳不可在此设置。

  评论有自己的端点。

• PlaylistPrimitive — 必填: none
• PlaylistPrimitiveLocked — 必填: none

  已锁定的图元是模板中固定的品牌内容（徽标、背景、布局、主题）：只有项目所有者或可以审批的成员才能添加、移除、移动、编辑它或解除其锁定，由该模板创建的播放列表也会保持锁定。省略表示未锁定。已锁定的图元不能读取字段。

  其他人的写入会返回 primitive_locked（403），在 Propose 下则成为审阅。

• PlaylistPrimitiveWrite — 必填: none
• PlaylistRect — 必填: x, y, width, height
• PlaylistRegionFormat — 必填: region, orientation

  沿显示器一条边绘制在页面之上的条带：header 在顶部，footer 在底部，side 在右边缘并占满整个高度。orientation 是其所针对显示器的方向，按旋转后观看者所见为准。

  每个页面的画布（宽和高）都相同；header 或 footer 宽大于高，side 高大于宽，长边至少是短边的两倍，否则在 pages[i].canvas 处返回 400 invalid_request。

  播放列表只包含图片和卡片原件（视频、流、iframe、应用或广告位页面会被拒绝），且没有配乐（音频会被拒绝）；原件不指定显示器。

  区域播放列表绝不会是屏幕默认项、文件夹默认项或接管：它只能作为 covers 设为其区域的排程条目或活动播放（covers 为 main 和整页时会拒绝它），而 covers 为 header、footer 或 side 时需要该区域的区域播放列表。

  当条带未布局在其针对的任何显示器上时，该条目或活动会被拒绝，返回 409 playlist_format_mismatch：条带布局在其方向对应的显示器上，按播放器报告的旋转后的表面判断（播放器未报告时按屏幕的视频墙旋转判断），并且仅当它覆盖不超过显示器的一半时（header 或 footer 按高度，side 按宽度）。

  仅当活动在其受众的所有屏幕上都未布局时才会被拒绝；在混合受众的某个屏幕上未布局时，该活动会离开该屏幕的堆栈，其说明为 region_not_laid_out。

  当屏幕排程、接管或默认项、文件夹默认项或活动正在使用某个播放列表时，将其移入或移出区域，或改到另一个区域的格式更改会被拒绝，返回 409 resource_conflict。

• PlaylistResolvedMedia — 必填: media_id, intrinsic_size
• PlaylistRevision — 必填: revision, created_at, change, name, page_count, current

  One stored revision of a playlist. change says what made it: created (the first revision), edited (a replace, patch, structure change or applied review), promoted (a copy of an earlier revision, named by restored_from), or baseline (the revision the playlist held when its history began, before any write recorded one).

  读取方不认识的值按 edited 处理。

• PlaylistRevisionAuthor — 必填: type, name

  创建该修订的人，按项目事件日志中的称呼；写入未指明任何人时（基线或系统工作）则不出现。

• PlaylistRevisionDetail — 必填: revision, playlist
• PlaylistRevisionList — 必填: items
• PlaylistStarterWrite — 必填: starter

  添加内置的“紧急通知”模板（标题和消息）。只需发送 starter，也可以再发送 name。

• PlaylistStinger — 必填: none

  仅过渡的 stinger 卡（主版本 1）。所有成员可选；默认保留在合成运行时位置。hang_ms 默认 1000，最大为过渡 duration_ms 的 60%（服务器检查）。logo 指向本项目中已准备图像，使用卡片媒体授权路径。

• PlaylistStreamPrimitive — 必填: id, primitive, sources, fallback_media_id, rect, layer, content_fit, muted, controller, resolved_media
• PlaylistStreamPrimitiveWrite — 必填: id, primitive, sources, fallback_media_id, layer, content_fit
• PlaylistStructurePatch — 必填: none

  播放列表结构，仅限页面显示内容（patchPlaylistStructure）。省略成员保持不变。提供的名称替换名称。提供的页面为播放列表持有页面的新完整顺序：省略的存储页面将被移除。

  页面内容（画布、过渡、audio_cue、原语、评论）和配乐无法发送，始终为存储的内容。

• PlaylistTemplateField — 必填: name, label, type

  模板接受的一个值。页面将其读取为 {field.NAME}：位于卡片的 params 中（文本和地址字段）、图片或视频选择器的 media_id（媒体字段），或 iframe 的整个 src（地址字段）。

• PlaylistTemplateFields — 必填: none

  声明字段会使播放列表成为模板。页面读取的每个标记都必须指向类型正确的已声明字段，每个字段都必须被读取；没有字段的播放列表不读取标记。模板不会显示在屏幕上（playlist_is_template）。不带 fields 的 PUT 会保留字段；null 或空数组会移除字段。

• PlaylistTransition — 必填: type, duration_ms

  页面过渡。type 和 duration_ms 都是必需的；OpenAPI 不默认它们。滑动创作示例使用 duration_ms 600；该值不是模式默认。

• PlaylistV2 — 必填: id, name, revision, pages
• PlaylistV2List — 必填: items
• PlaylistValuesChange — 必填: values
• PlaylistVideoPrimitive — 必填: id, primitive, selector, resolved_media, muted, loop, rect, layer, content_fit, controller
• PlaylistVideoPrimitiveWrite — 必填: id, primitive, selector, layer, content_fit
• PlaylistWallFormat — 必填: displays, arrangement, orientation

  播放列表所针对的视频墙：2 到 12 个显示器，瓦片为 1920 x 1080（横屏）或 1080 x 1920（竖屏），按行、列或网格布局。行布局的列数等于显示器数量、行数为一，列布局的列数为一、行数等于显示器数量，网格布局的列数为 columns、行数为 displays / columns。

  显示器 n 位于列 (n - 1) mod columns、行 floor((n - 1) / columns)：先从左到右，再从上到下。

  由 c 列 r 行、宽 w 高 h 的瓦片组成的画布大小为 (c * w, r * h)，例如 3 块横屏显示器排成一行为 5760 x 1080，2 块竖屏显示器排成一列为 1080 x 3840，12 块横屏显示器排成 4 列的网格为 7680 x 3240。

  每个普通页面的画布宽度和高度必须完全匹配，否则在 pages[i].canvas 返回 400 invalid_request。此类播放列表的卡片缩放比例为图块的 min(宽度，高度) / 1080 = 1。

  带格式的播放列表仅可绑定到墙面形状相同的屏幕（显示器数量=输出数，排列，列数，且仅当旋转为 90 或 270 时为竖屏），否则返回 409 playlist_format_mismatch：分配、车队分配、排程条目和接管。无格式播放列表可绑定任意屏幕。

• PlaylistWarning — 必填: code, message, page_id, primitive_id

  成功写入的作者应当采取行动的事项。写入已保存其所携带的内容；警告绝不会使其失败。播放列表写入在播放列表上返回警告；屏幕写入（updateScreen、控制台的字段、位置和播放列表路由）在屏幕上返回；机群分配在结果页上返回。

  两个代码。iframe_framing_refused：iframe 原语（其 src 或 fallback_src）指向的公共 https 页面发送了 X-Frame-Options（DENY、SAMEORIGIN 或已废弃的 ALLOW-FROM），或发送的 Content-Security-Policy frame-ancestors 列表不包含 Player 网页应用的源。

  Player 网页应用以及 macOS、Samsung Tizen、LG webOS 和 BrightSign Player 会将页面嵌入框架，因此无法显示该页面；Android、Linux 和 Windows Player 会直接打开完整 iframe 页面，不受影响。

  后端在写入提交后读取响应头，每次写入最多检查 8 个不同页面；无法及时访问或返回错误的页面不会报告。每个不同页面只出现一次，标明首个使用它的原语，并向项目日志添加一个 playlist.iframe_framing_refused 事件（警告）。

  带有屏幕令牌的 src 不是单一页面，不会被读取。screen_fact_missing：写入所涉及的某个屏幕缺少 iframe 的 src 或应用的 params 通过屏幕令牌（{screen.field.NAME}、{screen.location.…}、{screen.timezone}）读取的值，或其现有的值填入后会得到清单拒绝的内容（超过 2048 个字符的地址、路径段为 . 或 ..、启动 URL 中超过 4096 个字符的启动参数），因此在该屏幕有该值之前，该原语不会出现在该屏幕的清单中（清单诊断 screen_fact_missing 或 screen_fact_invalid）。

  每次写入有一条警告，指出第一个此类原语、所列屏幕均无法填入的令牌（最多 64 个）、前 20 个受影响的屏幕及总数。

  播放列表写入（替换、补丁、结构变更、提升或已应用的审核）会作用于显示该播放列表的屏幕；屏幕写入作用于该屏幕，涉及其所显示的播放列表和刚分配给它的播放列表；机群分配作用于其页面的屏幕；批准屏幕变更作用于其所指定的屏幕。

• PlaylistWrite — 必填: name, pages
• PlaylistWriteV2 — 必填: name, pages
• PrimitiveEnter — 必填: type

  可选对象进入。播放列表写入和运行时清单按原样使用此对象；其中不进行 snake_case 重命名。缺失表示静止绘制，完全不透明。可选整数错开 0 到 8，延迟启动时间为错开数乘以 120 毫秒，基于共享的 500 毫秒延迟。缺失或为 0 表示当天启动。持续时间为 screenrig.canvas/v1 中的命名常量。

• PrimitiveMotion — 必填: none

  可选持久对象运动。播放列表写入和运行时清单按原样使用此对象；其中不进行 snake_case 重命名。缺失表示进入后原始状态保持静止。

  通过未插值复制。旋转和漂移仅适用于图像和视频；应用和 iframe 上的旋转或漂移被服务器拒绝（motion_not_allowed_for_primitive）。路径适用于图像、视频、应用和 iframe。此限制未编码为 OpenAPI if/then。

• PrimitiveMotionDrift — 必填: type, zoom, direction, speed

  围绕 clipRect 中心连续缓慢缩放并缓慢平移。仅限图像和视频；服务器拒绝应用和 iframe 上的漂移。往返运动；无跳跃。

• PrimitiveMotionPath — 必填: type, points, rate

  沿画布单位路径点的多段线平移，起点为创作矩形。省略时 loop 默认为循环。适用于图像、视频、应用和 iframe。

• PrimitiveMotionPoint — 必填: x, y
• PrimitiveMotionSpin — 必填: type, direction, speed

  围绕 clipRect 中心连续旋转。仅限图像和视频；服务器拒绝应用和 iframe 上的旋转。

• Problem — 必填: errors, instance, request_id

  除面向播放器的运行时、内容和探测路由（RuntimeProblem）外，每个路由的错误文档。错误本身为 errors[0]：其状态、代码、类型、标题、详情和提示。仅文档成员保留在顶层。分支基于 errors[0].code，绝不基于详情或提示，它们是散文。

  被指责的请求字段添加 errors[0].field；每个进一步被指责字段是带该字段详情的独立条目。

• ProblemError — 必填: status, code, type, title, detail, hint

  问题文档的一个错误。超出这些成员的描述进一步说明该错误（例如依赖于 not_ready）。

• ProblemField — 必填: field, code, detail
• Project — 必填: id, revision, status, email, used_bytes, reserved_bytes, screen_count, content_limit_bytes, screen_limit, credit_remaining, created_at, updated_at, name
• ProjectBillingUsage — 必填：period, usage, stored_bytes, allowance
• ProjectCapabilities — 必填: project_id, plan_id, features, feature_revision, capabilities, media_video_bytes, plan_features, limits
• ProjectContext — 必填: project, organization
• ProjectContextList — 必填: projects
• ProjectCreate — 必填: name
• ProjectDeleteConfirmation — 必填: name, revision
• ProjectDeletionPreview — 必填: project, organization, devices, allowed
• ProjectFeatures — 必填: advertiser, screens
• ProjectMove — 必填: organization_id
• ProjectMoveDestinations — 必填: organizations
• ProjectName — 必填: none

  修剪后的可打印项目名称。拒绝控制字符、URL样式文本、@、www.和://。

• ProjectOwnerTransfer — 必填: user_id
• ProjectPatch — 必填: name
• ProjectPlanFeature — 必填: id, enabled, required_plan
• ProjectPlanFeatures — 必填: featuresets, features

  项目拥有的计划功能。由计划和项目的 featuresets 决定；额度绝不会解锁任何功能。项目不具备的功能会被 feature_not_in_plan（402）拒绝，其 required_plan 指明包含该功能的、公开销售的最低套餐。

• ProjectPlanLimits — 必填: screens, members, video_bytes, event_retention_days

  项目的限制，由其计划和 featuresets 给出，即准入时强制执行的数值。零表示计划不设上限。

• ProjectUptime — 必填: items
• ProvisionScreen — 必填: none
• RTSPStreamSource — 必填: protocol, url
• ReadyResponse — 必填: status, degraded
• ReleaseLaunch — 必填: launch_url, expires_at
• Report — 必填: kind, title, generated_at, columns, rows, truncated

  以表格形式表示的报告：columns 说明每个行成员是什么。行携带的成员多于列所显示的（文件夹层级用的 id、parent_id 和 depth）。百分比列取值为 0 到 100。

• ReportCatalog — 必填: items, formats
• ReportColumn — 必填: key, label, type
• ReportKindInfo — 必填: kind, title, description, params
• ReportParam — 必填: name, description
• ReportSchedule — 必填: cadence
• ReportSubscription — 必填: id, name, kind, filters, schedule, format, enabled, recipients, revision, created_at, updated_at
• ReportSubscriptionList — 必填: items
• ReportSubscriptionPatch — 必填: none
• ReportSubscriptionRecipient — 必填: user_id
• ReportSubscriptionWrite — 必填: name, kind, schedule, format, recipients
• Reseller — 必填: id, name, spread_bps, spread_effective_at, customer_count, review_state, customer_limit
• ResellerCustomer — 必填: organization_id, name, plan_id, delegated_at, project_count, screen_count, stored_bytes, annual_list_cents, annual_wholesale_cents
• ResellerCustomerPage — 必填: items, next_cursor
• ResellerCustomerProject — 必填: id, name, status, screen_count, member
• ResellerCustomerProjectPage — 必填: projects, next_cursor
• ResellerEnrollment — 必填: organization_id
• ResellerList — 必填: items
• ResellerStatement — 必填: reseller_id, name, period, spread_bps, lines, usage_list_mcr, usage_wholesale_mcr, plan_annual_list_cents, plan_annual_wholesale_cents
• ResellerStatementLine — 必填: organization_id, name, plan_id, delegated_from, project_count, screen_count, stored_bytes, api_events, usage_list_mcr, usage_wholesale_mcr, plan_annual_list_cents, plan_annual_wholesale_cents
• ResellerSummary — 必填: id, name
• Review — 必填: id, kind, state, subject, proposer, url, created_at, updated_at, impact
• ReviewAdCreative — 必填: creative_id, creative_revision, content_path
• ReviewApproveRequest — 必填: none
• ReviewBlocker — 必填: id, state, subject
• ReviewChangesRequest — 必填: note
• ReviewDecider — 必填: none
• ReviewDecisionResult — 必填: review
• ReviewDependentResult — 必填: id, state
• ReviewImpact — 必填: screens
• ReviewList — 必填: items, next_cursor, pending_count
• ReviewLocation — 必填: project_id, project_name
• ReviewMediaChange — 必填: media_id, filename, before, after

  selector_refresh 审核询问的一个媒体项的待处理更改。

• ReviewMediaFields — 必填: tags, folder_id
• ReviewMediaFile — 必填: sha256, bytes, content_type
• ReviewMediaPlaylist — 必填: id, name, screens, media_added, media_removed
• ReviewMediaReplace — 必填: media_id, filename, source, version, before, after, aspect_changed, playlists

  media_replace 审核所针对的某个媒体项目的文件替换。在批准之前，媒体保留其原文件。

• ReviewPageEdit — 必填: op, page_id
• ReviewPending — 必填: status, review

  在提议权限下的审核类写入，或在任何访问级别下涉及受保护屏幕的写入。在人员批准审核之前，更改不会出现在屏幕上；受保护的审核由第二位审批人决定（docs/screen-scope.md）。

• ReviewPerson — 必填: user_id, name
• ReviewPlaylistChange — 必填: operation, base_revision, proposed, diff
• ReviewPlaylistDiff — 必填: name_changed, pages_added, pages_removed, pages_changed, soundtrack_changed, media_added, media_removed
• ReviewPolicy — 必填: agent_changes_require_review, review_policy_revision
• ReviewPolicyUpdate — 必填: agent_changes_require_review
• ReviewPreview — 必填: live, proposed

  存储形态中 GET /api/playlists/{id} 返回的实时和提议播放列表（带 resolved_media 的页面）。

• ReviewProposer — 必填: kind
• ReviewProtectedCampaign — 必填: none

  一个 campaign_create、campaign_update 或 campaign_delete。

• ReviewProtectedChange — 必填: subkind

  protected_change 审核所存储的输入，在第二位审批人批准时通过所属服务应用。campaign、folder 和 move 中恰好有一个存在，如 subkind 所示。批准会在 base_revision 重放；已变化的活动或文件夹会使审核过时（review_stale）。

• ReviewProtectedFolder — 必填: none

  一个 folder_create、folder_update、folder_delete 或 folder_unprotect。

• ReviewProtectedMove — 必填: folder_id, screen_ids, folder_ids

  一个 screens_move，即 POST /api/screens/move 的请求体。

• ReviewRejectRequest — 必填: reason
• ReviewScreenChange — 必填: action, screens, request, playlist_ids
• ReviewSubject — 必填: type, id, name
• ReviewSummary — 必填: id, kind, state, url, subject, impact
• RuntimeAdslotCandidate — 必填: page_id, occurrence_id, check_sequence, earliest_start_at
• RuntimeAdslotEvent — 必填: event_id, decision_id, occurrence_id, kind, client_sequence
• RuntimeAdslotEventBatch — 必填: events
• RuntimeAdslotEventResponse — 必填: results
• RuntimeAdslotEventResult — 必填: event_id, state
• RuntimeAdslotMedia — 必填: kind, duration_ms, content_type, bytes, sha256, content_path, fit
• RuntimeAdslotPage — 必填: id, type, adslot_id

  整页广告位，仅发送给获得 adslot-v1 权限的配对会话。遇到未知页面类型的播放器会丢弃该页面。

• RuntimeAdslotResolveRequest — 必填: manifest_revision, candidates
• RuntimeAdslotResolveResponse — 必填: server_time, results
• RuntimeAdslotResult — 必填: occurrence_id, check_sequence, state
• RuntimeAdvance — 必填: mode
• RuntimeApplicationPackage — 必填: version, url, bytes, sha256, entrypoint, contentType

  不可变的标准化包，仅由独立验证的应用树构建。原生播放器在原子保留此版本以进行离线最后已知良好恢复之前，会验证字节和 SHA-256。该 URL 是授权绑定的传输引用，而非公共或持久对象 URL。

• RuntimeApplicationPrimitive — 必填: id, primitive, applicationId, releaseId, launchUrl, origin, protocol, grantId, package, rect, layer, contentFit
• RuntimeAudio — 必填: loop, volume, tracks

  播放列表配乐（docs/playlist-audio.md）。仅当播放列表有配乐且至少投影一条轨道时发出。播放器按顺序播放轨道，独立于页面序列器；页面变更、过渡和可见性不会暂停或重启播放。

  轨道标识是 id 加 mediaId 加 sha256，绝不包括 src，因此保持播放轨道的清单刷新不会重新启动它。有效增益是音量乘以播放器音量。缺陷轨道会自动丢弃（invalid_audio_track）。

• RuntimeAudioCue — 必填: track, restart

  在创建了 audio_cue 的页面上发出的配乐提示。当页面成为当前页面时：如果正在播放不同的曲目或没有曲目，则从头开始切换到该曲目；如果曲目正在播放，仅当 restart 为 true 时重新开始。序列从曲目继续。提示可能被忽略。未命名任何清单曲目的提示将被丢弃（invalid_audio_cue）。

• RuntimeAudioTrack — 必填: id, mediaId, src, sha256, bytes, contentType, durationMs, grantId
• RuntimeCanvas — 必填: width, height, viewportFit, background
• RuntimeCardPrimitive — 必填: id, primitive, card, major, params, rect, layer, contentFit

  内置卡片。对于声明 CardML 功能的播放器，后端在固定主版本内选择最新兼容的已发布修订，考虑保留的修订和所有必需功能；无合格时省略该卡，带 card_unavailable 诊断并移除空页面。

  播放器合并卡片默认值、参数，然后在数据存在时合并 GET /screen/card-data/{data} 文档的动态属性（仅卡片标记为动态的键）。

  带数据的卡片在其第一个文档到达前保持隐藏，然后淡入；screen.card_data_changed 针对该键重新获取。feed（存在时）从同一路径获取并传递给卡片作为其 feed。缺少卡片或其主版本的播放器不绘制任何内容。

  以 media: 开头的参数或数据文档中的字符串是媒体引用，格式为 media:<id>，播放器会将其解析为在卡片绘制前持有的字节，无法解析时显示为空白；它从不将参数或数据中的 URL 传递给卡片。media 列出准备好的图像参数名称，以及图像原语的 resolvedMedia 所携带的描述符，因此播放器在清单到达时下载并验证它们；发布后丢失的媒体引用将缺失，卡片绘制其备用内容。

  数据文档所指定的媒体会在文档到达时从 /media/{media_id} 加载（ETag 为 sha256）。卡片媒体不会阻塞页面。后端已为此屏幕展开放置项的 {screen.name}、{screen.timezone}、{screen.field.NAME} 和 {screen.location} 占位符，因此 params 和 data 中携带的是该屏幕自己的值。

• RuntimeChrome — 必填: schema_version, banner

  运行时拥有的 chrome（docs/player-compatibility.md §8）。读取器读取已知成员，忽略其他成员；无法识别的横幅形状不显示横幅。

• RuntimeCodecs — 必填: none

  服务器派生的 RFC 6381 编解码器列表，针对该确切版本，从不由客户端声明。它是 contentType 的同级；播放器可形成 contentType 后跟 codecs="VALUE" 的能力查询。无法派生编解码器的视频上传时被拒绝。该属性可选。缺失值不表示不支持该编解码器。

  当前存在值包含一个视频轨道条目；语法允许逗号分隔条目。

• RuntimeCommandResultWrite — 必填: state

  POST /screen/commands/{command_id}/result 的请求体。未知成员会被忽略（docs/player-compatibility.md §1.1）。

• RuntimeConditionReport — 必填: severity, code, context
• RuntimeDisplay — 必填: none

  屏幕的显示控制，在设备上评估（docs/player-compatibility.md §6.5）：电源排程和覆盖、空闲变暗设置以及亮度模式。屏幕无此项时省略；此时显示器保持开启，亮度为操作员设定的亮度。忽略未知成员。

• RuntimeHealthWrite — 必填: none

  PUT /screen/health 请求体。所有成员均为可选；发送平台可测量的数据。未知成员被忽略，超出范围的值丢弃（非拒绝）。整数为完整 JSON 数字。

• RuntimeHostHint — 必填: platform

  配对开始、配对完成和身份会话生成时的可选本机主机提示。它命名设备，绝不作为授权。

  容错读取（docs/player-compatibility.md §1.1.1）：忽略未知成员，丢弃格式错误字段或能力条目，最多保留 32 个能力，非对象值或模式外平台丢弃整个提示。以上均不拒绝请求。

  播放器仍只发送注册的平台值和以下成员，因为预合同后端拒绝其他内容。

• RuntimeHostHintDevice — 必填: none

  本机主机提示中的可选硬件标识符。格式错误的字段将被丢弃。

• RuntimeIframeCookie — 必填: name, value, domain, path, secure, httpOnly, sameSite

  共享浏览器标签页的单个Cookie，符合浏览器Cookie API格式。值属于秘密信息。

• RuntimeIframePrimitive — 必填: id, primitive, src, title, rect, layer, contentFit
• RuntimeImagePrimitive — 必填: id, primitive, selector, resolvedMedia, grantId, rect, layer, contentFit
• RuntimeImageResolvedMedia — 必填: mediaId, src, intrinsicSize, sha256, bytes, contentType
• RuntimeIntrinsicSize — 必填: width, height
• RuntimeKVEntry — 必填: application_id, key, value_base64, content_type, bytes, sha256, revision
• RuntimeKVList — 必填: items
• RuntimeKVSummary — 必填: application_id, key, content_type, bytes, sha256, revision
• RuntimeKVWrite — 必填: value_base64
• RuntimeKiosk — 必填: lock

  自助终端锁定（docs/player-compatibility.md §6.5）。屏幕的 kiosk.lock 开启期间在每个会话中发出，否则省略。能够将自身固定在屏幕上的播放器会在 lock 为 true 时固定，并在该成员缺失或 lock 为 false 时解除固定；不能的播放器会忽略它。忽略未知成员。

• RuntimeLiveHeartbeat — 必填: connection

  Player 自己的报告。开放模式。

• RuntimeLiveHeartbeatAnswer — 必填: lease_until, max_until
• RuntimeLiveJoin — 必填: live_id, ice_servers, lease_until, max_until, heartbeat_ms, video

  Player 推流的目标及其限制。开放模式。

• RuntimeLiveJoinRequest — 必填: none

  为空。可以省略请求体。

• RuntimeLiveOffer — 必填: sdp

  不含 type 的会话描述，用于 Player 的提议和中继的应答。

• RuntimeLiveStopped — 必填: reason
• RuntimeManifest — 必填: schemaVersion, manifestRevision, grantId, contentGeneration, screenId, screenLabel, playlistRevision, generatedAt, pages

  使用确定性 screenrig.canvas/v1 画布、矩形、适应和源顺序契约的不可变运行时清单。允许读取端附加属性，因此此契约上的播放器会忽略未知键（兼容规则 2）。写入模式保持封闭。

  页面是普通画布页面，对于授予 adslot-v1 的配对会话，是整页广告位页面；无广告位页面的清单是自有内容。

• RuntimeManifestDiagnostic — 必填: level, code, detail

  一个故障安全的运行时投影遗漏。播放器和 CLI 可能显示这些；它们绝不是授权。

• RuntimeMediaSelector — 必填: none
• RuntimeMediaSelectorByAll — 必填: by, oneAtATime
• RuntimeMediaSelectorByID — 必填: by, mediaId, oneAtATime
• RuntimeMediaSelectorByIDs — 必填: by, mediaIds, oneAtATime
• RuntimeMediaSelectorByTag — 必填: by, oneAtATime
• RuntimeObservationSurfaceWrite — 必填: id, width, height, pixel_ratio, presentation
• RuntimeObservationWrite — 必填: observed_at, surfaces

  PUT /screen/observation 请求体。未知成员被忽略（docs/player-compatibility.md §1.1）。存储值为项目 ScreenObservation。

• RuntimeOrigins — 必填: content

  已交付的来源白名单（docs/player-compatibility.md §2.3）。仅在 Player 授权 origins-v1 的 mint 响应中存在。

  播放器将内容与其编译的内容来源合并，忽略无效条目。release_suffix 仅在为有效的至少两标签 DNS 后缀时替换编译的发布后缀；当运行时来源自行提供发布（本地开发）时缺失。

  已交付的集合从不更改凭证来源，后端也不会将 URL 放在本会话 mint 未交付的来源上。播放器存储其验证的最后已知良好对象，因此后续无来源会话保持该 LKG 有效。

• RuntimePage — 必填: contractVersion, id, canvas, transition, advance, primitives
• RuntimePairingScreen — 必填: id, public_id, label, state, revision, manifest_revision, content_access_generation, created_at, updated_at

  运行时拥有的屏幕摘要，在配对和浏览器配置完成时。其成员集被冻结：项目屏幕字段不会出现在此处（docs/player-compatibility.md §8）。状态保持以下三种值之一。

• RuntimePrimitive — 必填: none
• RuntimeProblem — 必填: type, title, status, detail, instance, code, request_id, errors

  面向播放器的屏幕（/screen/）和媒体（/media/）路由、配对流和探测路由（/.ready，/.health）的错误文档：所有成员平铺在顶层。商店发布的播放器读取其顶层代码和操作（docs/player-compatibility.md §5），因此此结构保持不变；其他路由返回 Problem。

• RuntimeRect — 必填: x, y, width, height
• RuntimeReport — 必填: none

  报告体和上下文容错读取（docs/player-compatibility.md §1.1）。代码需自带上下文成员；其他成员忽略。播放器仍仅发送以下成员，因预合约后端拒绝其他成员。

• RuntimeScreenLabel — 必填: screen_label

  存储的屏幕名称，即清单携带的 screen_label 值。

• RuntimeScreenLabelWrite — 必填: screen_label

  PUT /screen/screen-label 请求体。服务器会去除 screen_label 首尾的空白，并存储 1 到 120 个字符，不含控制字符。未知成员被忽略（docs/player-compatibility.md §1.1）。

• RuntimeScreenPlaylist — 必填: playlist_id

  更改后的屏幕分配播放列表。

• RuntimeScreenPlaylistWrite — 必填: playlist_id

  PUT /screen/playlist 请求体。未知成员被忽略（docs/player-compatibility.md §1.1）。

• RuntimeScreenPlaylists — 必填: playlists, more

  屏幕设备上的播放列表选择器提供的播放列表，按名称字母顺序排序，不区分大小写，再按 id 排序。

• RuntimeSelectorPlaylistSnapshot — 必填: selections, pageMaxMs

  一个堆栈播放列表的选择项，以该播放列表自身的页面 ID 命名。

• RuntimeSelectorSnapshot — 必填: manifestRevision, snapshotRevision, selections, pageMaxMs
• RuntimeSession — 必填: paired, capabilities, event_cursor, public_url

  运行时拥有的会话（docs/player-compatibility.md §8）。读取器忽略未知成员和未知能力值。仅向授权覆盖的新成员发送。

• RuntimeSessionRequest — 必填: public_id

  匿名观众铸造。未知成员被忽略（docs/player-compatibility.md §1.1）。

• RuntimeStack — 必填: levels, playlists

  屏幕堆栈的每个层级，只发送给声明了 schedule.stack 主机能力的 Player，且仅当堆栈有多个层级时发送（docs/player-compatibility.md §6.11）。清单的根成员是最底层的播放列表；Player 用排程契约自行解析各层级。

• RuntimeStackPlaylist — 必填: playlistRevision, pages
• RuntimeStatusWrite — 必填: observed_at, chip

  PUT /screen/status 请求体。未知成员被忽略（docs/player-compatibility.md §1.1）。存储值为项目 ScreenStatus。

• RuntimeStorageWrite — 必填: observed_at, volume, cache, durability, plan, transfer_24h

  PUT /screen/storage 的主体。未知成员被忽略（docs/player-compatibility.md §1.1）。存储的值是项目 ScreenStorage 加服务器 received_at。

• RuntimeStreamPrimitive — 必填: id, primitive, sources, muted, fallback, grantId, rect, layer, contentFit
• RuntimeSuspension — 必填: message, since

  屏幕处于暂停状态时输出（docs/player-compatibility.md §6.9）：pages 为 []，没有 diagnostics，播放器会把 message 显示为全屏通知，而不是无内容界面。since 是屏幕首次被暂停的时间。清单修订版本是该通知自身的，绝不是某个播放列表的，且屏幕无需分配播放列表。

• RuntimeTelemetryBatch — 必填: telemetry_epoch, stream_id, sequence, created_at, reports

  持久的 FIFO 播放器队列每分钟最多发送一个普通批次，带随机相位，或满时提前发送。JSON 总体积最多 256 KiB；最多 64 条报告，每条最多 32 KiB。每条报告保留发生时间戳和稳定的 play_id。

  保持磁盘上有一个不可变的正在进行的批次，直到收到202响应，只有在确认后才递增序列号，丢失回复或重启后重试相同字节。序列号从1开始且无间隙。

  去重每个屏幕最多保留八个直播流，每个水印至少保留 24 小时，在此期间其批次仍可重播；凭证续期时保持相同流。记录在本地 24 小时后过期并有明确计数。manifest.activated 和 manifest.upgrade 保持独立且即时。

  互动写入、广告分辨率、内容获取、截图和 SDK 的 emitConfirmed() 也保持即时。健康采样保持十五分钟节奏；紧急显示/健康状态转换立即发送。观察和普通健康快照以最新为准，保留原始发生时间。健康需要 health.write 权限。

  现有单个报告仍被接受。报告项目滥用限制按新项目而非 HTTP 信封应用；提交的重放仅消耗请求许可。

• RuntimeTransition — 必填: type, durationMs

  创作页面过渡。普通移动保留字体、持续时间和可选装饰。Stinger在两层之上携带正常卡片内容形状。缺少代码或播放器解释器不兼容时，仅将过渡降级为相同持续时间的交叉淡入淡出，并带有transition_unavailable诊断。

• RuntimeTransitionCard — 必填: primitive, card, major, params, version, src, sha256, model, requires

  与画布卡相同的投影卡内容，无画布放置几何。Stinger 固定为主版本 1；参数包括 durationMs 和 hangMs。

• RuntimeUpgradeNotice — 必填: state, player_kind, recommended

  当播放器的可比版本低于player_kind推荐版本（docs/player-compatibility.md §6.1）时，在mint响应中出现。播放器启动平台更新检查，屏幕无显示。阅读器忽略未知状态的成员。

• RuntimeVerbosity — 必填: none

  播放器生成并显示的最低日志级别和提示级别（docs/player-compatibility.md §6.12）。当屏幕设置了其中任何一个时，每个会话都会发送；未设置的成员会被省略。错误始终会生成并显示。播放器会忽略未知的成员或值，并保留其默认值。

• RuntimeVideoPrimitive — 必填: id, primitive, selector, resolvedMedia, muted, loop, grantId, rect, layer, contentFit
• RuntimeVideoResolvedMedia — 必填: mediaId, src, intrinsicSize, sha256, bytes, contentType
• RuntimeWall — 必填: outputs, arrangement, rotation, span

  屏幕的视频墙，由其播放器布局（docs/player-compatibility.md §6.8）。仅当屏幕有墙时发出。忽略未知成员。

• SCIMError — 必填: schemas, status

  RFC 7644 第 3.12 节错误文档。

• SCIMEvent — 必填: at, action, status
• SCIMEventList — 必填: events
• SCIMGroupList — 必填: groups
• SCIMGroupProjectBinding — 必填: binding_id, project_id, project_name, role
• SCIMGroupSummary — 必填: id, display_name, member_count, bindings
• SCIMResource — 必填: none

  符合 RFC 7643 和 RFC 7644 在承载它的路由上所给出形态的 SCIM 2.0 文档；每个操作会指明具体是哪一种。它是 User 或 Group 资源、ListResponse、PatchOp 消息、ServiceProviderConfig、ResourceType 或 Schema。screenRIG 不使用的成员会被接受并忽略。

• SCIMSettings — 必填: enabled, base_url, tokens, user_count, group_count
• SCIMSettingsWrite — 必填: enabled, proof
• SCIMToken — 必填: id, name, prefix, created_at
• SCIMTokenCreate — 必填: name, proof
• SCIMTokenCreated — 必填: id, name, prefix, created_at, token

  SCIMToken 及其密钥，仅返回一次。

• SSODiscovery — 必填: sso, required, account

  该地址如何登录或注册。sso、required 和 provider_name 仅由地址的域名决定；account 表示是否有现有人员持有该地址。

• SSODiscoveryRequest — 必填: email
• SSOErrorCode — 必填: none

  单点登录未完成时所带的稳定代码：POST /api/sso/finish 重定向到的地址中 #sso_error= 的值，以及失败的身份提供者测试的代码。no_email：提供者未断言任何电子邮件地址。email_unverified：提供者将该地址标记为未验证。domain_not_allowed：该地址不在组织的任何已验证域名下。account_exists：该地址已属于一个有自己登录方式的账户；该人员照常登录，并从其账户中关联该身份（intent link）。managed_elsewhere：另一个组织管理该人员。subject_mismatch：该账户已关联到同一提供者处的另一个身份。not_provisioned：无人持有该地址，且连接不创建人员。sso_required：组织要求该地址使用单点登录。staff_account：screenRIG 员工账户绝不会被客户的身份提供者登录、接管或关联。expired：登录超过了其 10 分钟时限。bad_state：登录的 state 或浏览器绑定不匹配，或已被使用过。interaction_required：静默续期需要人员操作。provider_refused：提供者返回了错误。provider_unavailable：无法连接或读取提供者。verification_failed：提供者的令牌或断言未通过验证。deactivated：该人员已被停用。

• SSOPolicy — 必填: required, break_glass_user_ids, passkey_admin_ids, policy_revision
• SSOPolicyWrite — 必填: required, break_glass_user_ids, proof
• SSOStart — 必填: redirect_url
• SSOStartRequest — 必填: email
• SSOTestStart — 必填: redirect_url
• ScheduleCalendar — 必填: subject, from, to, screens, groups
• ScheduleCalendarConflict — 必填: kind, level_ids
• ScheduleCalendarGroup — 必填: key, screens, screen_ids, displays, levels, spans, on_screen, conflicts
• ScheduleCalendarOnScreen — 必填: display, from, to
• ScheduleCalendarSpan — 必填: level_id, from, to, state
• ScheduleImportCommitted — 必填: preview, applied
• ScheduleImportLevel — 必填: key, action, home, content, screens, priority, rows
• ScheduleImportPreview — 必填: name, columns, valid, fingerprint, summary, rows, levels, removals
• ScheduleImportRemoval — 必填: home
• ScheduleImportRequest — 必填: rows
• ScheduleImportResolved — 必填: kind, id, name
• ScheduleImportRow — 必填: row, status
• ScheduleImportRowError — 必填: code, message
• ScheduleImportSummary — 必填: rows, rows_with_errors, levels, creates, updates, unchanged, removes, screens, playlists
• SchedulePreview — 必填: gained, lost, calendar

  活动或排程写入会更改什么。gained 是将携带该写入的某个层级而现在没有的屏幕，lost 是现在携带而之后不再携带的屏幕；留在堆栈上的层级两者都不变，并显示在 calendar 中。

• SchedulePreviewReach — 必填: count, screen_ids
• Screen — 必填: id, public_id, label, revision, manifest_revision, manifest_upgrade, content_access_generation, state, online, created_at, updated_at
• ScreenAction — 必填: none

  一个舰队操作，按类型区分。每个成员仅携带自身参数；不同类型的成员视为未知字段和 invalid_request。

• ScreenActionAddTags — 必填: type, tags

  添加屏幕尚未携带的标签。超过 16 个标签的屏幕会因 invalid_request 失败。

• ScreenActionAssign — 必填: type, playlist_id
• ScreenActionClearDisplaySchedule — 必填: type

  移除每个屏幕的显示排程；无排程的屏幕保持正常且不变。

• ScreenActionClearPlaylist — 必填: type

  清除每个屏幕自己的默认播放列表，保留配对和其他内容层级。没有有效内容时，Player 显示待机画面。与分配一样属于审核类操作。

• ScreenActionClearPlaylistSchedule — 必填: type

  移除每个屏幕的播放列表排程；无排程的屏幕保持正常且不变。

• ScreenActionClearRebootSchedule — 必填: type

  移除每个屏幕的重启排程；没有排程的屏幕为 ok 且不变。仅限管理权限。

• ScreenActionDisplay — 必填: type, power

  与 ScreenDisplayWrite 相同的规则。当 Idempotency-Key 没有车队记录时，until 会针对请求时钟进行检查，然后由每个屏幕再次检查。

• ScreenActionDisplayClear — 必填: type

  结束每个屏幕的手动显示覆盖（DELETE /api/screens/{id}/display）；无覆盖的屏幕正常且不变。

• ScreenActionMaintenance — 必填: type

  对每个屏幕使用 POST /api/screens/{id}/clear-cache、/restart-app 或 /update；其主机未声明该能力的屏幕会单独失败并返回 command_unsupported。离线屏幕将命令保持为 queued，直到其上线（expires_in_s）。

• ScreenActionReboot — 必填: type

  对每个屏幕执行 POST /api/screens/{id}/reboot；其主机未声明 reboot 的屏幕会单独失败并返回 reboot_unsupported。离线屏幕会将重启保持为 queued，直到上线（expires_in_s）。

• ScreenActionReload — 必填: type

  对每个屏幕执行 POST /api/screens/{id}/reload。离线屏幕会将重新加载保持为 queued，直到上线（expires_in_s）。

• ScreenActionRemoveTags — 必填: type, tags

  移除列出的标签；屏幕未携带的标签被忽略。

• ScreenActionRequest — 必填: selector, action
• ScreenActionResult — 必填: action, matched, succeeded, failed, results
• ScreenActionScreenResult — 必填: screen_id, status

  单个屏幕的结果。ok 携带单屏幕路径的结果：assign、tag、takeover、takeover_clear、set_playlist_schedule、clear_playlist_schedule、set_reboot_schedule 和 clear_reboot_schedule 动作为 revision（标签动作还有 tags），reload 为 reload，toast 为 toast。failed 携带该屏幕自己的请求本应返回的问题。

• ScreenActionSelector — 必填: none
• ScreenActionSelectorFolder — 必填: by, folder_id

  屏幕文件夹及其内部每个文件夹中的所有活动屏幕，按创建顺序。无屏幕数量限制。

• ScreenActionSelectorIds — 必填: by, screen_ids
• ScreenActionSelectorTag — 必填: by, tag

  每个标签包含 tag 的活动屏幕，按创建顺序。无屏幕数量限制。

• ScreenActionSetDisplaySchedule — 必填: type, enabled, windows

  替换每个屏幕的显示排程（ScreenDisplayScheduleWrite），在分发前统一规范。无时区的屏幕单独失败，返回invalid_request。

• ScreenActionSetPlaylistSchedule — 必填: type, entries

  用相同条目替换每个屏幕的播放列表排程（ScreenPlaylistScheduleWrite）。条目ID在分发前分配。无时区或无默认播放列表的屏幕单独失败，返回invalid_request。

• ScreenActionSetRebootSchedule — 必填: type, enabled, windows

  替换每个屏幕的重启排程（ScreenRebootScheduleWrite），分发之前统一规范化一次。仅限管理权限。没有时区的屏幕单独以 invalid_request 失败，播放器未声明 reboot 的屏幕以 reboot_unsupported 失败。

• ScreenActionSetTags — 必填: type, tags

  替换每个屏幕的标签集；空数组表示清空。

• ScreenActionTakeover — 必填: type, playlist_id

  与 ScreenTakeoverWrite 相同的规则。当 Idempotency-Key 没有车队记录时，until 会在分发前针对请求时钟进行检查，然后由每个屏幕再次检查。

• ScreenActionTakeoverClear — 必填: type

  结束每个屏幕的接管；无接管的屏幕正常且不变。

• ScreenActionToast — 必填: type, level, text

  与 ScreenToastWrite 相同的级别、文本和持续时间规则，在分发前验证一次。

• ScreenCampaigns — 必填: screen_id, items
• ScreenCommand — 必填: id, type, state, requested_at, expires_at

  向屏幕发出的一次重启、重新加载、clear_cache、restart_app 或 update 请求，位于 Screen.commands 中。发送给在线屏幕的命令存为 sent。

  向离线屏幕发出的命令存为 queued 且没有运行时事件；当后端在 expires_at 之前处理该屏幕的下一次上线状态转换时，会追加该事件（id 和 expires_at 与此命令相同），命令变为 sent。

  每条命令恰好对应一个运行时事件，因此播放器不会看到两次。超过 expires_at 的排队命令在读取时推导为 expired。同类型的较新命令会取代仍在排队的命令。已发送的重启在携带 uptime_s 的健康报告表明开机时间晚于 sent_at 时变为 done；重新加载永远不会变为 done。

  clear_cache、restart_app 或 update 在其播放器报告后变为 done 或 failed，并附带 cause 和 detail。

• ScreenCommandPage — 必填: items, next_cursor
• ScreenCommandWrite — 必填: none

  POST /api/screens/{id}/reboot、/reload、/clear-cache、/restart-app 和 /update 的可选请求体。请求体为空时使用默认值。

• ScreenDeviceSettingsPatch — 必填: none

  对屏幕的空闲变暗和亮度设置以及自助终端锁定的更改（patchScreenDeviceSettings）。请求体至少包含这两个成员之一，不含其他成员。

• ScreenDisplay — 必填: requested, source

  显示电源状态。requested 是屏幕当前应显示的状态：活动覆盖，否则屏幕时区内评估的启用显示排程，否则为开启（来源为覆盖、排程或默认）；until 是下次变更的时间（已知时）。reported 是播放器最新的健康显示（电源、连接、reported_at，35 分钟后过期）。idle 和 brightness 是屏幕的 display.idle 和 display.brightness 设置（由 ScreenPatch 设置）。

  当屏幕无排程、无覆盖、无空闲变暗或亮度设置且无报告显示时缺失。

• ScreenDisplayBrightness — 必填: mode

  display.brightness：auto 将设备的环境光线映射为窗口亮度；fixed（默认值）保持操作员设定的亮度。由声明了主机能力 brightness.auto 的播放器应用，播放器仅在设备具备光线传感器时才声明它。

• ScreenDisplayIdle — 必填: after_s, wake

  display.idle：屏幕在持续 after_s 秒没有触摸或按键，或在 wake 列出 presence 时屏幕前无人（使用设备的摄像头，在设备上分析；不会有图像离开设备）之后变暗。唤醒事件会立即让其重新亮起，唤醒变暗屏幕的那次触摸会被消耗。

  屏幕变暗期间，播放器处于显示关闭状态，与显示排程相同：暂停播放（无播放记录，无广告），在健康报告中报告 display.power off，并在唤醒时恢复。让面板保持关闭的显示排程或覆盖优先；页面在屏幕上时，持有 device.display 的应用程序优先于 idle。

  由声明了主机能力 display_power.idle 的播放器应用。

• ScreenDisplayOverride — 必填: override_id, power, until, ends_at, set_at
• ScreenDisplayPatch — 必填: none
• ScreenDisplayReported — 必填: reported_at, stale

  播放器最近的显示器健康报告。观察到的电源和连接状态，与请求的电源状态无关。超过 35 分钟没有报告后，stale 为真；这只是背景信息，不能证明电源导致了截图失败。

• ScreenDisplaySchedule — 必填: enabled, windows, updated_at
• ScreenDisplayScheduleView — 必填: display_schedule
• ScreenDisplayScheduleWrite — 必填: enabled, windows
• ScreenDisplayWrite — 必填: power
• ScreenEffectivePlaylist — 必填: id, source

  屏幕运行时清单构建所依据的播放列表：接管播放列表，否则是第一个适用的活动（entry_id 是活动 id），否则是第一个匹配的播放列表排程条目（entry_id），否则是分配的默认播放列表，否则是包含该屏幕的最近文件夹的默认播放列表（source 为 folder，entry_id 是文件夹 id）。until 是下一次已知变化的时刻（接管结束或八天内的下一个排程边界），无时间变化时缺失。

  边界工作线程最多延迟 60 秒应用更改。无法显示播放列表的接管或条目被跳过。屏幕无播放列表时缺失。

• ScreenExplainAt — 必填: instant, effective_playlist, verdicts, not_judged

  屏幕在 instant 显示的内容及原因，来自边界扫描运行的解析器。屏幕的接管、播放列表排程和项目的活动按其现在的状态读取，而非当时的状态。播放列表缺失或未批准的活动会被跳过，与扫描的做法一致。

  在 Player 解析自身堆栈（schedule.stack）的屏幕上，判定读取该堆栈，not_judged 会说明这一点（player_stack）。

• ScreenFieldsPatch — 必填：fields

  屏幕字段的更改（patchScreenFields）。请求体没有其他成员。

• ScreenFolder — 必填: id, name, parent_id, revision, created_at, updated_at

  一个屏幕文件夹。一个屏幕最多位于一个文件夹中（Screen.folder_id）；文件夹的目标是其屏幕以及其内部每个文件夹的屏幕。

• ScreenFolderCreate — 必填: name
• ScreenFolderDeleteResult — 必填: levels
• ScreenFolderList — 必填: items
• ScreenFolderPatch — 必填: none
• ScreenGlass — 必填: none

  后端根据收到的报告，而不是播放器对自身的说法，对屏幕画面得出的结论。没有结论的检查会使该成员缺省。在项目 API 中只读。绝不用于授权或准入。ScreenPatch 不能写入。

• ScreenGlassChangedDetails — 必填: check, verdict, previous, since, evidence

  持久的、仅限项目的 screen.glass_changed 事件的 details 对象，在某项画面检查改变某块屏幕的判定时追加。它不是运行时受众命令，也不会通过 GET /screen/events 投递。

  当播放判定为 stalled 时，loop_stalled 条件开启，出现其他判定时结束；当画面判定为 blank 或 frozen 时，glass_blank 和 glass_frozen 开启，出现其他判定时结束。

• ScreenHealth — 必填: reported_at, stale

  最新的设备健康报告（PUT /screen/health），已清理，带服务器 reported_at。播放器未发送的成员缺失。当 reported_at 超过 35 分钟时 stale 为真；仍显示过时健康状态，永不删除；归档和屏幕恢复会清除它。

  状态转换会追加仅限项目的 screen.health_changed，带 details.changes，即 {change, ...} 列表：display_disconnected、display_reconnected、display_power（from、to）、temperature_high（达到或超过 80 °C）、temperature_normal（再次低于 75 °C）、on_battery（battery.source 变为 none；上报时附带 level_percent）、plugged_in（再次出现任何其他来源；source）、crash_spike 和 renderer_restart_spike（24 小时计数自上次峰值事件起增加 3 或更多；crashes_24h 或 renderer_restarts_24h 以及 previous）。仅当设备上报电池时才有 battery；后端除读取 battery.source 以判断 on_battery 条件外，不读取其任何内容，也不推断原因。

  只读；绝不授权。

• ScreenHealthHistory — 必填: none

  报告页面（分辨率为 raw）或小时汇总页面（分辨率为 hour）。

• ScreenHealthHour — 必填: hour, reports, temperature_max_c, temperature_avg_c, cpu_load_max, memory_used_ratio_max, wifi_rssi_min_dbm, display_disconnected, crashes_24h_max, renderer_restarts_24h_max, last_reported_at

  单个屏幕在一个 UTC 小时内的报告。若该小时无报告，则成员为 null。

• ScreenHealthHours — 必填: resolution, hours, next_cursor
• ScreenHealthSample — 必填: reported_at

  一个存储的设备健康报告：Screen.health，去除过期数据，且不含 cpu.utilization_percent 和 cpu.app_percent，这两个仅最新报告（Screen.health）携带。播放器未发送的成员缺失。

• ScreenHealthSamples — 必填: resolution, samples, next_cursor
• ScreenIdentifyAccepted — 必填: identify_id, duration_ms, expires_at
• ScreenIdentifyDetails — 必填: identify_id, label, screen_id, duration_ms, at, expires_at

  持久 player.identify 事件的 details 对象。

• ScreenIdentifyWrite — 必填: none
• ScreenKiosk — 必填: lock

  kiosk.lock：播放器将自身固定在屏幕上（使用 startLockTask 的 Android 屏幕固定；屏幕前的人员首次需要确认，固定期间状态栏、主屏幕和最近任务均被禁用；作为设备所有者的托管版本保持其锁定任务）。仅在锁定开启时存在。

  操作员设置面板提供“退出自助终端锁定”，可解除固定，直到下一次清单或重启再次应用它。由声明了主机能力 kiosk_lock 的播放器应用。

• ScreenKioskPatch — 必填: lock
• ScreenLevelChange — 必填: source, id, playlist_id, screens
• ScreenLevelChanges — 必填: gained, lost

  写入对其所更改屏幕的排程的影响：这些屏幕进入（gained）或离开（lost）受众的活动，以及开始或停止成为其默认播放列表的文件夹默认播放列表。screens 按级别统计受影响的屏幕数。

  标签写入时，活动条目会报告受众成员变化：屏幕进入或离开的每个实时活动，无论该活动是否在那里播放，这取决于屏幕的默认播放列表。移动或文件夹更改会列出其文件夹受众在播放这些活动的屏幕上发生变动的活动。

• ScreenLink — 必填: hint, created_at

  一个 Player URL，可在不保留存储的浏览器中打开一个屏幕，例如 vMix 或 OBS 的浏览器源。

• ScreenLinkSessionRequest — 必填: screen_link

  屏幕链接密钥，加上可选的 host、playback 和 player 提示。未知成员会被忽略，host、playback 和 player 按宽松方式读取（docs/player-compatibility.md §1.1）。密钥是一种凭据：绝不记录或回显。

• ScreenLinkSummary — 必填: hint, created_at

  屏幕的链接，不含其 url。仅在屏幕有链接时存在。只读；POST 和 DELETE /api/screens/{id}/link 可更改它。

• ScreenList — 必填: items
• ScreenLocation — required: latitude, longitude

  屏幕所在的位置，以十进制度数表示，并可附带简短的地名和街道地址。卡片放置项通过 {screen.location} 占位符读取它，屏幕列表则可按到某个点的距离筛选（near）。

• ScreenLocationPatch — 必填：location

  屏幕所在位置的更改（patchScreenLocation）。请求体没有其他成员。

• ScreenMaintenanceAccepted — 必填: command_id, command, expires_at, state
• ScreenManifestUpgrade — 必填: desired_revision, active_revision, desired_playlist, active_playlist, state, code, attempt, retry_at, missing_page_count, state_since, reported_at

  此屏幕始终存在的计算清单升级状态，在读取时从其发布的期望修订版或排队的共享播放列表内容目标、最后服务器确认的活动清单修订版（manifest.activated）和最新接受的 manifest.upgrade 报告槽派生。

  只读项目状态：无正文可写，报告也不会提升授权。active_revision 是最后确认的激活，不代表所有会话均已显示。

  离线状态从不导致失败，重试状态下的过期retry_at是客户端表现，非服务器判断。desired_revision为null表示无。pending状态表示期望修订无匹配报告；activating表示目标已在屏幕上但确认仍待完成；修订不匹配desired_revision的报告插槽被忽略，直到新报告匹配，因此新期望清单派生为pending且不清除任何内容。

  在下一次清单联系发布共享编辑的期望授权、期望修订和播放列表之前，可以将该排队目标作为只读意图公开；它不授予访问权限。活动身份始终来自确切确认的历史授权。较旧的激活不能将较新的排队目标宣布为当前。

• ScreenMove — 必填: folder_id

  screen_ids 和 folder_ids 中至少有一个 ID，总数最多 1000。

• ScreenMoveResult — 必填: screens, folders, levels
• ScreenNamePatch — 必填: name

  屏幕的新名称（patchScreenName）。请求体没有其他成员。

• ScreenNotJudged — 必填: code, detail

  解释不作判断的内容。

• ScreenObservation — 必填: observed_at, surfaces

  播放器报告的播放表面。在屏幕上缺失，直到首次接受的PUT /screen/observation.。在项目API上只读；ScreenPatch、PairScreen、配对主体、会话主体、画布、运行时清单和POST /screen/reports无法写入。

• ScreenObservationSurface — 必填: id, width, height, pixel_ratio, presentation
• ScreenOutage — 必填: offline_since

  屏幕最近一次在线状态中断，以及在屏幕恢复后的首份健康报告做出判定时，屏幕消失的原因。新的中断会替换它；自开始记录中断以来从未离线的屏幕则没有。

  原因来自该报告中 Player 自身的运行时长计数器，对照停机时段读取，绝不对照设备时钟：device_restart（设备在停机开始后启动）、app_crash（Player 启动且其 24 小时崩溃计数上升）、app_restart（Player 启动而设备没有）、network（两者都没有启动，且没有任何迹象指向 screenRIG）以及 platform（两者都没有启动，且停机期间有 player.stream_down 报告送达 screenRIG，或屏幕失声时在线状态观察器已停止或正在恢复）。未知时 likely_cause 不会出现，宁可保持未知也不猜测：没有运行时长的报告、离停机开始太近的报告、屏幕恢复之后才发生的重启，以及重新连接一分钟内的 Player 报告，都不做判定。

  报告只在屏幕恢复后的 35 分钟内做出判断。device_restart 无法区分断电和重启，network 无法区分屏幕自身的网络和其上游网络。

  判定后会追加一次仅限项目的事件 screen.outage_classified，详细信息为 {offline_since, back_at, likely_cause, evidence, online_event_id}；离线屏幕的已解决通知会在通知发出时已判定的情况下指出原因。读取方应把不认识的 likely_cause 当作 unknown。只读；绝不用于授权。

• ScreenPatch — 必填: none
• ScreenPlayPageAccepted — 必填: screen_id, playlist_id, page_id, manifest_revision, expires_at
• ScreenPlayPageDetails — 必填: page_id, playlist_id, manifest_revision, expires_at

  durable player.play_page 事件的详细对象。

• ScreenPlayPageWrite — 必填: page_id
• ScreenPlayerIdentity — 必填: legacy, seen_at

  从最新配对运行时 mint 断言身份。只读显示元数据，绝不授权。内部授权和 mint 字段被保留。

• ScreenPlaylistPatch — 必填: playlist_id

  屏幕播放列表的分配（patchScreenPlaylist）。请求体没有其他成员。

• ScreenPlaylistSchedule — 必填: entries, updated_at

  服务器评估的播放列表排程。它永远不会到达运行时清单；清单是从它选择的有效播放列表构建的。使用 PUT /api/screens/{id}/playlist-schedule. 写入。

• ScreenPlaylistScheduleView — 必填: entries
• ScreenPlaylistScheduleWrite — 必填: entries
• ScreenPresenceHistory — 必填: items, next_cursor
• ScreenPresenceTransition — 必填: at, state
• ScreenProvisioning — 必填: screen, public_url, provisioning_url, expires_at
• ScreenRebootAccepted — 必填: reboot_id, expires_at, state
• ScreenRebootSchedule — 必填: enabled, windows, updated_at

  后端重启屏幕的窗口。设置后才存在。

• ScreenRebootScheduleView — 必填: reboot_schedule, next_reboot_at
• ScreenRebootScheduleWrite — 必填: enabled, windows
• ScreenRecoveryHost — 必填: none

  请求恢复此屏幕的设备所报告的内容，复制自配对开始的主机对象。仅描述字段；绝不包含 duid、序列号或 mac。缺失字段未报告。

• ScreenRecoveryPending — 必填: expires_at

  当呈现此屏幕硬件身份的本地配对会话等待拥有项目通过POST /api/screens/{id}/recovery/confirm.确认时存在。携带截止时间，即配对会话自身的过期时间，以及提供设备的描述性主机字段（绝不包括duid、序列号或mac）。

  DUID 可被面板上的任何应用读取，因此报价是钓鱼面：确认前请将 host.model 和 host.firmware 与面前显示器比对。

  当屏幕绑定密钥在最近十分钟内显示活跃（会话铸造、运行时流、清单获取或存在心跳）时，服务器拒绝报价，每个屏幕每滚动小时最多接受三次报价；新报价替换待处理报价。确认后缺失、过期或作为新屏幕认领。只读。

• ScreenReloadAccepted — 必填: reload_id, expires_at, state
• ScreenReplaceWrite — 必填: with
• ScreenScheduleEntry — 必填: id, playlist_id
• ScreenScheduleEntryWrite — 必填: playlist_id

  一个播放列表排程条目，是屏幕自身堆栈的一个层级（packages/schedule-contract SEMANTICS.md，Levels and the stack）。id 可选（省略时按顺序分配 entry_N），且在排程中唯一。

  它在其所有规则成员都生效时生效：from（含）和 until（不含），为精确到分钟、不带偏移的民用边界；windows、monthly 或 dates 的某次出现（三者都没有则每天重复），且其日期不在 except 中；data，卡片数据条件；interaction，有人正在使用屏幕时。

  条目至少设置一个规则成员。data、interaction、covers 以及排除了部分输出的 displays 锁定，由能自行解析堆栈的播放器遵循；服务器对其他播放器的解析会跳过此类条目（stack_only）。

• ScreenSchedulePreviewRequest — 必填: entries
• ScreenScheduleRevision — 必填: revision, created_at, change, current, entries

  屏幕播放列表排程的一个已存储修订：某次写入之后其完整的 entries 列表（无 entries：该屏幕没有排程）。revision 是写入时屏幕的修订。change 为 edited、restored（更早修订的副本，由 restored_from 指明）或 baseline（屏幕历史开始时所持有的排程）。

• ScreenScheduleRevisionList — 必填: items
• ScreenScheduleWindow — 必填: days

  屏幕时区内的一个 screenrig.schedule/v1 窗口。天数按周一至周日存储。省略开始和结束表示全天。end <= start 表示跨午夜，起始日拥有该时间段（如周五 22:00-02:00 跨入周六凌晨）；相等边界表示全天 24 小时。

• ScreenScope — 必填: folder_ids, screen_ids

  带范围的成员或智能体可以操作的内容（docs/screen-scope.md）：所列屏幕文件夹及其内部每个文件夹中的屏幕，以及所列屏幕。所有 ID 中至少一个。写入时不指向项目现存文件夹或屏幕的 ID，在其位置为 invalid_request；之后的删除会留下不授予任何权限的无效 ID。

  范围在每次请求时读取，因此更改会在下一次请求时生效。标签永远不是范围。

• ScreenScreenshotAccepted — 必填: capture_id, expires_at
• ScreenScreenshotFailedDetails — 必填: capture_id, reason

  durable screen.screenshot_failed 事件的详细对象。

• ScreenScreenshotReadyDetails — 必填: capture_id, bytes, width, height, sha256

  durable screen.screenshot_ready 事件的详细对象。不包含像素和对象键。

• ScreenScreenshotRequestedDetails — 必填: capture_id, expires_at, max_width_divisor, max_height_divisor, format, quality, max_bytes

  durable screen.screenshot_requested 事件的详细对象。不包含图像字节和对象键。

• ScreenScreenshotStatus — 必填: state
• ScreenStackStatus — 必填: manifest_revision, levels, playing, reported_at

  屏幕的 Player 最后报告的其堆栈情况（docs/player-compatibility.md §6.11）：每个层级的就绪状态，以及每个显示器在每个区域（页面和任何条带）显示的层级。仅对自行解析堆栈的 Player 提供，且仅在该堆栈为当前时。

• ScreenStatus — 必填: chip, observed_at, received_at

  屏幕的播放器最近一次通过 PUT /screen/status 报告的状态芯片（docs/player-compatibility.md §9.5）：在排名中胜出的 screenrig.overlay/v1 条件；播放器不显示芯片时为 null。在首次接受的报告之前不存在。在身份重置、取消配对和归档时清除。

  这是播放器的最后一次报告，因此当屏幕不在线（Screen.online）时，消费者将其视为过时，与所有播放器报告相同。level 和 icon 取自后端目录中 chip 对应的条目，绝非来自播放器，chip 为 null 时不存在。项目 API 只读。绝不授权或许可。ScreenPatch 无法写入。

• ScreenStatusChangedDetails — 必填: chip

  持久的仅限项目的 screen.status_changed 事件的详细对象，在 PUT /screen/status 更改已存储的 chip、level 或 icon 时附加。chip 为 null 时不存在 level 和 icon。此类型不是运行时受众命令，且不会在 GET /screen/events 上传递。

• ScreenStorage — 必填: observed_at, received_at, volume, cache, durability, plan, transfer_24h

  已清理的播放器存储报告。在首次接受的PUT /screen/storage.之前缺失。在身份重置、取消配对和归档时清除。消费者将超过24小时的received_at视为过时。项目API只读。绝不授权或许可。ScreenPatch无法写入。

• ScreenStorageCache — 必填: house_used_bytes, capacity_bytes, reserve_bytes, protected_bytes, fallback_bytes, warm_bytes, ad_headroom_bytes
• ScreenStorageExcludedPage — 必填: page_id, reason
• ScreenStorageForecast — 必填: manifest_revision, fit, excluded_page_count, basis, received_at

  近似稳态目标选择（仅计划 A.3，无过渡），基于最后报告的容量和屏幕期望的清单。无存储报告时视为未知，基础为 reported_capacity。存储报告到达及屏幕清单版本变更时重新计算。绝不涉及授权或准入。

• ScreenStorageForecastDryRun — 必填: fit, excluded_page_count, required_bytes, capacity_bytes, basis, received_at

  针对一个播放列表的预分配适配干运行。fit、excluded_page_count和required_bytes来自计划A.3针对屏幕最后报告容量的目标选择（基于reported_capacity）；无过渡预测，且无本地处理。required_bytes为播放列表每页的保留成本。fit未知表示屏幕无存储报告，或播放列表内容引用未准备好；此时required_bytes、capacity_bytes和received_at为null。received_at为存储报告接收时间，超过24小时的报告为陈旧但仍用于预测，类似Screen.storage_forecast。

  只读元数据，绝不作为授权或准入。

• ScreenStorageForecastRequest — 必填: playlist_id

  预分配适配干运行的正文。playlist_id必须是经过身份验证项目的播放列表；其他项目或未知ID返回not_found。

• ScreenStoragePlan — 必填: manifest_revision, fit, transition, required_bytes, target_bytes, excluded_pages
• ScreenStorageShortfall — 必填: at, fit, required_bytes, capacity_bytes, excluded_page_count

  当播放器报告的适配为部分、transition_blocked或none_fit时存在，除非是唯一阻塞原因是anchor_unavailable的transition_blocked计划：那是设备有空间但下载失败，而非空间不足。at是条件开始时间。

  条件开始时设置，结束时移除，每次转换附加一个仅项目事件，screen.storage_shortfall 或 screen.storage_shortfall_cleared。这些事件不会在 GET /screen/events. 时传递。身份重置、取消配对和归档时通过 Screen.storage 清除。

  只读项目健康元数据；不更改屏幕修订版或清单权限，且绝不授权。

• ScreenStorageTransfer — 必填: new, refetch, repair, failed
• ScreenStorageVolume — 必填: total_bytes, available_bytes
• ScreenSurfaceChangedDetails — 必填: observed_at, surfaces

  持久screen.surface_changed项目事件的详细对象。不包含像素。此类型不是运行时受众命令，且不会在GET /screen/events.上交付

• ScreenSuspendWrite — 必填: message
• ScreenSuspension — 必填: message, since

  屏幕处于暂停状态时存在（docs/player-compatibility.md §6.9）。运行时清单以其 suspension 成员携带同一个对象。

• ScreenTags — 必填: none

  设备组选择器标签，0 到 16 个唯一且精确的标签，每个标签符合媒体标签语法。在 ScreenPatch 中，数组替换整个集合，空数组则清空；重复或格式错误的标签为 invalid_request。更改标签会提升屏幕版本（If-Match 保护），并附加 screen.updated，详情见 details.tags；不会更改清单版本。

  标签永远不会出现在运行时清单中，也不会用于授权。

• ScreenTagsPatch — 必填: tags

  屏幕的完整新标签集（patchScreenTags）。数组替换屏幕携带的所有标签，空数组清除所有标签。正文无其他成员。

• ScreenTakeover — 必填: playlist_id, until, set_at

  优先于广告活动、排程和分配的播放列表，直到 until 指定的时间；若 until 为 null，则直到被清除。

• ScreenTakeoverWrite — 必填: playlist_id
• ScreenTimelineSegment — 必填: from, to, source
• ScreenToastAccepted — 必填: expires_at
• ScreenToastDetails — 必填: level, text, duration_ms, expires_at

  durable screen.toast 事件的详细对象。不包含颜色。

• ScreenToastWrite — 必填: level, text
• ScreenUptime — 必填: items
• ScreenVerbosityPatch — 必填: none

  屏幕日志级别和提示级别的更改（patchScreenVerbosity）。请求体至少包含两个成员之一，且不含其他成员。

• ScreenVerdict — 必填: kind, playlist_id, verdict

  所解释时刻的一个候选。won：解析器选中它（在 Player 解析自身堆栈的屏幕上：它填充目标显示器上的自身区域）。outranked：它生效，by 是获胜的候选。not_started：早于其 from。ended：在其 until 或之后（接管则为其结束）。outside_hours：在 from 与 until 之间，但在其时间窗口之外。conditional：在 Player 解析自身堆栈的屏幕上，它满足时间条件，并在仅由 Player 观察的条件也满足时播放（reason interaction 或 data）。off：它不适用，reason 说明原因。

• ScreenWall — 必填: outputs, arrangement

  屏幕播放器布局的视频墙：两到十二个输出显示同一画布。设置需要声明了 display.wall 主机能力的播放器（docs/player-compatibility.md §6.5，§6.8）。带格式的播放列表跨越该视频墙。

• ScreenshotCaptureID — 必填: none

  可选 stage_、qa_ 或 development_ 前缀，然后是 shot_ 和随机后缀。新后缀使用 16 个不含 oOlL 的字母数字字符；接受保留的旧后缀。

• SelectorPreview — 必填: primitive, selector, matched_count, candidates
• SelectorPreviewInput — 必填: primitive, selector
• SelectorPreviewMedia — 必填: media_id, filename, tags
• ServiceClient — 必填: id, project_id, name, capabilities, access, state, created_by, keys, secrets, created_at, updated_at, authenticated_requests, tokens_issued
• ServiceClientChange — 必填: none
• ServiceClientKey — 必填: kid, alg, thumbprint, jwk, added_at
• ServiceClientList — 必填: items
• ServiceClientResult — 必填: client
• ServiceClientSecret — 必填: id, hint, added_at
• SessionDescription — 必填: type, sdp
• SessionSSOStartRequest — 必填: intent
• SignInPolicy — 必填: password, passkey, passkey_enrollment_required, policy_revision, federated

  已验证人员登录策略。被动默认保留本地登录。强制组织策略通过其身份提供者引导登录。

• SignInResetAccepted — 必填: status

  对已知和未知地址相同；不返回地址、凭据、项目或交付状态。

• SignInResetRequest — 必填: email
• SignupCreated — 必填: user_id, project_id, organization_id
• SignupHeardDetail — 必填: none

  heard 的后续回答。kind 指明简短列表中的一项选择，text 为自由文本。

• SignupPasskeyOptionsRequest — 必填: email, display_name
• SignupProfile — 必填: none

  人员在注册后给出的回答。每个成员都是可选的，可以为 null，表示未回答或已跳过。

• SignupRequest — 必填: email, display_name, marketing_email, credential

  电子邮件地址和显示名称与启动该仪式时使用的相同。

• Source — 必填: id, name, kind, target, enabled, config, preset, settings, secrets, refresh_seconds, stale_after_seconds, revision, status, created_at, updated_at
• SourceArea — 必填: key, name, rooms, status, screens
• SourceCreate — 必填: name, target

  JSON、CSV 和 Sheets 配置可设置 key_template，即包含 {screen.field.NAME} 标记的卡片数据键。此时映射生成 {documents:[{fields:{NAME:VALUE},document:{...}}]}，而不是单个文档。每项输出都会按目标卡片进行验证。

  键必须唯一，且位于卡片实例和数据源的命名空间之外；source test 会预览封装结构并验证每项输出。每个键使用该数据源的过期时限。缺失的键保留原有数据和到期时间；存储故障可能留下部分写入，下次运行会重试。

• SourceError — 必填: code, message, at
• SourceKind — 必填: none

  数据的来源。ics 读取 iCalendar 和 webcal:// 地址（其他类型见 /docs/sources）。不可用的类型会在 kind 处返回 invalid_request。

• SourceList — 必填: items, next_cursor
• SourcePreset — 必填: name, title, category, description, kind, cards, fields, secrets, refresh_seconds, min_refresh_seconds, stale_after_seconds, attribution, docs

  json 数据源的一套现成且经过测试的配置。

• SourcePresetAttribution — 必填: text
• SourcePresetCard — 必填: type, default
• SourcePresetField — 必填: name, label, type, required, help

  人要告诉预设的一项内容。文本按 pattern 和 max_length 检查，选择项是 options 之一，列表包含 min_items 到 max_items 个用 fields 填写的对象。

• SourcePresetList — 必填: items
• SourcePresetOption — 必填: value, label
• SourcePresetSecret — 必填: name, label, help, how_to_get, required

  预设所需的凭据，填写在 secrets 的 name 之下。

• SourceRoom — 必填: key, status, screens
• SourceRoomRef — 必填: id, name
• SourceRoomScreen — 必填: id, name, kind, field, value, status
• SourceRooms — 必填: source_id, room_field, room_key_prefix, area_field, area_key_prefix, rooms_as_of, summary, rooms, areas, screens, warnings

  为每个房间或区域写入一份文档的数据源的房间映射：数据源最后一次成功刷新时提供的房间，与读取这些房间的屏幕的对照。

  当屏幕在某字段上有值，或屏幕自己的播放列表放置了数据键为键前缀加 {screen.field.NAME} 的卡片时，该屏幕属于此字段的报告；通过文件夹、活动或日程层级到达的播放列表不会被跟踪。

• SourceRoomsSummary — 必填: rooms, unmapped_rooms, areas, unmapped_areas, screens, missing_screens, unknown_screens
• SourceSecretView — 必填: set, hint, updated_at
• SourceStaleAfter — 必填: none

  数据源无法刷新时，卡片保留其最后一次正常数据的时长，单位为秒。

  数据源写入的文档会在最后一次成功刷新后经过这段时间过期：若持续失败，文档会在所有屏幕（包括离线屏幕）上变空，可见性取决于数据的页面会切换到其后的页面；没有失败的数据源会在刷新时顺延截止时间。

  至少为 refresh_seconds 的两倍。null 会保留最后一次正常的数据，直到数据源再次刷新（除 momentus 外所有类型的默认值；momentus 在创建时省略该成员则为 1800）。失败的数据源超过该时长后即为已过期（status.stale），并追加 source.stale。

• SourceStatus — 必填: state, last_attempt_at, last_success_at, last_change_at, next_run_at, failures, stale, data_expires_at, error, warnings, stats

  最近几次运行的结果。state 为 pending（尚未运行）、ok（最近一次获取成功且卡片接受了文档）、error（最近一次运行失败，卡片保留最后一份有效文档）或 disabled。ok 不判断上游数据是否正确或最新，也不判断是否有屏幕在显示该卡片。

• SourceTarget — 必填: card_id
• SourceTestRequest — 必填: none
• SourceTestResult — 必填: document, valid, warnings, stats, fetched_at
• SourceUpdate — 必填: none
• StackLevel — 必填: id, source, playlist_id

  屏幕堆栈的一个层级（packages/schedule-contract SEMANTICS.md，Levels and the stack）。id 为 takeover、campaign:ID、schedule:ENTRY_ID、default 或 folder:FOLDER_ID；record_id 指明活动、条目或文件夹，name 为活动或文件夹的名称。rule 缺省则始终生效。

• StackLevelRule — 必填: none
• StreamSource — 必填: none
• StreamSourceWrite — 必填: none

  流源。源可以只给出 url，由 URL 方案决定协议：https 为 hls，rtsp 和 rtsps 为 rtsp。

• SupportConversation — 必填: id, subject, created_at, updated_at, last_sequence, human_requested, unread_staff, closed
• SupportConversationList — 必填: items, next, unread_staff_total
• SupportHours — 必填: timezone, start, end, weekdays, excludes_bc_holidays
• SupportMessage — 必填: id, conversation_id, sequence, role, author, body, created_at
• SupportMessageList — 必填: items
• SupportRead — 必填: sequence
• SupportStatus — 必填: chat_allowed, available, staffed, human_available, hours, human_wait_seconds, docs_url
• SupportSubmission — 必填: conversation, message
• SupportWrite — 必填: body
• TabShare — 必填: id, until, screens, skipped, warnings
• TabShareCookie — 必填: name, value, domain

  符合浏览器Cookie API格式的单个Cookie。值属于秘密信息。

• TabShareScreen — 必填: id, label
• TabShareSkip — 必填: id, label, code, detail

  未被接管的目标。code是单独接管该屏幕会返回的问题代码。

• TabShareState — 必填: id, until, screens
• TabShareStopped — 必填: id, screens
• TabShareWarning — 必填: code, url, detail
• TabShareWrite — 必填: tabs

  要显示的标签页及目标屏幕。screen_ids、folder_ids和tags中至少提供一项。

• Trigger — 必填: id, kind, label, target, default_for_seconds, url, username, revision, created_at, updated_at

  CAP 告警触发器或叠加层触发器。其密码只由 create 和 rotate-secret 返回。

• TriggerAlert — 必填: id, revision, state, status, msg_type, sender, identifier, until, screens, started_at, updated_at

  触发器的最新警报，来自 CAP 消息字段。

• TriggerAlertScreens — 必填: targeted, taken_over, cleared, skipped, failed, pending

  最新接管更改的内容。跳过无默认播放列表、已归档或已消失的屏幕；清除时跳过已被其他接管替换的屏幕。

  受保护屏幕文件夹中的屏幕保持原样，并计入 protected，而不是被跳过；结束警报（取消、解除、运营人员清除）仍会清除触发器在该屏幕上设置的内容。

• TriggerClear — 必填: none
• TriggerDelivery — 必填: at, outcome, status, bytes, request_id
• TriggerDeliveryList — 必填: items
• TriggerList — 必填: items
• TriggerOverlay — 必填: show, style, enabled, signing, alerts, screens, pending

  叠加层触发器的配置和状态。

• TriggerOverlayAlert — 必填: id, until, started_at, updated_at, revision
• TriggerOverlayReceipt — 必填: outcome, trigger_id, until, active
• TriggerOverlayRequest — 必填: none

  对叠加层触发器的一次推送，按触发器的 mapping（如果有）处理后读取。解除会忽略除 alert_id、clear 和 state 之外的所有成员。

• TriggerOverlayScreens — 必填: targeted, holding, taken_over, removed, edge_taken, skipped, failed

  最近一次分发对目标屏幕所做的操作。受保护屏幕文件夹中的屏幕保持原样，并计入 protected，而不是被跳过；结束警报仍会清除触发器在它上面设置的内容。

• TriggerOverlayStyle — 必填: none

  绘制叠加层所用的文本卡片静态参数。布局由触发器选择。

• TriggerOverlayWrite — 必填: show
• TriggerPatch — 必填: none
• TriggerReceipt — 必填: outcome, trigger_id
• TriggerSecretRotate — 必填: none
• TriggerTarget — 必填: none

  tag 和 screen_ids 中恰好一个。

• TriggerWithPassword — 必填: none
• TriggerWithSecrets — 必填: none
• TriggerWrite — 必填: label, target
• UDPStreamSource — 必填: protocol, group, port
• URLStreamSource — 必填: url
• UploadScope — 必填: playlist_ids, folder_ids

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

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

• UptimeDay — 必填: day, online_s, offline_s, availability, coverage

  一个 UTC 天。可用性是 online_s 在 online_s 加 offline_s 中的比例，若无记录则为 null。覆盖率是一天内（项目行中每个报告屏幕的天数）有记录状态的比例，范围为 0 到 1：间隙会降低覆盖率，且永远不是离线时间。间隔（屏幕行）表示触及该天的记录间隔数；屏幕（项目行）表示有记录状态的屏幕数；live 标记包含至今开放间隔的屏幕天数。

• UsageFrame — 必填: page_id, primitive_id, rect

  指明该媒体文件的一个图片或视频原语，附带其矩形区域以及文件填充该区域的方式。

• UsageScreen — 必填: id, label, screen, playlist_ids, how

  至少使用了所列播放列表之一的一个活动屏幕。

• UsageScreenHow — 必填: playlist_id, uses
• UsageTagFilter — 必填: all, any, none

  标签选择器的筛选条件。文件需具有 all 中的每个标签；若指定了 any，还需至少具有 any 中的一个标签；并且不得具有 none 中的任何标签，才算匹配。简写的标签选择器即只含一个标签的 all。

• UsageTrack — 必填: index, id
• UserEmailChangeAccepted — 必填: none
• UserEmailChangeRequest — 必填: email, proof

  请求使用新鲜证明更改已验证的电子邮件。验证期间当前邮箱仍有效。旧地址仅收到警告，无撤销链接。

• VerifiedOrganizationDomain — 必填: domain, organization_id, state, verified_at
• VersionResponse — 必填: version, commit, api_version, protocol_version
• Webhook — 必填: id, url, event_types, enabled, revision, status, created_at, updated_at

  项目 webhook。播放器日志记录（runtime.reported）不予传送。

  每个匹配的项目事件都会以 GET /api/events 返回的相同 JSON 对象 POST 到 url，附带 ScreenRig-Webhook-Id、ScreenRig-Event-Id（事件游标，重试时稳定）、User-Agent 和 ScreenRig-Signature t=<unix seconds>,v1=<hex HMAC-SHA256 over "<t>.<raw body>"，使用密钥字符串签名。

  10 秒内返回 2xx 状态即为成功；其他状态、重定向（不跟随）、超时或连接或 TLS 失败将以指数退避（30 秒翻倍至一小时，带抖动）重试 24 小时，之后失败。连续三次超时后，尝试超时降至 5 秒，直到收到响应。

  Webhook 最多有一个尝试在飞行中，项目跨所有服务器最多两个。投递至少一次且无序；基于 ScreenRig-Event-Id 去重。

  每次尝试都像监听流事件一样计量（超出每月 10,000 次 API/SSE 免费额度后，每次消耗 1 个额度），监听流上免费的事件在这里同样免费：screen.*、runtime.*、alert_mute.*、application.event、playback.page_failed 和 agent.command。

  在发送任何内容之前就被拒绝的尝试（url_rejected、dns_failed）不计费。payment_required 和 secret_unavailable 会退避，但绝不计入 failing 或自动禁用。自 failing_since 以来若没有任何投递成功，status 即为 failing；连续失败 72 小时后，该 Webhook 会被禁用（disabled_reason 为 delivery_failures），并追加 notification.disabled。

• WebhookDelivery — 必填: id, webhook_id, event_id, event_type, state, attempts, created_at
• WebhookDeliveryAttempt — 必填: attempt, at, status, error, duration_ms
• WebhookDeliveryAttemptList — 必填: items
• WebhookDeliveryList — 必填: items, next_cursor
• WebhookEventTypes — 必填: none

  精确的事件类型（如 screen.online），或以 .* 结尾的前缀（如 screen.*，即所有以 screen. 开头的类型）。notification.test 永远不会通过订阅分发；它只会由 POST /api/webhooks/{id}/test 发送。

• WebhookHandshake — 必填: none

  URL 所响应的服务商握手，适用于这里没有签名方案的服务商。microsoft_graph 对带有 validationToken 查询参数的 POST，把解码后的令牌以 text/plain 原样返回。monday 对 {"challenge": "..."} 的 JSON POST，返回相同的 JSON。trello 以 200 响应其 HEAD 检查。azure_event_grid 对 SubscriptionValidationEvent（aeg-event-type: SubscriptionValidation），以 {"validationResponse": "<validationCode>"} 响应。verify.vendor slack 响应 Slack 签名的 url_verification 质询，verify.vendor asana 响应 Asana 的 X-Hook-Secret 握手，并保留该密钥用于验证其事件。

  握手只会针对为该服务商设置的 webhook 响应，不写入任何内容，从不计费，也不消耗速率额度，并以结果 handshake 记录在投递日志中。已停用的 webhook 不响应任何握手。

• WebhookList — 必填: items
• WebhookPatch — 必填: none
• WebhookVerify — 必填: vendor, secret

  webhook 或触发器的服务商验证，即读取时显示的形式。密钥始终只是一个提示。

• WebhookVerifyVendor — 必填: none
• WebhookVerifyWrite — 必填: vendor

  用服务商自己的签名代替密钥来验证请求的服务商，因为这些服务商无法发送我们的密钥。

  每个服务商的请求头和方案都是其自身的，且固定不变：github 发送 X-Hub-Signature-256、sha256= 和请求体的十六进制 HMAC-SHA256；stripe 发送 Stripe-Signature，t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>">（轮换密钥期间有多个 v1，t 在五分钟内）；shopify 发送 X-Shopify-Hmac-Sha256，即请求体的 base64 HMAC-SHA256；slack 发送 X-Slack-Signature、v0= 和 "v0:<X-Slack-Request-Timestamp>:<body>" 的十六进制 HMAC-SHA256（五分钟内）；linear 发送 Linear-Signature，即请求体的十六进制 HMAC-SHA256，并且请求体的 webhookTimestamp 成员（Unix 毫秒）必须在一分钟内；vercel 发送 x-vercel-signature，即请求体的十六进制 HMAC-SHA1；asana 发送 X-Hook-Signature，即以 Asana 握手的 X-Hook-Secret 为密钥的请求体十六进制 HMAC-SHA256；generic_hmac 是任何在您指定的请求头中用 HMAC-SHA256 签名的发送方。

  带有效签名的请求无需密钥即可被接受，密钥仍可并行使用。verify 不能与 signing 同时使用。请求按其到达时的请求体判定，在消耗任何速率额度之前。Slack 和 Asana 也会响应它们的握手（见 WebhookHandshake）。

• WebhookWithSecret — 必填: id, url, event_types, enabled, revision, status, created_at, updated_at, secret

  Webhook 及其签名密钥。仅由 create 和 rotate-secret 返回。

• WebhookWrite — 必填: url, event_types
• WebsiteSetupCode — 必填: code, expires_at