快速开始（Quickstart）

受控开放

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

这页给已经拿到接入凭证的开发团队：把“能跑通的一条请求”升级成“可长期运行的稳定集成骨架”。

如果你还需要先走零代码或低代码路径，请先阅读接入模式。

确认凭证
使用平台正式发放的 Bearer，并按当前 Bearer 类型确认 key_id 形态。
查看这一节
发送最小同步请求
以 execution_mode: sync 调用 POST /api/execute。
查看这一节
保存回执标识
从同步响应保存 request_id 与 trace_id，便于后续排障。
查看这一节
补齐稳定性字段
上线前补齐幂等、scope、附件与会话/追踪处理。
查看这一节

当前集成流程为：

获得平台正式发放的 Bearer 凭证
组装最小平台请求
调用 POST /api/execute
调用 https://api.zhenrobot.com/api/execute 并处理同步 200 响应

1. 鉴权

入口使用 Bearer 凭证鉴权（以 OpenAPI 为准）。

路由鉴权契约：admin_or_api_key
OpenAPI security：bearerAuth

也就是：你用 Authorization: Bearer <token> 发起请求，平台会校验凭证与权限边界。

2. 最小请求

当前第一阶段可执行子集需要：

domain
required_scopes
execution_mode: "sync"
text or structured_input
key_id only when the bearer actor is admin

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

3. 稳定集成建议字段

Add these as soon as you move beyond the first successful request:

required_scopes
attachments
request_id
trace_id
idempotency_key
project_id
user_id
session_id
exact_bridge

如果需要保留 Demand、Envelope 或 AuthorizationGrant 等中性协议对象，请将它们放进 structured_input，以便平台完成转换与审计关联；它们不是当前 POST /api/execute 的顶层 HTTP 契约字段。

提示把“可跑通”升级成“可长期跑”

幂等：为关键写入类请求生成 idempotency_key，避免重试造成重复执行。
标识：稳定保存 request_id / trace_id，把排障链路固定下来。
权限：把最小 scope 写进 required_scopes，避免“默认全量权限”。

4. 同步请求示例

仅限已获发 Key 的组织

Base URL 已公开，但 $TOKEN 与 key_id 只能使用平台按组织/工作区发放的正式值。

curl -X POST "https://api.zhenrobot.com/api/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key_id": "key_example",
    "domain": "zhenins",
    "execution_mode": "sync",
    "required_scopes": [],
    "text": "I need an insurance consultation."
  }'

规范定义的同步完成响应形态：

{
  "output": {
    "request_id": "req_...",
    "trace_id": "trace_...",
    "status": "completed"
  },
  "usage_applications": []
}

5. 异步能力尚未公开

异步 workflow 的查询、流式读取与取消路由尚未进入公开白名单。当前请保持 execution_mode: "sync"，不要猜测未公开的 workflow URL。

下一步怎么走

首次请求

把第一条请求跑通并理解返回结构。

执行生命周期

同步/异步差异与 follow-up URL 处理。

鉴权与 Scopes

权限边界与常见拒绝原因。

上线检查

幂等、重试、告警与安全检查。

确认凭证

发送最小同步请求

保存回执标识

补齐稳定性字段

1. 鉴权​

2. 最小请求​

3. 稳定集成建议字段​

4. 同步请求示例​

5. 异步能力尚未公开​