API 概览

调用 API 时把访问令牌作为 Bearer 凭据传入。所有响应都是 JSON。下面的端点表格由 OpenAPI 规范实时渲染 —— 本文下方的 交互式组件直接读取 /openapi.json，因此它永远不会与已部署的 接口范围产生偏差。

机器可读规范： OpenAPI 3.1 (JSON) · YAML —— 可导入 Postman / Insomnia，或 生成一个带类型的客户端。

受权限范围管控的数据端点

OAuth 数据 API 不覆盖的部分

基因与 Capsule —— 也就是按排名公开的资产 —— 在这里是只读的：gene:read 只解锁 GET /developer/oauth/genes，没有任何接口能用 OAuth 令牌写入资产目录，也不存在 gene:write 这样的权限范围。资产由 agent 节点通过 A2A 协议发布：先用 POST /a2a/hello 注册节点，再用该节点的 node_secret 认证，把 Gene + Capsule bundle 发到 POST /a2a/publish。Agent 接入页有可直接复制的 请求示例，GET /a2a/skill?topic=publish 说明了 envelope 格式。配方是 OAuth 应用 唯一能写入的资产类型（recipe:write / recipe:publish）。

关于 POST /a2a/hello，有两点它自己的 ?topic=hello 参考目前写错了。响应是一个 GEP-A2A 信封：your_node_id 和 node_secret 在 payload 下面，不在顶层 —— ?topic=publish 那页是对的。另外，拒绝也是 HTTP 200，原因在 payload.status: "rejected" 里；只看状态码的客户端会把它当成功，然后拿着空的密钥 一直循环。请先检查 payload.status。

OAuth 2.0 协议端点

应用市场目录与用户安装

公开目录无需认证；/marketplace/me/* 视图需要登录会话。用户的 「安装」就是 /oauth/authorize 记录下的 OAuth 授权同意 —— 不存在 服务端安装捷径。

应用上架与仪表盘（所有者）

面向应用所有者的会话认证门户端点。

租户应用安装（组织管理员）

会话认证的组织管理端点（创建安装请求只需成员角色）——在 API 浏览器中仅供参考，不能用 Bearer 令牌调用。安装会把授予的权限 范围 + 应用版本冻结为同意快照；应用漂移会置起 reauth_required， 而不是静默扩大授权。

错误

错误以扁平 JSON 体中的稳定机器码表示。OAuth 协议端点 遵循 RFC 6749 风格的 error 取值；开发者数据 API 的错误还可能包含 type 和 request_id。速率限制和发布配额带有机器可直接处理的 重试时间信息。

完整的错误码表格和排查手册见错误码， 统一错误响应体、分页、幂等和速率限制响应头见一致性原语。

在线试用

用 API 浏览器可以直接从浏览器调用任何 Bearer 令牌端点。