用一条清晰的 API 路径，发布静态站点。

一条部署链，所有入口共用

网页上传、Public API 与 PubPage CLI V1 共用同一审核与发布流程。仓库已提供项目自有的 PubPage AI Skill 源文件 skills/pubpage/SKILL.md，用于指导 Agent 通过安全登录与官方 CLI 自动发布；外部 Skill registry/distribution 发布单独跟踪。

API Token 只放在可信服务端

Public API 使用 Authorization: Bearer <token>。Token 与网页登录 Session 是两套凭据，不能互换。

Scopes

同一个 scope 可能服务多个 operation。创建非 blank template 的 Site 还需要 deployments:write，因为模板 bootstrap 会创建普通 deployment candidate。

列出和创建 Sites

列表只返回当前 Token 所属用户拥有的 Sites。响应 envelope 包含 data 与 requestId；字段定义见下方 OpenAPI-derived Reference。

name 必填；slug 与 templateKey 的约束直接来自 OpenAPI。不要在客户端复制 slug 正则或 template enum 作为长期权威值。

模板只是普通静态文件的起点

运行时通过这个 endpoint 发现 template key、名称、摘要和 tone。不要把模板目录复制进 SDK。

选择非 blank 模板后，服务器生成普通静态文件，再调用现有上传服务；状态通过 Site 响应里的 template.status 与 template.deploymentId 跟踪。模板不能绕过 Scan 或 Review。

上传 file，必要时指定 path

请求是 multipart/form-data。OpenAPI 当前要求一个 file 字段，并允许一个可选 path 字段。单文件部署可用 path 指定安全的站内相对路径；多文件站点应打包为受支持 archive 后作为 file 上传。

上传仍受 transport safety cap、账户 storage/file-count 配额、archive/path/MIME 安全规则、上传限流和 review quota 约束。传输安全上限不是套餐“单文件空间”。

只依赖公开 deployment state

不要解析内部 Prisma status。Public API 把内部 Upload / Release / Deployment 投影成下面这些稳定状态；枚举直接读取 OpenAPI。

进一步判断时读取 review.status、publish.status、finalUrl 和有界的 reason/error。只有 published 才表示批准的 Release 已成为当前公开版本。

按 error.code 分支，保留 requestId

{
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid."
  },
  "requestId": "..."
}

每个稳定 V1 JSON 响应都有 x-request-id header，JSON envelope 也包含 requestId。日志和工单应保存 requestId，但不要记录 Authorization header。

当前 runtime 会返回的常见 machine codes 包括 invalid_api_token、token_expired、token_revoked、insufficient_scope、invalid_request、invalid_idempotency_key、not_found、site_limit_reached、storage_quota_exceeded、file_quota_exceeded、upload_too_large、upload_rejected、rate_limited 和 service_unavailable。

访问保护不等于审核豁免

Password Site 是 control-plane + wildcard UGC access-layer 能力，不是 Public API 认证模式。目前没有稳定的 /api/v1 密码管理 endpoint。

符合套餐条件的 Site 可在控制面启用密码保护。密码使用服务端 Argon2id 哈希；访问凭据绑定 Site 和 session version，生产 Cookie 为 Secure、HttpOnly、Host-only，受保护资源返回 private/no-store。HTML、CSS、JavaScript、图片、JSON、PDF 等资源都在同一访问边界后。

Operator validation pending：生产环境相关 DNS/TLS、CDN/cache、CAPTCHA、真实 PUBLIC/PASSWORD 站点与公网 E2E 仍需按独立验收清单验证。本页不把这些生产验收项描述为已完成。

CLI V1 与 PubPage AI Skill

pubpage whoami
# 如果尚未登录：
pubpage login
# 当前目录必须是带根 index.html 的静态输出：
pubpage deploy .

1. Agent 先读取 PubPage Skill，并用 pubpage whoami 检查身份；未登录时启动 browser login，不要求用户粘贴 API Token。
2. 确定用户要求发布的目录。目录发布必须有 regular root index.html；CLI 不会修改或删除源码。
3. 未传 --site 时，只有恰好一个 Site 才自动选择。没有 Site 时必须先询问用户是否创建；多个 Site 时先 pubpage sites，由用户选择。
4. pubpage deploy . 自动打包、上传 candidate 并进行有界轮询；仍保留 idempotency 与完整 Review pipeline。
5. manual_review、rejected、failed 都停止当前自动流程；特别是 rejected 后不能自动改写并重投。
6. 仅在 state 为 published 时返回成功，并输出 API 提供的 finalUrl；polling 达到边界时报告现状，不进入无限循环。

Reference 直接绑定 /openapi.json

下面的 endpoint、scope、parameter、request field、response 与 component schema 都由服务端同一份 publicOpenApiDocument 渲染。它不是第二份 contract。

Component schemas