调用 API

一切应用程序的操作都通过您可以自己调用的相同 HTTP API 完成。每个端点在 REST API 参考中列出；本页面涵盖您在调用任何端点之前需要了解的三件事。

认证

将身份令牌作为 Bearer 凭证发送：

curl -H "Authorization: Bearer <your-token>" \
     https://app.example.com/api/workflows

令牌来自登录。没有单独的 API 密钥需要创建：您的 API 身份就是您的用户身份，因此您在应用程序中可以访问的任何内容都可以通过 curl 访问，且没有其它方式。

每个端点都需要这个。 不允许匿名读取：没有凭证的请求在到达端点之前就会被拒绝，无论该端点是什么。少数公开路径——定价列表，这些文档——是明确决定公开的，而不是因为身份验证是可选的。

如果您属于多个工作区，请告知我们请求作用于哪个工作区：

curl -H "Authorization: Bearer <your-token>" \
     -H "X-Account-Id: <workspace-id>" \
     https://app.example.com/api/workflows

省略它会得到您最早的工作区。发送您不是成员的工作区 ID 将使您获取到您最早的工作区——该头部在您已属于的工作区之间进行选择，而不是授予您对您不属于的工作区的访问权限。

由于历史原因，该头部命名为 X-Account-Id；其值是工作区 ID。在其他地方，这个词指的是您自己的登录。

您只能看到自己工作区的数据。集合端点返回您的行而不返回其他；请求您不属于的工作区中的内容将被拒绝，而不是返回空值。

如果您的组织运行多个品牌产品，您调用的主机将决定选择哪个。相同的凭证在两个不同的主机上可以看到不同的工作区集合——您在每个主机上所拥有的工作区。这是故意的：工作区属于一个品牌，请求必须说明它是用于哪个品牌。

状态	意义	解决方案
`401`	没有凭证，或凭证无效	重新登录并使用新令牌重试
`402`	工作区没有有效的订阅	读取仍然有效；写入需要计划。请参见使用和计费
`403`	已认证，但您无法操作	您不是该工作区的成员，或该操作需要所有者权限
`404`	未找到 — 或者不是您的	对于按名称寻址的资源，我们返回 404 而不是 403，以便响应不确认某个资源存在
`429`	速率限制，或预付信用用尽	放慢速度；如果提示信用，补充余额

了解 402 是很重要的：未支付的工作区变为只读而不是关闭。您仍然可以访问已存在的所有内容，并且您仍然可以导出它——您只是无法在没有计划的情况下创建新工作。计费和成员资格端点仍然有效，因为这些是您修复问题的方式。

两类端点不是由已登录人员调用，因此它们不使用您的令牌：

当拥有工作区没有有效订阅时，两个都会直接拒绝，而不是降级为只读。在他人的网站上的陌生人不应看到计费问题。