仪表板 API

检查邀请但不消耗。绝不报告注册或验证状态，但登录重置会报告 replaces_unverified_account。organization_admin 或 organization_member 邀请会报告组织名称，不含项目。

启动一个绑定到邀请摘要和模式的五分钟注册仪式。链接 create_login 需要已验证的 __Host-screenrig-signup cookie 并使用其名称。

邮件 create_login 绑定提供的显示名称；重置绑定目标人员，但对未验证地址的重置例外：它会为其创建的新人员注册通行密钥，名称取自提供的显示名称，缺省时取自该地址。

该重置需要 replace_unverified_account 为 true（检查会报告 replaces_unverified_account），否则返回 409 unverified_account_replacement。

启动浏览器绑定链接注册，并撤销此邀请的早期注册。验证挑战绑定到此注册。开发授权立即验证注册，无需邮件。

返回属于此浏览器的实时注册信息。缺失、撤销、已使用或过期的注册 Cookie 返回 invitation_invalid。

事务性接受邀请并生成新的用户会话，若存在则删除旧会话。

链接 create_login 需要此邀请的已验证 __Host-screenrig-signup cookie。signed_in 需要控制台会话和最近登录或新证明；邮件发送需要匹配的已验证电子邮件，或已登录人员的未验证地址，接受邀请即验证该地址。

现有人员已持有的地址（无论是否已验证），对 create_login 返回 resource_conflict。重置会让持有已验证地址的人员登录。

对未验证地址的重置需要 replace_unverified_account 为 true（检查会报告 replaces_unverified_account），否则返回 409 unverified_account_replacement，且不消耗任何内容；设置后，重置会创建一个新的已验证人员，使用其注册的凭证，名称取自 display_name，缺省时取自该地址，并带有新的组织和项目，同时让该人员登录；未验证的人员被删除（其会话、通行密钥和智能体随之终止），其创建的项目和组织保留，但不再有他们，也不再以该地址作为联系人，因此之后的重置不会再向他们重新发送注册邀请。

响应会指明新项目。需要验证电子邮件的会话（GET /api/session 上的 email_verification_required）只接受指明其自身地址的邮件邀请，对任何其他邀请都收到 403 email_verification_required。

organization_admin 邀请将该人员添加为组织管理员，且不开通任何项目；当组织已有 20 名管理员时返回 organization_admin_limit 并保持待处理，组织已被删除时返回 resource_conflict。

organization_member 邀请将此人的主组织设为发出邀请的组织（无论其之前的主组织是什么），且不授予任何项目成员资格；当另一个组织管理此人时返回 managed_elsewhere（409），当组织已被删除时返回 resource_conflict。

organization_admin 邀请仅在此人没有主组织时设置其主组织。project_member 邀请会重新检查组织的访客策略，当此人将成为策略拒绝的外部访客时，返回 guest_not_allowed（403）；项目邀请绝不会更改任何人的主组织。被拒绝的邀请仍为未处理状态。

为自助注册启动一个五分钟的注册仪式，绑定到规范化的电子邮件地址和显示名称。它不创建任何内容，也不发送邮件。

现有人员持有的地址（无论是否已验证）返回 409 account_exists；其域名所属组织通过身份提供者登录的地址返回 403 sso_required；无效的地址或名称返回 400 invalid_request 并附带字段错误。运行控制台开发认证的服务器返回 passkeys_disabled。

按客户端地址限制。

创建自助账户并让此浏览器登录。

一个事务创建该人员（电子邮件地址未验证，验证截止时间在 72 小时后），注册由 POST /api/signups/passkey-options 启动的仪式中的通行密钥，按智能体注册创建组织和项目的方式创建该人员的组织和项目，将该人员设为项目所有者，存储营销邮件选择，并将验证邮件（purpose account_email）加入发送队列。

打开该页面的网站访客会关联到该账户，注册计为 signed_up。响应会设置控制台会话 cookie。拒绝情形与 POST /api/signups/passkey-options 相同；已使用、已过期或不匹配的仪式返回 400 invalid_request。按客户端地址和电子邮件地址分别限制速率。

切换到用户的某个项目并更新其最后使用时间。工作人员也可切换到其影子项目；该会话报告 shadow 为 true，只读且不更新最后使用时间。其他项目返回 not_found。

列出当前项目的成员，不含其私人电子邮件地址。

除成员管理（移除、审批人、范围、所有权）外，每个成员权限相等；成员管理属于所有者，以及身为成员的项目所属组织管理员。owner 标记项目所有者，external 标记访客（该成员的主组织不是项目所属组织），viewer_user_id 和 viewer_is_owner 描述已登录的人员。

从当前项目中移除成员。项目所有者可移除其他任何成员，身为成员的项目所属组织管理员也可以；任何成员可移除自己以离开。所有者永不被移除且永不离开（owner_cannot_leave；先转移所有权）。成员移除他人将被 owner_required 拒绝。

不是成员的人员（包括已被移除者）返回 not_found。在一次事务中，成员资格结束，此人对该项目的未处理邮件邀请被撤销，并追加项目事件 member.removed（详情含 user_id、removed_by_user_id、left）。

此人的会话在下一次请求时停止解析该项目，行为如同项目被删除后。智能体的成员资格是独立的，予以保留。仅限人员；无持有者路径。

当前项目中一个人的活动，最新优先：登录（及拒绝登录，含地址或通行密钥）、登出、切换项目、凭证更改、重新认证证明及通过仪表盘所做的每次更改，包括拒绝和失败。读取操作从不记录。

Agent 和 CLI 请求在其智能体上（listDashboardAgentEvents）。项目的员工影子不记录任何内容；在批准的员工写入租约下所做的更改为该员工的记录，来源为员工。

该人员本人、项目所有者、项目组织管理员和影子项目的员工可读取。其他任何人返回 not_found，未成员且无此处记录的人员同样如此，因此答案不会透露成员身份；前成员的记录仍可读。

项目属于会话，非请求，且仅返回该项目的行。

每个值均由服务器派生：操作来自服务器匹配的路由（或命名账户操作，如 session.sign_in 或 passkey.add），资源来自路由的第一个路径值（当它是服务器生成的标识符时），状态、problem_code 和错误来自问题注册表，客户端从 User-Agent 和平台提示解析（原始 User-Agent 不保留）。

未存储请求体、密码、令牌或 Cookie。显示记录的 client_ip 和 email。

分页键基于 (at, id) 降序。传递 next_cursor 作为 after 继续；末尾为 null。写入的行只会出现在第一页之前，保留策略删除最旧行，因此游标不会重复或跳过存活行。格式错误的游标或过滤器返回 invalid_request；limit 超出 1-100 范围时使用默认值。

行在项目事件保留窗口到期时过期。recorded_since 是项目最早存活行的时间，或在无行时为服务器开始记录时间；之前的内容不重建。

返回已登录人员的个人资料和凭证计数。

作废已登录人员。受证明保护：正文携带新鲜登录证明，针对绑定此会话且类型为 account_delete、subject_id 等于已登录人员用户 ID 的重新认证进行验证（从 POST /api/me/reauthentications 开始）。无当前重新认证时，返回 reauthentication_required。

成功时响应为 204，控制台会话 cookie 被清除，浏览器对控制台源的 HTTP 缓存也会像登出时一样被清除。

启动绑定到会话、类型和主题的通行密钥升级步骤。没有通行密钥的成员会收到 resource_conflict 并使用密码证明。

在新证明后设置或替换用户密码。首次密码需通行密钥证明；替换接受当前密码或通行密钥。撤销其他会话并排队登录变更通知。

电子邮件地址未验证的人员（例如自助注册后尚未验证的人员）无法设置密码，并收到 403 email_verification_required。

列出该人员的通行密钥，并附上客户端让浏览器的密码管理器与这些通行密钥保持同步所需的信息（WebAuthn Signal API）。列表带有这些通行密钥注册时所用的依赖方 ID 和用户句柄，每个通行密钥带有其凭证 ID 以及其认证器报告的提供者。

验证新鲜证明并启动绑定到会话和人员的注册。开发认证下禁用通行密钥。

存储新通行密钥，撤销该人员的其他会话，并排队发送登录变更通知。发送时未带名称的通行密钥以其提供者命名；若其认证器没有报告列表中已知的提供者，则命名为 Passkey。

重命名已登录用户拥有的通行密钥。

经过新验证后删除通行密钥，并发送登录变更通知。移除最后一个登录方式会返回 last_credential。账户需要通行密钥的人员（每个员工）不能移除其最后一个通行密钥；此操作返回 409 resource_conflict。

返回该人员的已验证和待处理电子邮件状态。自行注册的人员在打开发送到其地址的链接之前，持有未验证的地址；此时 email_verified 为 false，verify_by 为截止时间，过期后会话只能使用验证或更改该地址的路由（GET /api/session 上的 email_verification_required）。

在提供新的证明后请求更改电子邮件。验证待处理期间，已验证的地址继续有效。其他任何现有人员持有的地址（无论是否已验证）返回 user_email_conflict。旧地址会收到警告，而不是撤销链接。

地址未验证的人员以同样的方式更改地址；验证新地址后，它成为该人员的已验证地址，并清除 verify_by。

将一个新的验证链接加入发送队列。当电子邮件更改正在等待验证时（GET /api/me/email 上的 pending_email），它是该更改的链接，发送到待验证地址；否则它是该人员当前未验证地址的 account_email 链接。距同类最近一个链接不到十分钟时，不会加入任何队列，仍返回 202。

地址已验证且没有待处理更改的人员，其请求返回 409 resource_conflict。

用请求体替换该人员注册后给出的回答，请求体包含迄今为止的所有回答；省略或为 null 的成员视为未回答。每个成员都有封闭的取值集合，超出该集合的值返回 400 invalid_request 并附带字段错误。

该资料保存在该人员名下，并与其注册所属的组织一起显示给 screenRIG 员工。

会话所属项目中某个应用（Web 应用）被放置在何处，通过对项目播放列表的一次遍历和对持有这些播放列表的屏幕的一次读取计算得出。placements 是其存储的所属应用为此应用的应用原语，按播放列表（沿用播放列表的列表顺序）、页面和原语的顺序排列；一个播放列表放置它两次就有两条。release 说明每个固定的发布与该应用的 latest_ready_release 相比处于何种状态：latest、older，或在该应用尚无就绪发布时为 unknown。screens 是默认播放、排程播放、接管播放或当前正在显示某个放置所在播放列表的 pairing_pending 和 active 屏幕，最新的在前；已归档的屏幕不计入，而其播放器无法显示 Web 应用的屏幕会带有 applications_unsupported。

限定屏幕范围的成员或智能体（screen_scope）只能看到其范围内的屏幕，screen_count 也只统计这些屏幕。这并非删除的阻碍条件，真正的阻碍条件是运行时授权（屏幕的清单持有某个发布）。项目不持有的 id 与 getApplication 一样返回 not_found。响应为 private 且 no-store。

会话所属项目中某个就绪媒体项在何处被使用，通过对项目播放列表的一次遍历和对持有这些播放列表的屏幕的一次读取计算得出。playlists 先列出引用该文件的播放列表（图片或视频原语的静态 id 以及按 id 或 ids 指定的选择器、流的回退、卡片 params 中的 media:<id> 字符串、stinger 的标志、配乐音轨），再列出其标签、文件夹或 all 选择器触及该文件的播放列表，每组均沿用播放列表的列表顺序；每个播放列表是一个条目，其 uses 列出每一种方式，精确类型排在前面。

选择器按运行时解析它们的方式判断：标签筛选条件匹配文件的 tag 和 tags，文件夹选择器匹配直接位于该文件夹内的文件，all 选择器匹配该类型的每个文件，待审核的文件则按其上次批准时的标签和文件夹匹配（从未获批准的文件不会被任何选择器触及）。

轮换（batch_size、one_at_a_time）、可用时间窗口、宽高比适配和页面的可见性均不参与判断。screens 是默认播放、排程播放、接管播放或当前正在显示其中某个播放列表的 pairing_pending 和 active 屏幕，最新的在前；已归档的屏幕不计入。

限定屏幕范围的成员或智能体（screen_scope）只能看到其范围内的屏幕，screen_count 也只统计这些屏幕。项目不持有的 id 或未就绪的媒体项，与 getMedia 一样返回 not_found。响应为 private 且 no-store。

返回项目拥有的已准备好图像的小型有损 WebP，仪表板网格永远不解码原图。尺寸固定：保持比例，最大 512 x 512，且不放大，动画图像显示第一帧。

首次请求生成并存储副本于原件旁；后续请求流式传输存储副本，删除媒体时同时删除副本。其他项目标识符、视频、音频及未准备好的媒体返回 not_found。不接受范围请求。

ETag 是强标记，标明原始文件和缩略图生成器，因此每次请求和主机都相同。响应为私有、无缓存，且 If-None-Match 匹配时，在会话项目中媒体解析后返回 304，不读取缩略图。完成的字节计为 dashboard_media 出站。

应用与 getDashboardMediaThumbnail 相同的所有权、条件和生成规则，返回其头部但无正文。不记录外发。

扫描器安全验证窥视。它从不验证地址、不更改用户或登录访客。它报告链接的用途和状态；待处理的 account_email 链接只有携带该人员控制台会话的请求才能验证，因此页面会先要求登录，再要求确认。

明确的人工确认会消耗一个绑定用途的验证挑战。链接注册挑战需要匹配的 __Host-screenrig-signup cookie；电子邮件更改挑战绑定令牌，因此该链接在任何浏览器中都有效。

account_email 挑战（在自助注册时以及通过 POST /api/me/email/verification 发送，有效期 30 天）可在任何浏览器中打开，但只有携带该链接所属人员有效控制台会话的请求才能完成验证，包括被 email_verification_required 限制只能使用此路由的会话。

没有会话或会话属于其他人员时，它返回 200 sign_in_required，不验证任何内容，并保持链接可用。验证通过的 account_email 链接将该人员的地址标记为已验证并结束验证截止期限；如果另一人员先验证了同一地址，则返回 superseded。验证绝不会让访客登录。

启动一个无用户名的 WebAuthn 断言仪式，并逐字返回 navigator.credentials.get 的请求选项。不需要 cookie，也不发布 allowCredentials 列表，因此该路由不会泄露任何用户或凭证信息。仪式在五分钟的 DashboardCeremonyTTL 后过期。

当服务器运行仪表板开发身份验证时，此路由返回 passkeys_disabled。

验证一个无用户名断言并为发现的凭证标识的用户铸造仪表盘会话 cookie。无 cookie 验证请求。未知、过期或已使用的仪式返回 passkey_invalid，依赖方无法验证的断言或签名计数器倒退也返回此错误。

仪式有效但其凭证标识符未注册给任何人（没有任何人员的已存储凭证带有该标识符）时，改为返回 401 passkey_unknown；该响应仅用于这一种情况，因此客户端仅可在收到它时通知浏览器忘记该凭证（PublicKeyCredential.signalUnknownCredential），其他任何响应都不可以。

凭证标识符本身不是授权，签名的断言才是。已验证地址所在域名的组织要求单点登录的人员会被拒绝并返回 403 sso_required，除非其是该组织的应急管理员；此类登录会被审计。

当服务器运行仪表板开发身份验证时，此路由返回 passkeys_disabled。

让通过已验证电子邮件和密码识别的人员登录。未知电子邮件、没有密码和密码错误返回相同的 unauthorized 响应。若仍是成员则打开上次使用的项目，否则打开最近一次成员资格对应的项目，或不打开任何项目。

其域名所属组织要求单点登录的地址，在查找任何账户之前就会被拒绝并返回 403 sso_required，因此该响应不取决于是否有人持有该地址；POST /api/sso/starts 通过其身份提供者让该人员登录。

密码登录需要已验证的电子邮件，因此自行注册（POST /api/signups）的人员使用其通行密钥登录；在未验证地址上设置了密码的人员仍会收到 unauthorized 响应。开发认证使用同样的密码流程。

返回当前控制台会话。会话 Cookie 和服务器端会话建立权限；user_id 仅作描述。401 响应表示需要登录。

dev_auth 字段保留用于本地开发，托管服务上为 false。organization 是此人的主组织，没有主组织时不出现；project.organization_admin 表明此人管理当前项目所属的组织。

删除服务器端会话行并使会话 cookie 过期。它不会删除用户，也不会移除任何凭证。此操作本质上是幂等的，不接受 Idempotency-Key。

成功登出还清除仪表盘源的浏览器 HTTP 缓存，丢弃会话查看的私有无缓存媒体、截图和广告审查字节；仅过期的会话保留它们，直到浏览器驱逐。

上报一个浏览器在控制台入口流程（注册、登录、重置、邀请和添加通行密钥）中走过的某一步，用于员工查看入门数据。公开接口：有无控制台会话均可调用。

旅程是浏览器自己的随机 id；服务器还会保留请求携带的边缘访客 Cookie，以及会话携带的人员和组织。旅程仅限员工查看，并保留人们输入的真实值（地址、姓名、答案）；它绝不会接收密码、验证码或令牌。

mode、source、utm_source、utm_medium、utm_campaign、click_kind、site_trail 和 site_cta 保留第一个值；每个步骤保留其首次发生的时间，而步骤的 value、detail 和旅程的 email（来自 email_submitted）取最新值。source 仅在 entry_viewed 时被接受。question 在 question_* 步骤中必填，在其他所有步骤中被拒绝。detail 对 *_failed 步骤是问题代码，对 signed_in 是登录方式，对 signup_finished 是 connected 或 skipped。email_verified、email_gate_reached、site_visited、site_cta_clicked 以及账户里程碑由服务器写入或推导得出，在此处会被拒绝。

仅限制长度。按客户端地址限流。

列出会话项目的所有待处理、活动、已撤销、已取消和已过期代理，含安全安装元数据、最后使用时间、认证请求计数及直接归属的计量额度。不返回持有者、接收者密钥字节、信封或项目标识符。

此智能体的历史记录，最新的排在前面，每个触发器作为一条记录。它包含智能体请求的内容及其结果所产生的更改。更改了某项内容的请求即为其领域事件，并带有导致该事件的命令戳记。未更改任何内容的请求——被拒绝、失败或无事件的成功——为一个agent.command事件。

无单独命令端点；在两个面板上显示相同触发器是此替代方案修复的缺陷。包含该代理的生命周期事件。工作者、播放器和仅仪表板活动从不被推断为代理活动。两个请求即两个触发器。拒绝后的重试为第二条记录，绝不重写第一条。

读取不被记录，因为它不改变任何内容，轮询智能体会掩盖所有真实操作。匿名注册除外。命令戳的每部分均源自服务器匹配的路由或问题注册表。

记录中无参数向量、请求正文、头部或自由文本，因此无需编辑，且调用者无法将选定文本写入操作员可见界面。资源标识符出现是因为标识符从不作为授权且已在事件中公开。分页键按序列，降序。

将返回的 next_cursor 作为 after 传递以继续。当页面较短时 next_cursor 为空，表示历史结束：并发追加只采用更高序列，保留策略先移除最低序列，因此游标不会重复或跳过存活记录。不支持偏移分页。

每个搜索参数都是服务器生成令牌的精确匹配或范围谓词。格式错误的游标或过滤值返回 invalid_request。限制超出 1-200 范围时会被限制为默认值而非拒绝。记录在项目自己的事件保留窗口内过期。

在新的证明后断开智能体与所选项目的连接。该项目必须是此人所属的项目之一。待处理的连接和凭据签发会被取消；不会签发替代令牌。限定屏幕范围的成员不能连接智能体、签发凭据或管理项目的人员：outside_screen_scope（请询问项目所有者）。

该智能体在会话项目中写的备注，最新优先，包含未解决和已解决。状态为全部（默认）、未解决或已解决。传回 next_cursor 作为 after；最后一页为空。备注正文为智能体书写的纯文本；渲染为文本，绝不作为HTML或Markdown。

以登录用户身份解决智能体的一个未处理备注，需提供原因；resolution.by 标明该用户。附加 note.resolved，演员为该用户。已解决的备注为 note_not_open。

删除作为已登录人员的智能体备注，无论是打开还是已解决。附加 note.deleted，演员为该人员。

针对会话项目的待处理连接请求，成员可审核并批准：请求指定项目，以及由已是该项目成员的智能体身份进行的设备登录或连接。

新安装的登录未列出（其项目提示由客户端提供）；人员通过其用户代码访问（POST /api/agent-connections/lookup）。

解析待处理设备登录的用户代码（`screenrig login`），该代码在连接页面输入或预填，解析后显示其连接的审批视图。此操作不批准任何内容。分隔符、空格和大小写均被忽略。未知、已使用或无效代码为 agent_connection_invalid；过期代码为 agent_connection_expired。

每个控制台会话每 10 分钟限 5 次查询，每个客户端地址每小时 20 次，整个设备组每小时 1200 次（rate_limited）。限定屏幕范围的成员不能连接智能体、签发凭据或管理项目的人员：outside_screen_scope（请询问项目所有者）。

返回安全连接审核元数据。审核不选择项目；批准选择该人员的某个成员身份。

在新的证明后批准所选项目的连接，并创建一个待处理的智能体。该项目必须是此人所属的项目之一。返回安全的元数据，绝不返回持有者令牌。限定屏幕范围的成员不能连接智能体、签发凭据或管理项目的人员：outside_screen_scope（请询问项目所有者）。

在新的证明后拒绝所选项目的连接，不创建智能体。该项目必须是此人所属的项目之一。限定屏幕范围的成员不能连接智能体、签发凭据或管理项目的人员：outside_screen_scope（请询问项目所有者）。

用于控制台外壳的一次请求。

每个成员都是所指路由为这同一个会话返回的响应体（GET /api/me/email、/api/support/status、/api/projects、/api/organizations、/api/project、/api/project/capabilities、/api/advertising/network、/api/alerts?state=open&limit=1 和 /api/reviews?state=all&limit=1），由该路由自己的处理程序在其自身的授权、计划和范围检查下生成。

当其路由不会对此会话返回 2xx 时（被拒绝、角色或计划无权读取、没有当前项目、出现故障），该成员缺失，控制台随后会自行读取该路由。当项目没有网络、其路由会返回 404 not_found 时，advertising_network 为 null。

没有当前项目的会话只会得到不需要项目的成员。

会话项目的项目网络状态计数。屏幕在线计数来自实时配对运行时事件流，与 Screen.online 发布的推导相同；它们不是存储的布尔值，也不是播放器心跳。媒体字节数仅为已准备好媒体的持久字节数。

真实的支付能力状态。当rails_available为false且unavailable_reason为financial_rails_unavailable时，卡、税务和提现渠道不可用。不返回原始银行凭证。

一个由调用者拥有的最终收据/税务文件。在资金未发货时无收据存在，因此这是 not_found 而非伪造文档。

返回会话项目的公共整数额度余额。此 Cookie 认证读取永不扣款，因此在零余额时仍可用。仅 Cookie 的控制台从不向 GET /api/project 出示项目持有者。

铸造一个单次使用的三十秒启动票据，用于会话项目拥有的应用程序的最新准备发布版本，在该发布版本的精确预览主机上，绝不使用发布主机播放器框架，因此播放器和控制台在同一浏览器中永远不会共享该主机的缓存文档或授予 Cookie。

票据仅在该主机上转换为 release-grant cookie，因此预览本质上是跨域的，网页应用代码永远无法读取仪表板 cookie。响应中的 release_id 标识本次启动所选的确切版本，即使之后另一次发布完成也是如此。将 launch_url 赋值给 iframe.src，且仅此。

此处权限为所有者权限：会话的项目拥有该应用。这是 screenrig.webapp-package/v1 的精确当前清单权限之外的第二权威来源，且仅限于此操作。不要将其泛化为媒体或受保护的运行时内容。

无父播放器，因此浏览器 SDK 和键值桥失败关闭，预览仅限演示。没有就绪版本的应用返回 resource_conflict。

按 GET /api/organizations 的列表项形式呈现给调用者的一个组织，含 admin、home 和 reseller。已登录的人员在以下情况下可以读取：管理该组织、管理其所委托的经销商、是员工，或会在该列表中看到它（是其某个活跃项目的成员，或它是其主组织）。

其他任何人，以及不存在的组织，都会收到 404 not_found。不授予项目成员资格。仅限 Cookie 会话；智能体凭证会被拒绝。

组织管理员仅读取项目名称、所有者、状态和屏幕数量；这不授予项目访问权限。管理员只有在加入项目（POST .../projects/{project_id}/access）后才能读取其内容，并通过下方的所有者和成员路由管理其人员。

已登录人员管理其组织的有效经销商（admin_user_ids），按名称排序；其他人为空。仅限 Cookie 会话。经销商是被员工设为经销商或由其管理员注册的组织（POST /api/resellers）；其管理员运营其客户的组织（docs/resellers.md）。

组织管理员可立即将该组织设为经销商。调用者必须是邮箱地址已验证的已登录人员（仅限 Cookie 会话；智能体和服务客户端永远不具备经销商权限），并且是 organization_id 所指组织的管理员；其他任何人都会收到 404 not_found。

经销商起始为标价的 2000 基点（20%），即刻生效，处于待审核状态；在 screenRIG 审核之前，最多可接入 10 个当前客户（customer_limit）。该组织必须处于有效状态，尚不是经销商，不是经销商的客户，也不在 staff 或 promo 套餐上（409 reseller_conflict，详情说明具体原因）。

向组织审计追加 reseller.enrolled。

调用者管理的一个经销商，含其差价。其他任何人都会收到 404 not_found。

经销商的当前客户（委托给它的组织），按名称排序，含套餐、数量和存储字节数。仅限经销商管理员；其他任何人都会收到 404 not_found。

创建一个从创建起就委托给该经销商的客户组织，使用 Standard 套餐，由调用的经销商管理员担任其唯一管理员。调用者的主组织不变。该组织自己的管理员之后可以结束委托（DELETE /api/organizations/{org_id}/reseller）。

向组织审计追加 organization.created 和 reseller.customer_started。等待审核（review_state pending）的经销商最多可接入 customer_limit 个当前客户；超出后返回 409 reseller_conflict。

经销商的某一个当前客户。仅限经销商管理员；不是当前客户的组织返回 404 not_found。

设置当前客户的套餐，由经销商支付。standard 表示移除套餐；plus 和 premium 始终允许，education 仅限符合教育资格的组织。Enterprise、staff 和 promo 由员工分配。

升级立即生效，降级或移除在下一个 UTC 月边界生效，与组织套餐更改相同（docs/billing-rollup.md）。向组织审计追加 reseller.customer_plan。

当前客户的活跃项目，含名称、状态、屏幕数量，以及调用者是否已是成员。列出项目不授予项目访问权限；POST .../access 可加入其中一个。

让调用的经销商管理员成为某个当前客户项目的完整成员（can_approve，无范围，来源 reseller_admin），效果与组织管理员加入相同，这样他们就能用 PUT /api/session/project 打开该项目。已是成员时原样返回该项目。

向项目追加 member.added_by_reseller，向组织审计追加 reseller.project_joined，并向项目所有者发送电子邮件。该成员资格会保留到被移除；结束委托不会移除它。

经销商某个 UTC 月份应付的金额。该月内任何时间被委托的每位客户占一行，列出其在该月委托期间产生、且其自身额度未覆盖的用量费用部分（按标价和按经销商价格），以及其套餐的年价格。

经销商价格为标价减去月初与经销商（重新）创建时间中较晚者所适用的差价。仅限经销商管理员。

组织的管理员可以立即结束该组织对其经销商的委托。此后该组织自行付费；其套餐、项目和成员保持不变，包括经销商管理员持有的成员资格。其钱包在委托期间产生、由经销商承担账单的超额费用，会在同一次变更中冲销。

向组织审计追加 reseller.customer_ended。没有经销商的组织返回 404 not_found。

其他地方的项目，其所有者在完全验证的域上有验证过的电子邮件。联系地址和子域不匹配，管理员无法拉取这些项目。

为一个域开启 7 天 DNS TXT 挑战，替换该域的待处理挑战；组织的其他域保持不变。将其精确值放在返回的 DNS 名称处并保持。一个组织最多持有 20 个域，已验证和待验证合计（resource_conflict）。另一个组织持有的域为 resource_conflict。

组织已持有的域名可再次验证，记录新的每日 DNS 检查值。

验证一个未过期的挑战对 DNS 并将其域添加到组织，附加到已有域旁。每个精确域属于一个组织。查找期间旋转的证明被拒绝。保持 TXT 记录；每日检查删除连续七天缺失记录的域。

认领提交后，以及此响应后台，每个所有者为该域的已验证用户且独自处于该用户个人组织的项目将移入此组织（若名称冲突，重命名为“<name> (<owner>)”）。

任何其他组织中的项目、自付费计划项目，以及其所有者或员工从域组织迁出的项目均保持原位；组织限制拒绝的项目将在一天后重试。放置不授予访问权限。

指定管理员读取组织管理员、可能成为管理员的候选人（已验证、活跃的项目所有者且尚非管理员）及组织修订版本。其他人员拒绝访问其他组织管理员路由。仅限人员；智能体和持有者凭证无管理员路由。

指定的管理员替换组织管理员。If-Match 包含组织修订版；过期版本为 revision_conflict，带 current_revision。该集合最多可指定 1 到 20 位成员，每位均为现任管理员或候选人，否则为 invalid_request；仅当还有其他管理员时，管理员才能移除自己。

该更改会增加修订版本，记录在组织审计中，不授予项目成员资格，并返回与 GET 相同的结构。仅限人员；智能体和持有者凭证无管理员路径。

指定管理员读取组织的人员。只读。projects 列出组织的活跃项目，按名称排序，最多 500 个。people 是组织的主组织成员（member 为 true）、这些项目的活跃成员（不含已暂停的成员）和指定管理员的并集。

排序为管理员在前，其次是主组织成员，最后是外部人员（非主组织成员），每组按显示名再按邮箱排序。

每个人都带有其在各项目中的角色（owner 或 member）、是否可在该项目中批准审核（can_approve）、是否仅限于屏幕或上传（limited）、是否为管理员、是否为主组织成员（member）、是否由组织管理（managed），对于外部人员，还带有当前访客策略是否不会准许他们（outside_guest_policy）。

不在任何项目中的管理员或主组织成员会显示为空的 projects 列表。地址未验证的人员，其 email 为空。已停用的人员和智能体永远不会出现。最多返回 500 人，管理员始终包含其中；当人员、项目或成员资格被省略时，truncated 为 true。

其他人会像在其他组织管理员路由上一样被拒绝。仅限人员；智能体和持有者凭证无路由。

指定管理员按 ID 列出组织的管理员邀请，每次 50 条，过期邀请自动失效。收件人地址对组织管理员可见，管理员提供。令牌和凭证 URL 不列出。仅限人员；智能体和持有者凭证无管理员路由。

指定的管理员通过电子邮件邀请成员成为管理员。接受后，该成员将加入组织管理员，并在无登录账号时创建其登录；不会获得任何项目成员资格。管理员总数（含待处理邀请）最多 20 个（organization_admin_limit）；若该成员已是组织管理员，则该地址为 invalid_request。

电子邮件邀请在 7 天后过期；对同一地址的未完成邀请会被重复使用。组织名称和邀请人名称需适合用于邮件。仅限成员；智能体和持有者凭证无管理员通道。

指定管理员撤销未处理的管理员邀请并释放管理员名额。已撤销邀请返回 204；已接受邀请返回 invitation_consumed；组织不持有的 ID 返回 not_found。仅限人员；智能体和持有者凭证无管理员路由。

指定管理员按 ID 列出组织的成员邀请，每次 50 条，过期邀请自动失效。收件人地址对组织管理员可见，管理员提供。令牌和凭证 URL 不列出。仅限人员；智能体和持有者凭证无管理员路由。

指定管理员通过电子邮件邀请人员作为成员加入组织。接受邀请会把此人的主组织设为本组织（无论其之前的主组织是什么），并在其没有登录账号时创建登录；不会授予任何项目成员资格。

地址对应的人员已是该组织主组织成员的，返回 invalid_request；对应人员由其他组织管理的，返回 managed_elsewhere。电子邮件邀请在 7 天后过期；对同一地址的未完成邀请会被重复使用。组织名称和邀请人名称需适合用于邮件。

接受员工组织（plan_id staff）的邀请也会使该用户成为员工，因此只有员工能发送此类邀请。每次请求只能指定一个地址，并须提供与该地址绑定的 staff_grant 证明（缺少证明时返回 reauthentication_required）。仅限人员；代理和 bearer 凭据没有管理路由。

指定管理员撤销一个未处理的成员邀请。已撤销的邀请返回 204；已接受的邀请返回 invitation_consumed；组织不持有的 id 返回 not_found。仅限人员；智能体和持有者凭证无管理员路由。

指定管理员将一名主组织成员从组织中移除。

在一次事务中，此人的主组织被清除，其在组织所有活跃项目中的成员资格全部结束，每一项都与将其从该项目移除的效果相同（对该项目的未处理邮件邀请被撤销，其会话不再解析该项目）；其在其他组织项目中的成员资格不受影响，也不会更改任何其他组织。

该更改记录在组织审计中。

由身份提供者管理（单点登录或 SCIM）的人员返回 managed_member；指定管理员返回 organization_admin_member（先用 PUT /api/organizations/{org_id}/admins 移除其管理员席位）；拥有组织任一活跃项目的人员返回 member_owns_projects，详情列出项目名称（先转让这些项目，不会移除任何内容）；不是组织主组织成员的人员（包括已被移除者）返回 not_found。

仅限人员；智能体和持有者凭证无管理员路由。

指定管理员设置组织准许哪些人作为访客进入其项目，访客指主组织是其他组织或没有主组织的人。mode 为 allow（默认值）时准许所有访客，为 domains 时准许已验证电子邮件地址属于 domains 中某个域名的访客，为 none 时不准许任何访客。domains 列出 1 到 20 个互不相同的小写 DNS 名称，mode 为 domains 时必填，其他情况下省略；否则返回 invalid_request。

该策略会替换之前的策略，增加组织修订版本，记录在组织审计中，并返回当前生效的策略。组织向访客授予项目成员资格时会检查该策略，途径为项目成员邀请（创建和接受）以及 SCIM 群组绑定，不符合时以 guest_not_allowed 拒绝。

员工和组织自己的管理员不受此策略约束，智能体不检查，主组织成员绝不是访客。收紧策略不会移除任何人；outside_policy 统计已在组织活跃项目中、但新策略不会准许的外部人员数量，GET /api/organizations/{org_id}/people 会逐一标记他们（outside_guest_policy）。

仅限人员；智能体和持有者凭证无管理员路由。

指定管理员设置或清除组织的媒体库项目。project_id 指明组织的一个有效项目，null 表示清除。

组织的其他所有项目随后可读取媒体库的媒体、媒体文件夹和播放列表（在 GET /api/media、/api/media-folders 和 /api/playlists 上使用 library=true，或按 id 读取），并以只读方式使用它们：页面的媒体引用、指向媒体库文件夹的 by:folder 选择器（标签选择器和 all 选择器绝不会涉及媒体库）、屏幕的排程和层级栈，以及 from_template。只有媒体库自己的成员才能修改它们。

媒体库项目不含屏幕：有屏幕的项目会得到 library_no_screens，此后媒体库也不接纳任何屏幕。设置媒体库需要套餐功能 library（Premium、Education、Enterprise；否则返回 feature_not_in_plan）；清除则无此要求，降级后保留的媒体库会继续提供服务。

清除或替换媒体库后，引用其内容的成员项目播放列表会在下次写入时无法解析，屏幕也不再接收其媒体。作为媒体库的项目被删除或移出组织时，媒体库会被清除。

返回组织视图，记录在组织审计中（organization.library_changed），并使修订号加一。仅限人员。

指定管理员可在一次请求中设置多人对组织多个活跃项目的访问权限，无需加入其中任何一个项目。

1 到 500 项变更中的每一项指定一个项目、一个人员和一种访问权限，且同一个 (project_id, user_id) 组合不会出现两次。member 使该人员成为不能批准审核的项目成员（若不是成员则添加；审批人会失去审批权），approver 为可以批准的成员（若不是成员则添加），none 表示不是成员（若是成员则移除）。

所有变更在一个事务中按顺序应用，任何一次拒绝都会撤销整个批次；每次拒绝都会在 errors[].field 中指向 changes[i]（项目或人员）或 changes[i].access。

不是本组织活跃项目的项目返回 not_found；不是现有人员的对象（智能体、已停用人员、未知 id）或属于员工的人员、已暂停的成员资格，以及被添加但不属于组织人员的人员（其管理员、主组织成员和其他活跃项目的活跃成员；其他人须通过邀请加入），均返回 invalid_request；所有者永远不会被设为 member 或 none（owner_cannot_leave）；上传者永远不能审批（resource_conflict，与 PUT /api/members/{user_id}/approver 的响应一致）；不允许移除管理员本人（管理员通过 DELETE /api/members/{user_id} 离开）；被添加的人员按邀请的准入规则获得准入，因此主组织成员和组织管理员始终可以，外部人员仅在当前访客策略准许时才可以（guest_not_allowed）。

项目的 200 名成员上限及其计划的成员数上限适用于新添加的人员（member_limit_reached）。响应按请求顺序重复每项变更；对于访问权限已经生效的变更，changed 为 false，不会写入也不会记录任何内容。

每项变更都会记录在组织审计中（organization.project_member_added、organization.project_member_approver_changed 或 organization.project_member_removed）和项目事件中（member.added_by_organization_admin、project.member_approver_changed 或 member.removed，标记为组织管理员所为），并且每个项目的所有者会就该批次收到一封电子邮件，除非变更由其本人所做。

仅限人员；智能体和持有者凭证无管理员路由。

指定管理员以不带屏幕或上传范围、可批准审核的成员身份加入组织的一个活跃项目。加入后，管理员才能获得该项目的内容，组织路由从不显示这些内容。

已是不带范围且可批准的成员的管理员会收到 200，joined 为 false，不发生任何变化；带屏幕或上传范围的成员，或不能批准的成员，会成为不带范围且可批准的成员，并记录为一次加入。

项目的 200 名成员上限适用（member_limit_reached）；组织的访客策略绝不适用于其自己的管理员。加入会在组织审计中记录为 organization.project_joined，在项目事件中记录为 member.added_by_organization_admin，并向项目所有者发送电子邮件。

组织不持有或已被删除的项目返回 not_found。仅限人员；智能体和持有者凭证无管理员路由。

指定管理员无需加入项目，即可将某人设为组织某个活跃项目的所有者，无论项目现由谁拥有，包括账号已停用的所有者。

新所有者须是已验证的活跃人员，且是项目成员或组织的主组织成员（不是项目成员的主组织成员会先作为不带屏幕或上传范围、可批准审核的成员被加入；访客策略不适用于主组织成员）；其他任何人在 user_id 处返回 invalid_request。

管理员只有加入项目后才能让自己成为所有者（POST /api/organizations/{org_id}/projects/{project_id}/access）；若不是不带屏幕或上传范围、可批准的成员，则在 user_id 处返回 invalid_request。

其效果与所有者自己的转让相同，因此新所有者的屏幕范围和上传范围会被清除，项目的旧版职责绑定到新所有者。指定现任所有者不会产生任何变化。该更改会在组织审计中记录为 organization.project_owner_changed，并向原所有者和新所有者发送电子邮件。

项目的 200 名成员上限适用于新加入的主组织成员（member_limit_reached）。组织不持有或已被删除的项目返回 not_found。仅限人员；智能体和持有者凭证无管理员路由。

指定管理员无需加入项目，即可将成员从组织的某个活跃项目中移除。其效果与所有者执行移除相同（DELETE /api/members/{user_id}）。成员资格结束，此人对该项目的未处理邮件邀请被撤销，其会话不再解析该项目，智能体的成员资格保留。

所有者永不被移除（owner_cannot_leave；先用 PUT /api/organizations/{org_id}/projects/{project_id}/owner 转让所有权）。不是项目成员的人员（包括已被移除者），以及组织不持有或已被删除的项目，均为 not_found。

移除会在组织审计中记录为 organization.project_member_removed，在项目事件中记录为 member.removed，其中 removed_by_organization_admin 为 true。仅限人员；智能体和持有者凭证无管理员路由。

移除一个域名（已验证或待验证），保留组织的其他域名。该域名的未来放置和发现停止，其他组织可能验证它。项目仍留在组织内。组织既不拥有也未验证的域名返回 not_found。

组织要求单点登录期间，已验证域名返回 resource_conflict；关闭“要求单点登录”会在 72 小时后生效，此后即可移除该域名。

设置成员是否可以批准：决定审核，并授予智能体管理访问权限。不可批准的成员，其智能体限于 Propose。仅限项目所有者，或管理项目所属组织的成员（否则返回 forbidden）；所有者自身的行固定（resource_conflict）；非成员返回 not_found。

追加 project.member_approver_changed（详情含 user_id、can_approve）。

将成员限定在屏幕文件夹（每个文件夹包含其内部的所有文件夹）和屏幕，或替换其范围（docs/screen-scope.md）。

在同一事务中，它还会结束此人带到项目中的智能体（agent.disconnected，如同移除它们一样），并追加 project.member_screen_scope_changed（details 为 user_id、screen_scope、previous、changed_by_user_id）。范围在成员的下一次请求时读取：更改会在其下一次 GET /api/session 中显示，无需重新登录。

仅限项目所有者，或管理项目所属组织的成员（否则为 forbidden）；所有者自己的行、上传者（带范围的成员限定于屏幕，上传者限定于内容）以及范围内带单个屏幕的审批审核成员为 resource_conflict；非成员为 not_found；不是项目现存屏幕文件夹或屏幕的 ID，在 screen_scope.folder_ids[i] 或 screen_scope.screen_ids[i] 处为 invalid_request。

审批审核的带范围成员只能在范围内审批；不能审批的成员可以读取并运行命令，但只能通过审批人更改播放内容（approver_required）。

当此人或其带来的智能体持有项目的有效服务客户端时，范围也会被拒绝并返回 resource_conflict：详情最多列出五个客户端，格式为 ID（名称），并统计其余数量，不写入任何内容。

将人员限定到屏幕属于屏幕范围，Enterprise 计划包含该功能；计划不含该功能的项目会被拒绝并返回 feature_not_in_plan（402）。已设置的范围会持续限制该人员，直到将其清除（DELETE），每个计划都可以这样做。

让带范围的成员重新拥有整个项目的屏幕。仅限项目所有者，或管理项目所属组织的成员；未设范围的成员保持不变。追加 project.member_screen_scope_changed，其中 screen_scope 为 null。

将智能体在会话项目中的成员身份限定在屏幕文件夹和屏幕，或替换其范围（docs/screen-scope.md）。智能体的触达范围是此范围经其负责人范围收窄后的结果，因此带范围的人员不会通过比自己更宽的智能体行事。

仅限项目所有者，或管理项目所属组织的成员（否则为 forbidden）；不是项目成员的智能体为 not_found。追加 agent.screen_scope_changed（details 为 agent_id、screen_scope、previous、changed_by_user_id）。

智能体的范围在写入它的实例上于其下一次请求时生效，在其他实例上于两秒内生效。当智能体持有项目的有效服务客户端时，范围会被拒绝并返回 resource_conflict：详情最多列出五个客户端，格式为 ID（名称），并统计其余数量，不写入任何内容。

将智能体限定到屏幕属于屏幕范围，Enterprise 计划包含该功能；计划不含该功能的项目会被拒绝并返回 feature_not_in_plan（402）。已设置的范围会持续限制该智能体，直到将其清除（DELETE），每个计划都可以这样做。

移除智能体在会话项目中的成员身份的范围。仅限项目所有者，或管理项目所属组织的成员。追加 agent.screen_scope_changed，其中 screen_scope 为 null。

将成员设为上传者，或替换某位上传者的范围（docs/uploaders.md）：其可更改页面的播放列表，以及可上传到的媒体文件夹。

在同一事务中，它还会禁止其批准审核，终止其带入项目的智能体（agent.disconnected，与移除他们时相同），并追加 project.member_upload_scope_changed（详情为 user_id、upload_scope、changed_by_user_id）。

范围在该成员的下一次请求时读取：更改会在其下一次 GET /api/session 时显示，无需重新登录。

仅限项目所有者，或管理项目所属组织的成员（否则为 forbidden）；所有者自己的行返回 resource_conflict；非成员返回 not_found；不是项目有效播放列表或媒体文件夹的 id 会在 upload_scope.playlist_ids[i] 或 upload_scope.folder_ids[i] 处返回 invalid_request。access 为 propose（默认）时，上传者的更改会送去审核；manage 则直接发布。

限定屏幕范围的成员属于 resource_conflict：请先清除该范围（DELETE /api/members/{user_id}/screen-scope）。

将上传者恢复为完整成员，该成员不批准审核（如需开启，请使用 setDashboardMemberApprover）。仅限项目所有者，或管理项目所属组织的成员；非上传者的成员保持原样。会追加 project.member_upload_scope_changed，其中 upload_scope 为 null。