一份规范，管理你的小屋

机器可读的接口规范

GET /api/v1/openapi.json 返回一份 OpenAPI 3.1 文档，准确描述当前部署实现的内容：每个路径、模式、所需权限范围和响应，以及 webhook 事件。它由运行中的操作目录生成，MCP 工具也来自同一目录，因此 REST 与 MCP 始终保持一致。

curl -s "https://<your host>/api/v1/openapi.json"

接口涵盖小屋与草稿、修订与发布、动态、模板目录、导入、域名组合与批量运行、域名与 DNS 计划、邮件转发、订阅与联系设置、社交来源、分析、推广、账单、团队成员和 webhook。GET /workspaces/{id}/capabilities 会告诉你，这些功能在你的工作区中哪些已经可用，哪些处于模拟状态，哪些正在等待凭据。

有意识地重试

• 每次修改操作都需要一个长度为 16 至 128 个字符的 Idempotency-Key 请求头。以相同键和请求体重复发送请求，会返回原来的结果，并附带 Idempotent-Replayed: true。相同键搭配不同请求体会返回 409 idempotency_key_reused。
• 编辑小屋时，需要在 If-Match 中提供上次读取获得的 ETag。过期的值会返回 412 revision_conflict，且不会作出任何更改。
• 发布需要你读取到的确切 revision_id 和 expected_digest，确保发布的正是你检查过的内容。

耗时操作以任务执行

发布、批量运行和其他较慢的操作会返回 202 和一个任务。轮询 GET /workspaces/{id}/jobs/{job_id} 的间隔不得短于 next_poll_after_seconds，也可以订阅 job.updated webhook。请求已接受并不代表工作已完成：报告成功之前，请读取任务的 state、各项计数和 error。

错误采用问题详情格式

错误使用 application/problem+json 格式，其中包含稳定的 code、本地化的 title、request_id 和 retryable。请根据 code 判断处理方式，不要根据标题文本判断。

{
  "type": "https://<your host>/problems/insufficient_scope",
  "title": "This token does not include the permission this action needs.",
  "status": 403,
  "code": "insufficient_scope",
  "request_id": "01M5...",
  "retryable": false,
  "context": { "required_scope": "account:read" }
}

列表与限制

• 列表端点接受 limit（最多 100）和上一页返回的 cursor。
• 每个工作区令牌每分钟最多可执行 120 次读取和 30 次写入。超过限制会返回 429 和一个 Retry-After 请求头。
• 保留响应中未知的字段：新增字段可能不会伴随版本号变更。