開始使用 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

直接前往端點: