REST API
The Representational State Transfer (REST) Application Programming Interface (API) publishes status updates and opens or closes incidents. It cannot read data.
API keys
- A key belongs to one service and can only act on that service.
- ADMIN members create and revoke keys on the API Keys tab.
- The key is shown once, right after it is generated. Only a hash is stored.
- Keys do not expire. Revoke a key to stop it working.
Authentication
Send the key in either header:
Authorization: Bearer <key>
X-Api-Key: <key>
Endpoints
| Method and path | Purpose | Success |
|---|---|---|
POST /api/v1/services/{slug}/status |
Post a status update. | 201 |
POST /api/v1/services/{slug}/incidents |
Open an incident with its first update. | 201 |
PATCH /api/v1/incidents/{id}/close |
Close an incident. | 200 |
Status update body
{
"status": "DEGRADED",
"message": "Markdown text, up to 4096 characters",
"componentId": "optional UUID",
"incidentId": "optional UUID of an open incident"
}
status is one of OK, DEGRADED, CRITICAL, MONITORING, MAINTENANCE, OFFLINE, in any letter case.
Incident body
{
"title": "up to 256 characters",
"status": "CRITICAL",
"message": "up to 4096 characters",
"componentId": "optional UUID"
}
Here status must use the exact upper-case name.
Errors
Errors are RFC 7807 problem documents.
| Cause | Status code |
|---|---|
| Unknown service, incident or component | 404 |
| Invalid input, unknown status, closed incident, key for another service | 400 |
| Action not allowed | 403 |
Updates posted through the API trigger the same emails as updates posted in the back office.