公共 API 概述
何时应直接使用 REST API，而不是 MCP 工具。
Showly 的公共 REST API 适用于不方便使用 MCP 的场景，例如 CI 脚本、 自定义仪表盘，以及不由智能体驱动的第三方集成。
如果你正在开发智能体，请优先使用 MCP。 MCP 原生提供审计、带作用域的令牌和类型化工具输入。REST API 提供相同的操作，但接口更通用，主要面向由人维护的自动化。
基础 URL
https://api.showly.ai所有请求都必须使用 TLS；纯 HTTP 请求会被拒绝。
版本控制
当前没有 /v1/ 前缀或 Api-Version 请求头，API 采用单一版本线。 破坏性变更会作为重要事件发布在公开的更新日志中， 并注明日期、受影响的路由和迁移说明。如果你维护长期运行的集成， 请关注该页面。新增可选字段、端点等向后兼容的变更会随常规版本发布。
身份验证
每个请求都需要一个 Authorization: Bearer <token> 标头。您将使用的凭据：
- 个人访问令牌（PAT） — 前缀为
sk_live_/sk_test_。PAT
只属于创建它的单个工作区，并包含创建时授予的作用域，适合临时 脚本和 CI。
- MCP 令牌 — 前缀为
mcp_live_/mcp_test_，可从
工作区设置 → MCP 客户端签发，也可通过设备授权流程获得。令牌 限定在单个工作区，既可用于 MCP，也可验证 REST 请求。
对于无法粘贴静态令牌的智能体环境，Showly 支持 RFC 8628 设备授权流程（POST /oauth/device，然后轮询 POST /oauth/token），并生成绑定到授权用户的 MCP 令牌。完整流程和令牌轮换方式见身份验证。
响应结构
每个 JSON 响应都使用统一的外层结构。成功响应：
{
"ok": true,
"data": { ... }
}错误：
{
"ok": false,
"error": { "code": "string", "message": "string" }
}error.code 是稳定的程序契约，调用方应按它分支，不要依赖 error.message。错误码使用 kebab-case 或 snake_case 标识符，例如 rate_limited、idempotency_key_conflict、not_found。 error.message 面向人类阅读，可能随版本调整。
速率限制
速率限制取决于已认证工作区当前生效的配置。无论工作区如何计费， MCP 令牌默认最多每分钟请求 60 次；高流量路由可能有更严格的单路由 限制。
触发限流后，服务器返回 HTTP 429、error.code: "rate_limited"， 以及以秒为单位的 Retry-After 请求头。请严格等待该时长后再重试。
幂等性
创建部署的 POST /sites/:siteId/deploy 必须携带 Idempotency-Key 请求头，否则服务器返回 428。键由调用方生成； 建议每次逻辑操作使用一个 UUID。生产发布也通过同一路由提交 environment: "production" 和 sourceDeploymentId，因此要求相同。 其他路由目前不要求该请求头。
使用同一个键重放相同请求时，服务器会返回首次调用的缓存响应。如果 同一个键对应的请求体发生变化，服务器返回 409 和 idempotency_key_conflict。
只读 GET 请求自然是幂等的并且忽略标头。
分页
列表端点（GET /sites、GET /deployments）当前以普通数组返回工作区 的完整结果集，尚无游标或 limit 参数。未来若增加分页，会以向后兼容 的方式使用不透明游标，并在变更日志中说明。