API 概览
Cloady REST API 的身份验证、权限范围、约定和错误。
在控制台里能做的一切，都可以通过 HTTP 完成：工作区、应用、部署、域名、变量、成员。控制台本身调用的也是这套 API。
基础 URL
https://cloady.com/api所有请求和响应都是 application/json。凡是带请求体的请求，都要发送 Content-Type: application/json。
身份验证
使用个人 API 令牌进行身份验证，以 Bearer 令牌的形式传递：
Authorization: Bearer cldy_...令牌代表你本人：它能访问你所属的工作区，在每个工作区中的角色都与你相同。密钥只在创建时显示一次，之后无法再次获取；如果丢失了，请吊销它并新建一个。
令牌可以设置有效期（never、30d、90d、1y），也可以随时吊销。缺失、格式错误、已过期或已吊销的令牌会得到 401 unauthorized。
令牌还可以绑定到某一个工作区。这样一来，对其他任何工作区的请求都会返回 403 forbidden，无论你在那里是什么角色。
你的账号必须有已验证的手机号；否则，所有需要身份验证的端点都会返回 403 phone_required。在控制台的 Account → Security 中验证一次即可。
创建令牌
在控制台中打开 Account → API tokens（参见控制台指南）。选择名称、权限范围和有效期。密钥只显示一次，请立即复制。创建令牌这一操作本身，需要 full 权限范围的令牌或已登录的浏览器会话。
令牌权限范围
每个令牌在创建时都带有一个权限范围，它限定了令牌能做什么：
read— 只读。可以列出和查看工作区、应用、部署和日志，不能做任何修改。deploy—read能做的一切，再加上 developer 能做的操作：部署、重新部署、启动、停止和重启，管理域名和变量，以及删除应用（这会永久删除应用的数据）。full— 不受限制。deploy能做的一切，再加上管理类操作：创建工作区，以及管理工作区设置、成员、集成和计费。
请选择能满足需求的最小权限范围，例如用于 CI 部署的令牌应该选 deploy，而不是 full。
工作区角色
权限范围限定的是令牌；你在工作区中的角色限定的是请求。工作区端点要求一个最低角色，角色由低到高依次为：
viewer— 查看工作区及其应用。developer— 部署和运维应用，包括部署、重启、日志、Shell、数据库、域名和变量，以及删除应用。admin— 管理工作区设置、成员、集成和单点登录。owner— 拥有全部权限，包括计费和删除工作区。
角色低于端点最低要求的请求会返回 403 forbidden。如果你不是某个工作区的成员，对它的请求会返回 404 not_found：成员关系从不对外透露。
env 与 region 查询参数约定
每个应用运行在一个区域和一个环境（production、preview 或 development）中，应用名称在同一工作区和环境内唯一。控制台 URL 把区域和环境作为路径段，而 API 请求把它们作为查询参数传递：
?env=<production|preview|development>®ion=<regionId>env省略时默认为production。region是可选的，很少需要。只有同一名称存在于多个区域时才需要传：这类请求会返回400 region_required，你需要带上?region=重试。
GET /api/workspaces/acme/apps/my-blog?env=production®ion=usw1区域 ID 可以通过 GET /api/regions 获取。任何工作区都可以部署到其中任意一个区域；区域在部署应用时选定。
这些路径通过名称定位应用和工作区，而应用的公开地址也随名称而定，所以重命名会同时改变你调用的 URL 和应用对外提供服务的 URL。请更新所有引用旧名称的脚本。即便如此，重命名仍是安全的做法：删除应用会永久删除它的数据。
流式端点
应用状态、指标、部署进度、部署日志和工单消息，都以服务器发送事件（server-sent events）的形式推送。发送 Accept: text/event-stream 可以获取实时流；不带这个请求头时，你会以普通 JSON 的形式拿到一次当前状态，这正是脚本需要的。服务日志也是如此：对普通请求，它会返回最近 200 行。
错误格式
错误带有一个机器可读的 code：
{ "error": { "code": "not_found", "message": "App my-blog not found" } }从 body.error.code 读取错误码，并据此进行分支处理，切勿只依据消息或状态码。校验失败（bad_body）时，还会附带一个 details 数组，列出出错的字段。
| 状态码 | 常见的 code | 含义 |
|---|---|---|
400 | bad_body、bad_reference、bad_region | 请求体格式错误、缺少字段，或名称/区域不存在 |
400 | region_required | 该名称匹配到多个区域中的应用，请带上 ?region= 重试 |
401 | unauthorized | 令牌缺失、已过期或已吊销 |
403 | forbidden | 角色不够、令牌权限范围不够，或令牌绑定的是另一个工作区 |
403 | phone_required | 账号没有已验证的手机号 |
402 | payment_required | 此次变更会让工作区超出免费额度，而目前没有绑定银行卡，或银行卡扣款被拒 |
402 | payment_failed、payment_action_required | 银行卡付款（例如域名订单）被拒，或需要银行确认 |
404 | not_found | 找不到工作区或应用 |
503 | billing_misconfigured | 计费服务不可用 |
示例
列出你的工作区：
curl https://cloady.com/api/workspaces \
-H "Authorization: Bearer cldy_..."{
"workspaces": [ /* ... */ ]
}完整的端点目录（路径、方法、参数和请求体），请查看侧边栏中的各个端点页面，可以从 listWorkspaces 开始。