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