Status page APIs

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.

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.

The Widget API toggle in status page settings, switched off, with a Save button

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.

Endpoint

Send a GET request to your status page URL with /api/v1/summary appended:

https://status.example.com/api/v1/summary

The endpoint is unauthenticated and publicly accessible on the internet. You can copy the exact URL from the Widget API settings page. If the widget API is disabled, the endpoint returns a 404.

Response structure

The response contains three arrays, so you can tell the different types of event apart:

ongoing_incidents: incidents that are investigating, identified or monitoring
in_progress_maintenances: maintenance windows that are in progress
scheduled_maintenances: maintenance windows that haven’t started yet

Each array is empty when there’s nothing to show. Here’s an example response:

{
  "page_title": "Example",
  "page_url": "https://status.example.com",
  "ongoing_incidents": [
    {
      "id": "01H0QJ89CRW5BKTY9N89MSDT5S",
      "name": "Login failing for some users",
      "status": "identified",
      "url": "https://status.example.com/incidents/01H0QJ89CRW5BKTY9N89MSDT5S",
      "last_update_at": "2026-10-26T09:00:00Z",
      "last_update_message": "We've identified the cause and are rolling out a fix.",
      "current_worst_impact": "partial_outage",
      "affected_components": [
        {
          "id": "01H0QJ1BXP0E76RGBYRDHKA2KQ",
          "name": "Login",
          "group_name": "Authentication",
          "current_status": "partial_outage"
        }
      ]
    }
  ],
  "in_progress_maintenances": [
    {
      "id": "01FDAG4SAP5TYPT98WGR2N7W91",
      "name": "Database upgrade",
      "status": "maintenance_in_progress",
      "url": "https://status.example.com/incidents/01FDAG4SAP5TYPT98WGR2N7W91",
      "last_update_at": "2026-10-26T08:00:00Z",
      "last_update_message": "Maintenance has started.",
      "affected_components": [
        {
          "id": "01FDAG3W4H5WRT0QE6WAEEQ1C2",
          "name": "API",
          "current_status": "under_maintenance"
        }
      ],
      "started_at": "2026-10-26T08:00:00Z",
      "scheduled_end_at": "2026-10-26T10:00:00Z"
    }
  ],
  "scheduled_maintenances": [
    {
      "id": "01FCNDV6P870EA6S7TK1DSYD5H",
      "name": "Essential maintenance",
      "status": "maintenance_scheduled",
      "url": "https://status.example.com/incidents/01FCNDV6P870EA6S7TK1DSYD5H",
      "last_update_at": "2026-10-25T12:00:00Z",
      "last_update_message": "We're upgrading our network hardware.",
      "affected_components": [],
      "starts_at": "2026-10-28T02:00:00Z",
      "ends_at": "2026-10-28T04:00:00Z"
    }
  ]
}

Fields

string

The name of your status page.

string

The canonical URL of your status page. This is your custom domain if you’ve set one, whichever URL you fetched the summary from.

string

The status of the incident or maintenance window.

Ongoing incidents: investigating, identified or monitoring
In-progress maintenance: maintenance_in_progress
Scheduled maintenance: maintenance_scheduled

string

The worst current impact across the incident’s components. One of operational, degraded_performance, partial_outage or full_outage. Only present on ongoing incidents.An incident can be ongoing with a current_worst_impact of operational. This usually happens in the monitoring stage, after the affected components have recovered.

array

The components affected by the incident or maintenance window. Each component has an id, a name and a current_status. The group_name field is only included when the component belongs to a group. Otherwise it’s left out, rather than set to null.current_status is one of operational, degraded_performance, partial_outage, full_outage or under_maintenance.

string

The time and text of the most recent published update. Incidents and maintenance windows without a published update aren’t included in the response.

string

When an in-progress maintenance window started and when it’s scheduled to end.

string

When a scheduled maintenance window will start and end.

All timestamps are in ISO 8601 format, in UTC. You can use the affected components to decide where to show a banner. For example, if an incident affects your “Login” component, show the banner on your login page only.

What the response includes

The widget API only shows what’s happening now. As soon as you resolve an incident or complete a maintenance window, it drops out of the response. To show past incidents, link to your status page instead.

Status pages with sub-pages

For a parent status page, the response returns a subpages array. Each entry has the sub-page’s subpage slug and a summary object with the structure above. To fetch a single sub-page, add its slug before /api/v1/summary:

https://status.example.com/europe/api/v1/summary

Caching

We cache the response at our CDN for 30 seconds, so polling more often than that returns the same data. The response doesn’t set a max-age for browsers, so add your own caching if you call it from your backend. Polling every 30 to 60 seconds works well for most use cases.

FAQs

Can I automate status page incidents or maintenance windows using an API?

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.

Can I create maintenance windows through the API?

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.

Do you have a read-only status page API?

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.

Getting started

Alerts

On-call

Incident response

Post-incident

Status pages

Nexus

Investigations

AI features

Workflows

Insights

Integrations

Administration

Need more help?

Status Page API

Prerequisites

Status page incidents

Status page maintenance windows

Widget API

Endpoint

Response structure

Fields

What the response includes

Status pages with sub-pages

Caching

FAQs

​Status Page API

​Prerequisites

​Status page incidents

​Status page maintenance windows

​Widget API

​Endpoint

​Response structure

​Fields

​What the response includes

​Status pages with sub-pages

​Caching

​FAQs

​Related resources

Status Page API

Prerequisites

Status page incidents

Status page maintenance windows

Widget API

Endpoint

Response structure

Fields

What the response includes

Status pages with sub-pages

Caching

FAQs

Related resources