OpenAPI 与集成

正确使用控制平面 OpenAPI，并避免把它与本地工作区 Server 混为一谈。

控制平面 API 由仓库中的 packages/docs/openapi.json 描述。它是组织和 Cloud 能力的版本化契约，覆盖身份、配置资源、插件、Skills、连接器与托管 Worker。

OpenAPI 文档是每个路由 Schema 的事实来源。本篇说明如何选择 API 平面、完成认证、构建安全客户端，以及处理多个资源族共享的生命周期语义。

集成边界按状态归属选择 API

控制平面请求不应用作间接修改本地工作区文件的方式。本地 Server 请求也不应用作组织管理。

客户端

桌面、Web、CLI 或服务端客户端

用户动作

由明确的人或服务意图发起请求。

受限凭据

只发送当前 API 调用所需的授权材料。

控制平面

Den OpenAPI 契约

身份与组织

解析当前用户、组织、成员、角色或邀请。

能力资源

对配置对象、插件、Skills、Provider 与连接器进行版本与授权管理。

托管运行时

仅在确实需要远程运行时，才创建和检查托管 Worker。

本地工作

另一条运行时边界

本地 Server API

处理工作区、审批、产物、状态和受支持的 OpenCode 代理。

基地址与路径

OpenAPI 当前声明的服务地址是 https://api.ipolloworklabs.com。Cloud 桌面文档也使用配置的 Web 基地址推导如下路径：

https://app.ipolloworklabs.com/api/den/v1/...
https://app.ipolloworklabs.com/api/den/mcp/...

始终使用目标部署实际配置的 Base URL。需要连接私有组织环境的客户端，不要把公共地址硬编码进去。

明确认证方式

契约声明了两种受支持的安全方案。某个路由是否要求其一，应以该路由的 OpenAPI 定义为准。

方案	Header	适用情况
Bearer Session	`Authorization: Bearer <session-token>`	代表已登录用户或桌面 Session 操作。
Den API Key	`x-api-key: <den-api-key>`	服务集成已获发组织 API Key。

两者都不能出现在浏览器可见的静态产物、源码仓库、共享截图或支持日志中。初次连通性检查时，如果 OpenAPI 声明该路由公开，可使用无密钥端点：

curl --fail-with-body https://api.ipolloworklabs.com/health

通过客户端环境安全提供凭据后，先解析调用者，再展示受保护操作：

curl --fail-with-body \
  -H "Authorization: Bearer $IPOLLOWORK_SESSION_TOKEN" \
  https://api.ipolloworklabs.com/v1/me

构建请求闭环

客户端请求闭环先发现，再约束，写入后重新读取

多数集成问题来自使用了错误的组织上下文，或把展示名称误认为稳定 ID。

01发现
读取当前用户、组织，以及带真实过滤参数的资源集合。
02约束
根据 OpenAPI 选择组织范围、资源 ID、权限和准确请求 Schema。
03写入
通过最窄的资源路由创建、更新、归档、恢复或创建运行时。
04重新读取
读取返回的 ID、版本、resolved 表示或活动状态，再继续下一步。

分页、过滤与状态处理

资源集合具有各自的 Query 形态。例如 GET /v1/config-objects 支持 Cursor 分页、1 到 100 的 limit、资源 type、status、sourceMode、插件与连接器过滤、已删除资源筛选和文本查询。GET /v1/workers 同样使用 Cursor 分页，limit 范围为 1 到 50。

准确默认值和响应 Envelope 均以 OpenAPI Schema 为准。客户端应当：

保存上一页返回的 Cursor，而不是自行构造 Offset。
将零结果集合视为有效结果，而不是授权失败。
当路由声明了 401、403、409、422 时，分别展示可行动的状态。
日志中保留操作 ID 或资源 ID，但绝不记录凭据和原始 Provider Secret。

事实来源如何选择

问题	最佳事实来源
必填请求字段和准确响应体	当前检出 iPolloWork 版本的 `packages/docs/openapi.json`
组织、成员或授权行为	对应 `/v1` 资源族和它的 OpenAPI Operation
本地文件、会话、审批或产物操作	本地 iPolloWork Server API，而非 Den API
远程 Worker 就绪状态和 Token 行为	OpenAPI 契约中的 Worker Operations

继续阅读 认证与访问控制 了解范围决策，阅读 运行时、Worker 与 Webhook 了解异步生命周期工作。