HTTP API

Base URL：CONTROL_ORIGIN/api/v1。错误使用 application/problem+json 与稳定错误码。以下示例中的源请替换为实际控制面。

匿名首次部署

curl --fail-with-body -sS -X POST "https://coderuntime.com/api/v1/deploy" \
  -H "Idempotency-Key: 01900000-0000-7000-8000-000000000099" \
  -F "archive=@site.zip" \
  -F "intent=auto"

成功 201：响应含 workspaceId、projectId、 url、versionUrl、deployment、 quota。API/CLI 路径在首次成功时额外返回一次 guestToken；官网 Cookie 模式不会在 JSON 中暴露 Token。

Idempotency-Key 可选但推荐：同一键在 24 小时内重放同一结果，不创建第二版本。超时后请复用原键重试。

同一项目再次部署

curl --fail-with-body -sS -X POST "https://coderuntime.com/api/v1/deploy" \
  -H "Authorization: Bearer $GUEST_TOKEN" \
  -H "Idempotency-Key: 01900000-0000-7000-8000-000000000100" \
  -F "archive=@site.zip" \
  -F "intent=auto" \
  -F "projectId=$PROJECT_ID"

Guest 只能更新自己的唯一项目。稳定 url 不变；版本递增。未带 Token 却指定他人 projectId 会失败。

常见错误码

429 RATE_LIMITED / WORKSPACE_PROJECT_QUOTA_EXCEEDED — 额度或速率
403 CONTENT_SUSPENDED / WORKSPACE_SUSPENDED — 政策暂停
451 CONTENT_LEGALLY_UNAVAILABLE — 法律下线
503 SERVICE_UNAVAILABLE — 备份过久等运营保护（仅拦新发布）
507 — 磁盘不足

邮箱 OTP

POST /api/v1/auth/email/challenges
POST /api/v1/auth/email/challenges/{id}/verify
POST /api/v1/auth/logout

认领

POST /api/v1/claims
GET  /api/v1/claims/{id}
POST /api/v1/claims/{id}/authorize
POST /api/v1/claims/{id}/confirm
DELETE /api/v1/claims/{id}

认领需要原设备上的 Guest 凭据二次确认。Guest Token 丢失不提供人工恢复。完整 schema 见仓库 packages/contracts/openapi.json。第一期不含支付、自定义域名或私有预览。