Client API v1

Client API 是外部业务系统、Agent 平台和自动化工具触发 BailingHub 的稳定边界。它不是执行器协议，也不是 Agent Client Runtime。

提交任务

POST /run
Authorization: Bearer <client-token>
Content-Type: application/json

{
  "request_id": "order-10001-ai-001",
  "route": "order_assistant",
  "input": "分析订单为什么仍未发货",
  "metadata": {
    "principal": { "id": "u_42", "tenant": "t_100" },
    "order_id": "10001"
  },
  "callback_url": "https://biz.example.com/ai/callback"
}

字段	规则
`request_id`	接入方作用域内的幂等键；重试必须复用同一值
`route`	后台配置并在接入方白名单内的稳定路由 key
`input`	不可信业务任务文本，不能用来决定权限
`metadata`	可选业务上下文；最终授权仍由业务系统负责
`callback_url`	可选 HTTP(S) 完成回调地址

请求只接受契约允许的顶层字段。不要沿用旧文档中的 callback 或自行添加 source。

查询任务

GET /jobs/{job_id}
Authorization: Bearer <client-token>

任务状态可能是：queued、running、dispatched、done、error 或 rejected。超时或网络中断时查询同一 job_id，不要用新的 request_id 盲目重建写任务。

完成回调

配置 callback_url 后，中枢发送签名回调。业务后端必须验证时间戳、HMAC 和允许的时间窗口，再消费结果；回调失败不等于任务未完成，仍应保留按 job_id 查询的兜底路径。

机器可读契约