受控开放

Base URL 与白名单端点可验证；API Key 与生产权限仍通过开通流程发放。本文档用于集成预览，不等价于匿名自助开放。

这页给已经准备做 Full API 集成 的团队：用一条最小请求跑通鉴权、请求体和同步返回，作为后续稳定接入的起点。

如果你还在判断是否需要 API，先看 选择接入路径 或 完整接口接入；Hosted Inbox 与 Widget Embed 不需要从本页开始。

提示开始前确认三件事

• 你已经确定需要系统级集成（而不是 Hosted Inbox / Widget Embed）。
• 你已经拿到平台签发的 Bearer 凭证（以及必要时的 key_id）。
• 你本次目标是“先跑通最小链路”，不要一次把所有业务字段都塞进来。

推荐阅读

这条最小链路验证什么

凭证

Bearer 能被平台识别，并具备所需权限。

请求体

最小字段能够通过入口校验并进入执行。

同步返回

能够读取 200 响应并保存排障标识。

请求入口

• Base URL：https://api.zhenrobot.com
• 路由：POST /api/execute
• 鉴权：Authorization: Bearer <token>

最小可用请求

{
  "key_id": "key_example",
  "domain": "zhenins",
  "execution_mode": "sync",
  "required_scopes": [],
  "text": "I need an insurance consultation."
}

• domain：目标业务域。
• execution_mode：当前公开预览固定为 sync。
• required_scopes：本次请求所需的最低权限。
• text：最小输入内容。

当 Bearer 为 api_key 时，key_id 通常可由凭证侧解析，不必在 body 重复传入；当 Bearer 为 admin 时，当前请求形态仍要求 body 中提供 key_id（以实际 OpenAPI 为准）。如需携带协议层对象（例如 Demand、AuthorizationGrant），请放在 structured_input 中作为上下文载体即可。

返回值怎么处理

• 200：同步完成，返回 output 与 usage_applications（以及可选 exact_bridge）。
• 当前公开预览通常只建议从 sync 开始：先把同步链路做稳定，再考虑异步与回调相关能力。

推荐阅读

卡住时先看这些页

把问题定位到鉴权、请求字段、还是结果处理链路，然后再继续往下推进。

鉴权与 Scopes

Bearer 与 required_scopes 的写法、常见拒绝原因。

执行生命周期

200 / 202 的差异、如何接住后续 URL。

API Reference

字段、返回结构与 OpenAPI 对照。

Error Model

把错误分类成“鉴权/请求体/后续查询”三段来处理。

下一步

1. 用 快速开始 把最小请求补成可长期运行的稳定接入。
2. 用 鉴权与 Scopes 固化你的权限与最小 scope 集合。
3. 用 API Reference 校准字段与响应结构，再进入上线准备。