站点API

站点表面允许您在工作区中枚举、检查和创建站点。 REST API没有版本前缀：下面的所有路径都以https://api.showly.ai为根。

列出站点

GET /sites
Authorization: Bearer <token>

返回令牌可以看到的每个站点（一个普通数组 - 还没有分页），以及带有工作区站点上限的同级 entitlements 对象。

{
  "ok": true,
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "projectId": "9b2f1c44-0d31-4c19-8a77-0f4bd4a1c001",
      "slug": "marketing-site",
      "name": "Marketing site",
      "framework": "next-export",
      "status": "active",
      "repositoryUrl": "https://github.com/acme/marketing",
      "productionUrl": "https://marketing-site.showly.site",
      "createdAt": "2026-03-01T10:14:22Z",
      "updatedAt": "2026-07-01T08:03:10Z"
    }
  ],
  "entitlements": {
    "maxSites": "unlimited",
    "currentSites": 3,
    "maxLiveSites": "unlimited",
    "currentLiveSites": 1
  }
}

站点 ID 是 UUID。 framework 值是构建器自动检测的自由格式字符串（例如 next-export、astro、static-html）。

站点数量额度

maxLiveSites 表示正式站点的商业额度。Free 和 Pro 都返回 "unlimited"。自定义合同或单独的权益覆盖仍可能返回有限数值，此时发布流程 会按该数值检查。

maxSites 覆盖所有活跃站点记录，包括仅有预览的站点；所有基础套餐均返回 "unlimited"。只有运营人员为某个工作区设置明确覆盖时才会出现有限数值；从 Free 升级到 Pro 不会增加站点名额。工作区预览不会过期。

获取单个站点

GET /sites/{siteId}

返回站点以及当前清单和最新部署摘要。

创建站点

POST /sites
Content-Type: application/json

{
  "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Docs",
  "slug": "docs",
  "repositoryUrl": "https://github.com/acme/docs"
}

返回 201 和创建的站点。projectId 是站点所属项目的 UUID。slug 必须匹配 ^[a-z0-9-]+$，并且在工作区中唯一；如果发生冲突，接口会返回 409 和 error.code: "slug_taken"。framework 和 repositoryUrl 是可选字段。

构建配置位于提交到存储库的 showly.json 清单中，而不是在创建主体中。构建器自动检测框架并从该文件读取 rootDirectory、runtime、buildCommand、output 以及相关字段。有关完整架构，请参阅站点清单。

部署目标

部署目标是在组织级别而不是每个站点配置的。它们安装在/deployment-targets：

目标带有 provider、mode 和 runtime。能力端点是 当前环境中启用的组合的真实来源；枚举 API 模式中的值不保证提供程序已配置。 不支持的组合返回 400 deployment_target_not_implemented。

在您自己的云帐户中注册部署目标需要 byoCloudTargets 权利和用户参与者。仅令牌机器人无法创建， 更新或删除自己的云目标。

Curl 示例：端到端创建 + 首次部署

# 1. Create the site
SITE=$(curl -sS -X POST https://api.showly.ai/sites \
  -H "authorization: bearer $SHOWLY_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Demo", "slug": "demo", "repositoryUrl": "https://github.com/acme/demo" }' \
  | jq -r '.data.id')

# 2. Inspect the site (and the auto-detected manifest)
curl -sS "https://api.showly.ai/sites/$SITE" \
  -H "authorization: bearer $SHOWLY_TOKEN"

# 3. Request a preview deployment (siteId in the path; Idempotency-Key required)
curl -sS -X POST "https://api.showly.ai/sites/$SITE/deploy" \
  -H "authorization: bearer $SHOWLY_TOKEN" \
  -H "content-type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{ "environment": "preview" }'

创建部署的调用返回 202。POST /sites/:siteId/deploy 必须包含 Idempotency-Key 请求头；缺少时返回 428，冲突的重试返回 409。部署生命周期的其余部分见部署。

归档和恢复

删除站点会将其归档：它会从 GET /sites 中消失，但仍会列在 GET /sites/archived 中。站点不会仅仅因为一直处于预览状态就被自动归档。 明确删除后可以复用 slug。如果工作区存在有限的显式 maxSites 覆盖值，删除还会 释放其中一个覆盖名额。

带回一张：

POST /sites/:siteId/restore

该站点返回空并准备重新部署 - 其旧部署不可用 复活了，因为他们的构建工件已经被垃圾收集了。 恢复会消耗一个站点槽位，因此如果您在您的位置，它会返回 402 maxSites 津贴，404 如果 id 未知，则属于另一个 工作区，或者已经处于活动状态。

错误