Runstatus API
Connect your public status page to the rest of your stack
The Runstatus API will enable you to query your status page(s) and retrieve:
- current status of services
- post new incidents and maintenances
- update and resolve those
Public endpoint
Note that a public and unidentified endpoint is available at
https://[page_name].runstat.us/api.json
For example you can query Exoscale’s one at https://exoscale.runstat.us/api.json it provides the following output:
{
"upcoming_maintenances": [],
"status": {
"Compute API": {
"state": "operational"
},
"DNS": {
"state": "operational"
},
"Compute": {
"state": "operational"
},
"Apps": {
"state": "operational"
},
"Object Storage": {
"state": "operational"
}
},
"incidents": [],
"url": "https://status.exoscale.ch"
}
Authentication
The runstatus API requires authentication using API key and API secret that you can find on https://portal.exoscale.com/account/profile/api
Then each request is formed as such:
- Compute a signature: HMAC SHA256 of the UTF-8 encoded payload with the secret key
- Pass a header
Authorizationwith:Exoscale-HMAC-SHA256 [api key]:[signature] - Pass a header
Exoscale-Datewith the current UTC datetime in iso format, for example2017-02-02T15:18:46Z
The payload to sign is formatted as follow: <url><date><request body>. For posting a new incident, the payload to sign would be like:
https://api.runstatus.com/pages/mystatuspage/incidents2017-02-02T15:18:46Z{"services": ["API"], "title": "Connectivity issue", "status_text": "We are experiencing database connection glitches", "status": "investigating", "state": "degraded_performance"}
Pages
GET /pages
Description
Retrieves the list of pages that are manageable by this API and KEY
- 200 Ok: Return pages list
- 403 Forbidden: Not authorized or invalid signature
Request Parameters
Answer
{"next": null,
"previous": null,
"results": [{"created": "2015-10-21T17:34:41.953089Z",
"dark_theme": false,
"domain": null,
"gradient_end": "255,255,255,1",
"gradient_start": "224,224,224,1",
"header_background": null,
"id": 6,
"incidents_url": "https://api.runstatus.com/pages/mypage/incidents",
"logo": null,
"maintenances_url": "https://api.runstatus.com/pages/mypage/maintenances",
"ok_text": "All systems operational",
"plan": "free",
"public_url": "https://mypage.runstat.us",
"services_url": "https://api.runstatus.com/pages/mypage/services",
"state": "operational",
"subdomain": "mypage",
"support_email": "",
"time_zone": "UTC",
"title": "",
"title_color": "204,204,204,1",
"twitter_username": "",
"url": "https://api.runstatus.com/pages/mypage"},
{"created": "2016-02-08T09:11:52.896836Z",
"dark_theme": false,
"domain": null,
"gradient_end": "255,255,255,0.9",
"gradient_start": "224,224,224,0.9",
"header_background": null,
"id": 18,
"incidents_url": "https://api.runstatus.com/pages/team/incidents",
"logo": null,
"maintenances_url": "https://api.runstatus.com/pages/team/maintenances",
"ok_text": "All systems operational",
"plan": "free",
"public_url": "https://team.runstat.us",
"services_url": "https://api.runstatus.com/pages/team/services",
"state": "operational",
"subdomain": "team",
"support_email": "",
"time_zone": "UTC",
"title": "",
"title_color": "204,204,204,1",
"twitter_username": "",
"url": "https://api.runstatus.com/pages/team"},
{"created": "2015-11-13T09:12:54.727621Z",
"dark_theme": false,
"domain": null,
"gradient_end": "255,255,255,1",
"gradient_start": "224,224,224,1",
"header_background": null,
"id": 10,
"incidents_url": "https://api.runstatus.com/pages/api/incidents",
"logo": null,
"maintenances_url": "https://api.runstatus.com/pages/api/maintenances",
"ok_text": "All systems operational",
"plan": "free",
"public_url": "https://api.runstat.us",
"services_url": "https://api.runstatus.com/pages/api/services",
"state": "operational",
"subdomain": "api",
"support_email": "",
"time_zone": "UTC",
"title": "",
"title_color": "204,204,204,1",
"twitter_username": "",
"url": "https://api.runstatus.com/pages/api"}
]
}
POST /pages
Description
Creates a page.
- 201 Created: on a successful page creation;
- 403 Forbidden: Not authorized or invalid signature.
Request Parameters
| Parameter | Description | Required |
|---|---|---|
| name | The name of the new page to create. |
|
| subdomain | The subdomain for the url of the status page to create. |
Answer
{
"created": "2016-05-30T19:47:41.503608Z",
"dark_theme": false,
"domain": null,
"gradient_end": "255,255,255,0.9",
"gradient_start": "224,224,224,0.9",
"header_background": null,
"id": 341,
"incidents_url": "https://api.runstatus.com/pages/wickedservice/incidents",
"logo": null,
"maintenances_url": "https://api.runstatus.com/pages/wickedservice/maintenances",
"ok_text": "All systems operational",
"plan": "free",
"public_url": "https://wickedservice.runstat.us",
"services_url": "https://api.runstatus.com/pages/wickedservice/services",
"state": "operational",
"subdomain": "wickedservice",
"support_email": "",
"time_zone": "UTC",
"title": "",
"title_color": "204,204,204,1",
"twitter_username": "",
"url": "https://api.runstatus.com/pages/wickedservice"
}
DELETE /pages/[page_name]
Description
Deletes a status page.
- 204 No Content: on a successful page deletion.
Request Parameters
Answer
Services
POST /pages/[page_name]/services
Description
Creates a new service
- 201 on successful service creation
Request Parameters
| Parameter | Description | Required |
|---|---|---|
| name | The name of the new service to create. |
Answer
GET /pages/[page_name]/services
Description
Displays the list of services
Request Parameters
Answer
{
"previous": null,
"next": null,
"results": [
{
"url": "https://api.runstatus.com/pages/mypage/services/437",
"name": "alarm",
"state": "operational"
},
{
"url": "https://api.runstatus.com/pages/mypage/services/435",
"name": "vault",
"state": "operational"
},
{
"url": "https://api.runstatus.com/pages/mypage/services/436",
"name": "weather station",
"state": "operational"
}
]
}
`previous` and `next` are pagination links.
GET /pages/[page_name]/services/[service_id]
Description
Displays service detail
Request Parameters
Answer
{
"name": "alarm",
"state": "operational",
"url": "https://api.runstatus.com/pages/mypage/services/437"
}
DELETE /pages/[page_name]/services/[service_id]
Description
Deletes a service
- 204 No Content: on successful deletion
Request Parameters
Answer
Incidents
POST /pages/[page_name]/incidents
Description
Creates an incident.
- 201 Created: on a successful incident creation;
- 400 Bad Request: on a validation failure.
Request Parameters
| Parameter | Description | Required |
|---|---|---|
| services | List of strings with the services impacted. |
|
| title | Title of the incident. |
|
| status_text | Description for the initial creation event. |
|
| status | The target status for the incident from |
|
| state | The target state for the services impacted from |
Answer
GET /pages/[page_name]/incidents
Description
Lists the incidents for a specific page.
Request Parameters
Answer
{
"next": null,
"previous": null,
"results": [
{"end_date": null,
"events": [
{"created": "2016-05-31T21:11:32.378267Z",
"state": "degraded_performance",
"status": "investigating",
"text": "It is raining, the corridor is wet, "
"walk slowly! Looking for the root "
"cause."}],
"events_url": "https://api.runstatus.com/pages/mypage/incidents/135/events",
"id": 135,
"post_mortem": "",
"real_time": true,
"services": ["weather station"],
"start_date": "2016-05-31T21:11:32.378Z",
"state": "degraded_performance",
"status": "investigating",
"status_text": "It is raining, the corridor is wet, walk slowly! Looking for the root cause.",
"title": "rain",
"url": "https://api.runstatus.com/pages/mypage/incidents/135"}
]
}
`previous` and `next` are pagination links.
GET /pages/[page_name]/incidents/[incident_id]
Description
Retrieves the details of a specific incident.
Request Parameters
Answer
{
"end_date": null,
"events": [
{"created": "2016-05-31T21:11:32.378267Z",
"state": "degraded_performance",
"status": "investigating",
"text": "It is raining, the corridor is wet, "
"walk slowly! Looking for the root "
"cause."}],
"events_url": "https://api.runstatus.com/pages/mypage/incidents/135/events",
"id": 135,
"post_mortem": "",
"real_time": true,
"services": ["weather station"],
"start_date": "2016-05-31T21:11:32.378Z",
"state": "degraded_performance",
"status": "investigating",
"status_text": "It is raining, the corridor is wet, walk "
"slowly! Looking for the root cause.",
"title": "rain",
"url": "https://api.runstatus.com/pages/mypage/incidents/135"
}
POST /pages/[page_name]/incidents/[incident_id]/events
Description
Adds an event to an existing incident.
This is also used to close an incident, passing a
resolved status and flagging the services state
as operational.
Request Parameters
| Parameter | Description | Required |
|---|---|---|
| text | Description for the event. |
|
| status | The target status for the incident from |
|
| state | The target state for the services impacted from |
Answer
DELETE /pages/[page_name]/incidents/[incident_id]
Description
Deletes an incident. Not recommended, only for extreme measures. Normal process is to post an update and close the incident.
- 204 No Content: incident was deleted
Request Parameters
Answer
Maintenances
POST /pages/[page_name]/maintenances
Description
Creates a maintenance notice for the selected services.
Request Parameters
| Parameter | Description | Required |
|---|---|---|
| title | Title for the maintenance. |
|
| description | Description for the maintenance. |
|
| start_date | The planned start date for the maintenance, in UTC format e.g. 2016-05-31T21:11:32.378Z. |
|
| end_date | The expected end date for the maintenance. |
|
| services | The list of services affected by the maintenance. |
Answer
POST /pages/[page_name]/maintenances/[maintenance_id]/events
Description
Adds a event to a maintenance. Events can be updates or final message with status completed.
Request Parameters
| Parameter | Description | Required |
|---|---|---|
| status | The maintenance status is |
|
| description | Description for the maintenance. |
Answer
GET /pages/[page_name]/maintenances
Description
Returns the list of maintenances for the page.
Request Parameters
Answer
{
"previous": null,
"next": null,
"results":
[{"created": "2016-06-10T06:42:54.382163Z",
"description": "The grass is too high, lawn is going to "
"get mowed. The lawn will not be "
"available for games during the period.",
"end_date": "2016-06-11T06:40:05.805000Z",
"events": [],
"events_url": "https://api.runstatus.com/pages/mypage/maintenances/71/events",
"real_time": true,
"services": ["outdoor"],
"start_date": "2016-06-10T06:40:05.800000Z",
"status": "scheduled",
"title": "Lawn mowing",
"url": "https://api.runstatus.com/pages/mypage/maintenances/71"}
]
}
`previous` and `next` are pagination links.
GET /pages/[page_name]/maintenances/[maintenance_id]
Description
Retrieves the details of a specific maintenance.
Request Parameters
Answer
{
"created": "2016-06-10T06:42:54.382163Z",
"description": "The grass is too high, lawn is going to "
"get mowed. The lawn will not be "
"available for games during the period.",
"end_date": "2016-06-11T06:40:05.805000Z",
"events": [],
"events_url": "https://api.runstatus.com/pages/mypage/maintenances/71/events",
"real_time": true,
"services": ["outdoor"],
"start_date": "2016-06-10T06:40:05.800000Z",
"status": "scheduled",
"title": "Lawn mowing",
"url": "https://api.runstatus.com/pages/mypage/maintenances/71"
}