API / V1

用稳定 HTTP 契约驱动 GoClaw。

生产 API 基地址为 https://goclawai.com/api/v1。所有示例使用 Workspace 级短期 Bearer Token；浏览器 Session 另需 CSRF 保护。

BASE URL

先验证版本与身份

版本端点无需认证。其他请求使用 Authorization: Bearer；令牌已绑定 Workspace 时 Header 可省略，但显式携带便于发现配置错误。

检查生产 API

curl -fsS https://goclawai.com/api/v1/version

curl -fsS https://goclawai.com/api/v1/workspaces/current \
  -H "Authorization: Bearer ${GOCLAW_TOKEN}" \
  -H "X-GoClaw-Workspace-ID: ${GOCLAW_WORKSPACE}"

CREATE RUN

幂等地创建 Run

POST /runs 接受 workload、provider 与 region。相同业务重试复用同一个 Idempotency-Key；不要为每次网络重试生成新键。

提交最小 Run

curl -fsS https://goclawai.com/api/v1/runs \
  -X POST \
  -H "Authorization: Bearer ${GOCLAW_TOKEN}" \
  -H "X-GoClaw-Workspace-ID: ${GOCLAW_WORKSPACE}" \
  -H "Idempotency-Key: onboarding-run-001" \
  -H "Content-Type: application/json" \
  --data '{"workload":{"image":"alpine"},"provider":"auto","region":"auto"}'

OBSERVE

查询状态或恢复事件流

GET /runs/{runId} 返回当前派生状态。GET /runs/{runId}/events 使用 text/event-stream；断线时把最后一个事件 ID 放入 Last-Event-ID。

GET /api/v1/runs/{runId}
GET /api/v1/runs/{runId}/events
POST /api/v1/runs/{runId}:cancel

ERRORS

按 Problem Details 处理错误

错误响应为 application/problem+json，包含稳定 code、requestId、retryable 和可选 params。程序判断 code 与 HTTP 状态，不解析自然语言 title。

409 可能表示审批、版本或幂等冲突。
429 与 retryable=true 的 5xx 才进入有界退避。
提交支持工单时保留 X-Request-ID，不要附带 Token。

CONTRACT

OpenAPI 是机器契约

字段、枚举、Header、响应码和 schema 以仓库中的 OpenAPI 3.0 文档为准。生成客户端时固定版本，并在升级前检查契约差异。

查看 OpenAPI

SECURITY

不要把 Provider Key 当 API Token

GOCLAW_TOKEN 只授权 GoClaw Workspace；百炼等 Provider Key 仅保存到 Provider Credential。两者都不应出现在 URL、日志、截图或前端源码。