API 概览

完整字段以 当前 OpenAPI spec 为准。本页只列调用时不能猜错的公共约定。

Base URL 与路径

https://webagent.qoni.ai

user-facing 路由使用 /api/v1 前缀，并按 project 隔离：

/api/v1/projects/{pid}/...

当前四个产品的创建路径：

能力	创建路径
DoAnything	POST /api/v1/projects/{pid}/do_anything/runs
Track	POST /api/v1/projects/{pid}/track/tracks
DeepResearch	POST /api/v1/projects/{pid}/deep_research/runs
WebSearch	POST /api/v1/projects/{pid}/web_search/runs

鉴权

原生 HTTP 可以使用项目 API key：

Authorization: Bearer wa_xxxxxxxxxxxxxxxxxxxxxxxx

Node SDK 使用 Qoni AK/SK 初始化，再通过 delegateToken() 取得代表终端用户的短期 token；SDK 会自动解析 project 路径。不要在浏览器中暴露 AK/SK。

状态与异步

DoAnything、DeepResearch、WebSearch 创建接口返回 202 和 run envelope。用 GET .../{run_id} 轮询或订阅 .../events；Node SDK 用 run.wait() 等待终态。

常见 run 状态：pending、running、awaiting_input、succeeded、failed、canceled。不要把旧文档中的 done 当作 status；done 是一种 terminal_reason。

SSE

事件流返回 JSON 编码的 SSE，并支持：

Last-Event-ID: <最后收到的事件 id>

断线后服务端会从该 ID 之后重放事件。Node SDK 的 events() / wait() 已处理常规重连；需要底层 wire 事件时看 event.raw。

错误

错误响应是 JSON envelope，包含 HTTP status、稳定的 code 和 detail。业务逻辑按 code 判断，不要解析 detail 文案。具体错误码和可重试范围见错误码与重试。

Track 路径描述当前后端契约；npm 0.9.0 的旧 Track 入口不兼容，SDK 修复候选尚未发布，见 Track。