开始使用 Instatus API

所有端点都在 https://api.instatus.com 之下,整体遵循 REST 架构。

所有请求都必须编码为 JSON,并带上 Content-Type: application/json 请求头。

Instatus API 的响应(包括错误)同样以 JSON 编码。

认证

调用 Instatus API 的请求必须通过 Authorization 请求头发送 API 密钥:

Authorization: Bearer <API_KEY>

在控制台 › 开发者中点击创建密钥来创建密钥。你可以拥有多个密钥,每个都有自己的名称,例如“GitHub Actions”或“Terraform”。密钥以 inst_sk_ 开头。

密钥能做什么

每个密钥都有自己的设置:

  • 角色:成员、编辑者,或 Business 套餐中的自定义角色。角色决定密钥能查看和修改哪些内容,和对人的作用一样。密钥不能是所有者,因此账单、角色和删除操作始终由人来负责。
  • 访问权限:查看和更改或仅查看。仅查看的密钥无法修改任何内容,无论其角色允许什么。
  • 项目:所有项目(包括你之后添加的项目),或仅限你选择的项目。
  • 过期时间:密钥停止工作的日期。在 Free 套餐中,密钥最长可使用 90 天;Pro 套餐最长 1 年;Business 和 Enterprise 套餐不限时长,也可以永不过期。团队所有者可以在团队设置 › API 密钥中设置更短的上限。在密钥设置推出之前创建的密钥不受影响,现有密钥在套餐变更后也会保留原来的日期。
  • 允许的 IP:在 Business 套餐中,密钥只能从你列出的 IP 地址或地址段使用。

密钥属于团队或属于你:

  • 团队密钥在创建者离开团队后仍会继续工作。可将其用于 CI、脚本和集成。
  • 个人密钥以你的身份操作,权限永远不会超过你。它们可以使用与你相同作为角色,并会在你离开团队时停止工作。

团队所有者可以在团队设置 › API 密钥中设置密钥规则:密钥最长有效期、成员能否创建团队密钥,以及是否允许个人密钥。

创建、修改、轮换和撤销密钥都会显示在团队的活动记录中,因泄露而被撤销的密钥也一样。通过密钥或已连接应用执行的所有操作,都会在那里显示为“人员 通过 密钥或应用名称”。

保护好密钥

  • 密钥只在创建时显示一次。请当场复制,并作为机密妥善保存。
  • 要更换密钥,打开它并点击轮换。选择旧密钥还能继续工作多久(最长 7 天),这样你有时间更新所有使用它的地方。
  • 从密钥的菜单中撤销后,它会立即停止工作。

在密钥设置推出之前创建的密钥会照常工作,不受影响。它们在开发者页面中显示为“创建于密钥设置推出之前”,你可以在那里为它们添加限制,或用新密钥替换它们。

密钥错误

当密钥无法完成某个请求时,错误中会包含以下代码之一,错误消息会说明需要更改什么。

代码状态原因
invalid_key401密钥不存在。请检查是否完整复制。
key_expired401密钥已过期。
key_revoked401密钥已被撤销。
key_owner_left401个人密钥所代表的人已离开团队。
key_view_only403密钥为仅查看,而请求会修改内容。
role_not_allowed403密钥的角色无法查看或修改此内容。
ip_not_allowed403请求来自密钥不允许的 IP 地址。
page_not_allowed403密钥无法使用此项目。
account_action_not_allowed403密钥无法创建或删除页面、团队或工作区。请使用控制台。
route_not_allowed403该路由不属于已公开文档的 API。

获取你的页面 ID

按以下步骤可以在控制台中找到页面 ID:

  1. 进入你的控制台。
  2. 右键点击左上角的项目,打开菜单。
  3. 点击 Copy Project ID,页面 ID 就会复制到剪贴板。
页面 ID

错误

所有 API 端点的错误响应中都包含 code 和 message。

{
"error": {
"code": "forbidden",
"message": "Not authorized"
}
}

状态取值

可能的页面状态。这是当前 API(v2 及之后)返回的细粒度 status。旧的 summary.json 端点和 webhook 通知使用的是精简形式,只有 UP、HASISSUES 和 UNDERMAINTENANCE。

  • UP
  • HASISSUES
  • ALLUNDERMAINTENANCE
  • ALLDEGRADEDPERFORMANCE
  • ALLPARTIALOUTAGE
  • ALLMINOROUTAGE
  • ALLMAJOROUTAGE
  • SOMEUNDERMAINTENANCE
  • SOMEDEGRADEDPERFORMANCE
  • SOMEPARTIALOUTAGE
  • SOMEMINOROUTAGE
  • SOMEMAJOROUTAGE
  • ONEUNDERMAINTENANCE
  • ONEDEGRADEDPERFORMANCE
  • ONEPARTIALOUTAGE
  • ONEMINOROUTAGE
  • ONEMAJOROUTAGE

可能的组件状态:

  • OPERATIONAL
  • UNDERMAINTENANCE
  • DEGRADEDPERFORMANCE
  • PARTIALOUTAGE
  • MAJOROUTAGE

可能的事件状态:

  • INVESTIGATING
  • IDENTIFIED
  • MONITORING
  • RESOLVED

可能的维护状态:

  • NOTSTARTEDYET
  • INPROGRESS
  • COMPLETED

跳转到端点: