> ## Documentation Index
> Fetch the complete documentation index at: https://docs.incident.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Status page APIs
> Automate status page incidents, maintenance windows, and embed status data in your product.
incident.io provides two APIs for status pages: the **[Status Page API](#status-page-api)** for programmatically managing incidents and maintenance windows, and the **[Widget API](#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](https://docs.incident.io/api-reference/status-pages-v2/).
### 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](/status-pages/auto-publishing) 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**.
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](#status-page-api) to programmatically declare incidents, publish updates, resolve
incidents, schedule maintenance windows, and mark maintenance as complete. See the [API
docs](https://docs.incident.io/api-reference/status-pages-v2/) for endpoint details.
Yes — you can create and manage maintenance windows using the [Status Page API](#status-page-maintenance-windows).
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](#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](#status-page-api).
## Related resources
* [Status Page API docs](https://docs.incident.io/api-reference/status-pages-v2/)
* [Automatically publishing via workflows](/status-pages/auto-publishing)