Skip to main content
Using the status pages API, you can programmatically update your status page to make your customers aware of problems immediately or to schedule routine maintenance windows in advance. This article describes how to set up automated Status page incidents and Status page maintenance windows. The approach via the API mirrors the steps in the incident.io dashboard.
The status pages API is for public and customer status pages only.

​
Prerequisites

This article assumes you already have a status page up and running. To use the API, you will need have created an API key with the required scopes. For read-only access (listing status pages, viewing structure, incidents, and maintenance windows), any valid API key will work. For write requests (creating incidents, maintenance windows, and publishing updates), you will need an API key with the “Create status page incidents, maintenance windows and publish updates” scope. You can create an API key in the incident.io dashboard.
API docsYou can find details of all endpoints in the Status Page V2 API docs.

​
Status page incidents

  1. Creating a status page incident
To declare a status page incident, you use the CreateStatusPageIncident endpoint.
  • You will need the ID of your status page. This can be found using the ListStatusPages endpoint, which lists your status pages by name and ID.
  • You will need to set an initial incident_status for the incident, give it a name and provide a message which will be used for publishing that initial update.
  • Optionally, you can specify which components the incident has affected by providing their component_statuses. You will need the IDs of the components, which you can find using the ShowStatusPageStructure endpoint once you’ve already found out your page’s ID.
  • You’re also required to provide a unique idempotency_key for the incident and whether to notify_subscribers to your status page.
  1. Publishing an update on a status page incident
Once you’ve declared the status page incident, you can publish updates on the progress of the incident using the UpdateStatusPageIncident endpoint.
  • You can update the incident_status and/or component_statuses, and provide a new message to your viewers and subscribers.
  1. Resolving a status page incident
To resolve a status page incident, you again use the UpdateStatusPageIncident endpoint, setting the incident_status to "resolved". Any components affected by the incident will be reset to "operational" (within that incident).
  1. Updating the status page incident’s name (optional)
During a status page incident, you may wish to update the incident’s name, for instance because its nature has changed and its original name is outdated. You can do this using the UpdateStatusPageIncident endpoint described in the API docs.

​
Status page maintenance windows

Status page maintenance windows are similar to status page incidents, so this focuses on the important differences and features.
  1. Scheduling a status page maintenance window
To schedule a status page maintenance window, you use the CreateStatusPageMaintenance endpoint.
  • Unlike with status page incidents, you will need to provide a start_at and end_at when scheduling maintenance.
  • You supply a maintenance_status rather than an incident_status.
  • Optionally, you provide a list of the IDs of components affected by the maintenance.
  1. Publishing an update on a status page maintenance window
To publish a status update on a maintenance window, you use the CreateStatusPageMaintenanceUpdate endpoint. In the incident.io dashboard, you can choose to manually or automatically update the status of a maintenance window. The API uses the manual status updates approach: you must publish updates in order to update the maintenance window’s status, and move it from e.g. "maintenance_scheduled" to "maintenance_in_progress".
  1. Completing a status page maintenance window
When the maintenance is complete, you again use the CreateStatusPageMaintenanceUpdate endpoint to publish a final update, this time setting the maintenance_status to "maintenance_complete".

​
Further reading

For detailed information, turn to the Status Page V2 API docs. You might also find the following article useful, if you’re looking to automate status page updates from incidents in the Response product: Automatically publishing to your status page via workflows