公共 API

部署API

触发部署、查询部署记录和流式传输管道事件。

部署表面涵盖预览构建、生产发布和管道事件流。路径没有前缀并以 https://api.showly.ai 为根（没有版本前缀）。

创建部署

POST /sites/{siteId}/deploy
Authorization: Bearer <token>
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "environment": "preview",
  "commitSha": "abc123...",
  "branch": "main"
}

这是创建部署的唯一路由（路径中存在siteId；没有POST /deployments）。它需要一个 Idempotency-Key 标头 - 丢失的密钥返回 428，重播的冲突密钥返回 409。它返回202 + queued状态的部署记录。构建异步运行；订阅事件或轮询部署记录。

{
  "ok": true,
  "data": {
    "id": "8c9d3e2a-4f1b-4c6d-9a2e-1f0b3c4d5e6f",
    "siteId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "target": "preview",
    "status": "queued",
    "createdAt": "2026-05-14T15:00:00Z"
  }
}

部署记录上的环境字段名为 target，并且是 preview、staging 或 production 之一。

发布到生产环境

生产发布使用与 environment: "production" 和 sourceDeploymentId 相同的端点来命名正在推广的已构建的 ready 预览：

POST /sites/{siteId}/deploy
Authorization: Bearer <token>
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "environment": "production",
  "sourceDeploymentId": "dep_01HZX..."
}

生产发布不需要 OTP 或 MFA 注册。它仍然需要一个显式发布操作，并且当工作区有 approvalWorkflows 时启用，第二人称批准。当出现这种情况时，代理会使用request_publish 策略已启用，否则两步publish_site确认。

获取部署

GET /deployments/{deploymentId}

部署状态恰好是五个值之一：

queued → building → ready
                  ↘ failed
                  ↘ canceled

ready 是预览和生产部署的最终成功状态； failed和canceled是终端故障状态。没有 built 或 live 状态。 ready 预览部署在 url 字段中携带其地址； ready 生产部署服务于站点的生产路线。

流式构建进度

从预览界面通过 SSE 实时生成进度流：

GET /previews/{deploymentId}/stream
Accept: text/event-stream

当部署达到最终状态时，流发出状态转换并关闭。对于事后读取，两个普通端点可以满足大多数需求：

GET /deployments/{deploymentId}/log?lineCount=200 — 捕获的构建日志尾部。
GET /deployments/{deploymentId}/diagnostics — 专为代理自调试而设计的结构化故障包（阶段、错误代码、日志尾部、排名假设）。

批准/拒绝生产发布请求

POST /approvals/{requestId}/decision
Content-Type: application/json

{
  "decision": "approve" | "reject",
  "notes": "looks good"
}

需要具有允许的批准角色的活跃用户成员资格。禁止发起者批准自己的请求（职责分离）。

回滚

没有回滚REST端点。恢复到之前的部署仅是 Web-UI 操作。要重新发布之前的 ready 预览版，请使用 environment: "production" 调用 POST /sites/{siteId}/deploy，并且该部署的 ID 为 sourceDeploymentId；正常审批、配额和安全门仍然适用，但不需要 OTP 注册。

列出部署

GET /deployments

以普通数组的形式返回工作区的完整部署列表 - 尚无过滤器或分页参数。对于单个站点的历史记录，请使用 GET /sites/{siteId}/deployments。

特定于部署的错误

代码	状态	意义
`idempotency_key_required`	428	428调用 `POST /sites/{siteId}/deploy` 时没有 `Idempotency-Key` 标头。
`idempotency_key_conflict`	409	409提供的 `Idempotency-Key` 已用于不同的请求。
`deployment_not_found`	404	404令牌看不到此部署。
`approval_required`	428	428生产发布需要经过批准才能推广。
`source_deployment_required`	428	428生产发布必须通过 `sourceDeploymentId` 命名 `ready` 预览。
`self_approval_forbidden`	403	403批准者是发起者（职责分离）。
`source_deployment_not_found`	404	404 `sourceDeploymentId` 不存在或对您的令牌不可见。
`source_deployment_not_ready`	409	409指定的源部署不处于可发布 (`ready`) 状态。

耗尽每月部署配额会返回 402 并出现配额错误 — 升级计划或等待每月重置。

模式

等待部署完成 (CI)：

DEP=$(curl ... | jq -r .data.id)
while :; do
  S=$(curl -sS .../deployments/$DEP | jq -r .data.status)
  [ "$S" = "ready" ] && break
  { [ "$S" = "failed" ] || [ "$S" = "canceled" ]; } && exit 1
  sleep 10
done

阅读构建日志：

curl -sS ".../deployments/$DEP/log?lineCount=500" \
  | jq -r '.data.lines[]' | tee build.log

对于大多数自动化，MCPcreate_preview工具更简单——对于MCP不适合的情况存在RESTAPI。