API 概览

本页讲 WebAgent 所有端点共享的约定。具体每个端点字段请直接看 OpenAPI 3.1 spec——SDK 和 Console 的 Get Code 对话框都是从这里生成。

Base URL

https://api.web-agent.asix.inc

所有资源 path 以 project 为前缀：

/v1/projects/{project_id}/...

鉴权

Authorization header 带 bearer token，详见 鉴权与 API key：

Authorization: Bearer wa_xxxxxxxxxxxxxxxxxxxxxxxx

错误

JSON 响应体 + HTTP 状态 + 稳定的 code 字段（可程序判断）：

{
  "code": "session_not_found",
  "detail": "Session sess_demo_0001 not found.",
  "extra": { "session_id": "sess_demo_0001" }
}

状态	常见 code
400	bad_request
401	unauthorized
402	insufficient_credits、budget_exceeded
403	forbidden、safety_boundary_violated
404	session_not_found、task_not_found、profile_not_found……
409	conflict
422	validation_error
429	rate_limit_exceeded、too_many_concurrent_sessions
5xx	internal_error

限流

• per-key 并发 session 数——按 plan
• per-key 请求频率——滑动窗；超时返回 429 + Retry-After
• per-project 月额度——80% 软警告，100% 硬停

分页

list 类端点全是 cursor 分页：

GET /v1/projects/{pid}/do_anything/sessions?limit=50&cursor=eyJ…

响应里带 next_cursor（最后一页是 null）。limit 上限 100。

幂等

变更类端点（POST /sessions、POST /messages……）支持 Idempotency-Key header。同 UUID 重发返回同响应——retry 安全。

SSE 约定

流式端点（…/events）发 JSON 编码 SSE 事件，带数字 id。断线后用 Last-Event-ID: <last_id> 续传，server 重放该 id 之后的全部事件。

接下来

• OpenAPI spec —— 每个端点、每个字段，机器可读
• Sessions 与 Tasks —— 资源模型
• 错误码与重试 —— 完整错误码矩阵