Skip to main content
incident.io provides two APIs for status pages: the Status Page API for programmatically managing incidents and maintenance windows, and the Widget API for embedding status data into your own product.
Both APIs are for public and customer status pages only. Internal status pages do not support API access.

​
Status Page API

Using the Status Page API, you can programmatically update your status page to make your customers aware of problems immediately or to schedule routine maintenance windows in advance. The approach via the API mirrors the steps in the incident.io dashboard.

​
Prerequisites

To use the API, you need 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 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.
You can find details of all endpoints in the Status Page API docs.

​
Status page incidents

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.
Publishing an update 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.
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). Updating the incident 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. Scheduling a 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.
Publishing an update 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". Completing a 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".
If you’re looking to automate status page updates triggered by incidents in the Response product, you may find publishing via workflows more suited to your needs.

​
Widget API

The status page widget API is a read-only JSON API that reflects the current content of your status page. Use it to embed status information directly into your own product — for example, displaying a banner at the top of your web page or a pop-up in your mobile app. The widget API updates whenever you update your status page, and is a direct reflection of the data shown there. To enable the widget API, go to your status page in the dashboard, then Settings, then Widget API. CleanShot+2024-11-24+at+20_36_27%402x.png
Although the widget API can be called directly from a web app, we strongly recommend proxying it through your own backend with some level of caching. The response itself is highly cacheable. If we notice high levels of traffic for your status page, we will reach out to discuss this.

​
Response structure

You can see a preview of the full JSON response from within the Widget API settings page. It contains three arrays — ongoing_incidents, in_progress_maintenances and scheduled_maintenances, allowing you to distinguish between those three different types of event. Each incident in those arrays will have dates associated with it. Each incident also has an ID, name, status, the last update message, and several other fields. It also contains affected components. By implementing your own logic, you can use these components to decide (for example) whether to show a banner on a certain page or not. For example, if the incident contains “Login” as an affected component, your login page can filter on that.

​
Authentication

The endpoint is unauthenticated and publicly accessible on the internet. You can see the URL from within the Widget API settings page.

​
FAQs

Yes — use the Status Page API to programmatically declare incidents, publish updates, resolve incidents, schedule maintenance windows, and mark maintenance as complete. See the API docs for endpoint details.
Yes — you can create and manage maintenance windows using the Status Page API. This allows you to schedule maintenance, publish updates, and mark maintenance as complete, all programmatically. Note that maintenance windows are only available on public and customer status pages.
Yes — the Widget API allows you to retrieve information about ongoing incidents and scheduled maintenance. It works regardless of whether your status page is live or not. The Widget API is read-only — to create or update incidents, use the Status Page API.