开始使用 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_key | 401 | 密钥不存在。请检查是否完整复制。 |
key_expired | 401 | 密钥已过期。 |
key_revoked | 401 | 密钥已被撤销。 |
key_owner_left | 401 | 个人密钥所代表的人已离开团队。 |
key_view_only | 403 | 密钥为仅查看,而请求会修改内容。 |
role_not_allowed | 403 | 密钥的角色无法查看或修改此内容。 |
ip_not_allowed | 403 | 请求来自密钥不允许的 IP 地址。 |
page_not_allowed | 403 | 密钥无法使用此项目。 |
account_action_not_allowed | 403 | 密钥无法创建或删除页面、团队或工作区。请使用控制台。 |
route_not_allowed | 403 | 该路由不属于已公开文档的 API。 |
获取你的页面 ID
按以下步骤可以在控制台中找到页面 ID:
- 进入你的控制台。
- 右键点击左上角的项目,打开菜单。
- 点击 Copy Project ID,页面 ID 就会复制到剪贴板。

错误
所有 API 端点的错误响应中都包含 code 和 message。
{"error": {"code": "forbidden","message": "Not authorized"}}
状态取值
可能的页面状态。这是当前 API(v2 及之后)返回的细粒度 status。旧的 summary.json 端点和 webhook 通知使用的是精简形式,只有 UP、HASISSUES 和 UNDERMAINTENANCE。
UPHASISSUESALLUNDERMAINTENANCEALLDEGRADEDPERFORMANCEALLPARTIALOUTAGEALLMINOROUTAGEALLMAJOROUTAGESOMEUNDERMAINTENANCESOMEDEGRADEDPERFORMANCESOMEPARTIALOUTAGESOMEMINOROUTAGESOMEMAJOROUTAGEONEUNDERMAINTENANCEONEDEGRADEDPERFORMANCEONEPARTIALOUTAGEONEMINOROUTAGEONEMAJOROUTAGE
可能的组件状态:
OPERATIONALUNDERMAINTENANCEDEGRADEDPERFORMANCEPARTIALOUTAGEMAJOROUTAGE
可能的事件状态:
INVESTIGATINGIDENTIFIEDMONITORINGRESOLVED
可能的维护状态:
NOTSTARTEDYETINPROGRESSCOMPLETED