受控开放
Base URL 与白名单端点可验证；API Key 与生产权限仍通过开通流程发放。本文档用于集成预览，不等价于匿名自助开放。
提示这页怎么用
- 把它当成“对照表”：字段、结构、示例以 OpenAPI 为准。
- 先跑通 首次请求，再回到这里逐步补齐字段。
- 不要从示例推导未公开的 URL 或能力；只沿响应返回的 follow-up URL 继续。
推荐阅读
查字段前先确定你的任务
POST /api/execute
这是当前对外公开的执行入口。生产 Base URL 为 https://api.zhenrobot.com；访问仍需通过开通流程获得凭证。
路由契约
- route id:
brain.execute - auth:
admin_or_api_key - security:
bearerAuth - surface:
gateway - stability:
phase1_gateway - current public phase:
phase 1
请求体
Schema: 公开 OpenAPI 资产 中定义的请求体结构。
IMPLEMENTATION MAP
必填执行输入
- domain
- execution_mode: "sync"
- required_scopes
- key_id
text 与 structured_input 是可选输入路径；当前公开请求中的 key_id 必须标识调用方组织和工作区签发的 API Key。
关联与稳定性
- request_id
- trace_id
- idempotency_key
- project_id · user_id · session_id
前三项用于追踪与幂等；后三项按自有系统的关联需要提供。
扩展上下文
- attachments
- exact_bridge
附件可附带标识、类型和可选元数据；exact_bridge 仅用于稳定关联既有业务记录，不是执行必填项。
协议对象边界
- Demand
- Envelope
- AuthorizationGrant
这些标准层对象应置于 structured_input，用于转换与审计关联；它们不是 POST /api/execute 默认顶层字段。
当前契约说明：
Demand、Envelope与AuthorizationGrant等中性协议对象属于zhen-protocol-c2ai2x标准层- 当前可执行 HTTP 契约不会将这些对象固定为
POST /api/execute的顶层请求字段 - 如有需要，可将协议对象放入
structured_input，用于平台转换与审计关联
200 成功响应
Synchronous success returns a completed execution envelope:
{
"output": {
"request_id": "req_...",
"trace_id": "trace_...",
"status": "completed"
},
"usage_applications": [],
"exact_bridge": {
"contract_id": "...",
"escrow_id": "...",
"org_id": "...",
"organization_id": "...",
"workspace_id": "...",
"audit_id": "...",
"source_layer": "platform-core",
"source_record": "canonical_audit"
}
}
异步边界
底层平台仍具备异步 workflow 实现，但其查询、流式读取和取消路由未进入当前公开白名单。因此公开预览只支持 execution_mode: "sync"；不要依赖未公开的 202 follow-up URL。
字段如何被理解
平台在入口侧会做这些基础转换（便于统一审计与执行）：
text：最直接的文本输入路径structured_input：用于携带更丰富的结构化上下文- 协议层对象（例如
Demand、Envelope、AuthorizationGrant）可放在structured_input中保留语义 attachments：支持attachment_id、kind，以及可选url/metadataexact_bridge：可选字段，仅用于把一次执行与既有业务记录做稳定关联（非必填）