A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Statuspage API is how an app or AI agent runs a status page: opening and updating incidents, flipping a component to a degraded or operational status, adding metric data points, and managing the subscribers who get notified. Access is granted through an organization API key that is admin-level and page-scoped, so a valid key can read and write everything across the pages its organization owns, with no read-only or per-endpoint permission to narrow it. There is no version header to pin, and a webhook subscriber can receive incident updates instead of polling.
How an app or AI agent connects to Statuspage determines what it can reach. The Manage API makes authenticated calls with an API key, while a separate public Status API reads a page's current state without a key.
The Manage API answers at api.statuspage.io under the v1 path. It is authenticated with an organization API key and lets an app create and update incidents, components, subscribers, and metrics.
The public Status API reads a page's current status, components, and incidents for embedding elsewhere. It needs no key for a public page, and is not rate limited.
A webhook subscriber registers a receiver URL on a page. Statuspage posts the incident payload to that URL when an incident is created or updated, so an integration learns of changes without polling.
The Manage API authenticates with an organization API key sent in the Authorization header as 'OAuth {key}', or as an api_key query parameter. The key is admin-level and page-scoped, with no read-only variant and no per-endpoint scopes.
The Statuspage API is split into areas an agent can act on, like incidents, components, subscribers, and metrics. Each area has its own methods, and writes here change what visitors see on a public status page.
List, read, create, update, and delete incidents, including filtered views of unresolved, scheduled, and upcoming incidents, and edit a past incident update.
Read, create or publish, and delete the postmortem attached to an incident.
List, read, create, update, and delete the components whose status the page reports.
List, read, create, update, and delete the groups that organize components on the page.
List, read, create, update, and unsubscribe the people and endpoints that receive incident notifications, and read counts by type.
List and read metrics, update and delete a metric, add data points to a metric, and reset a metric's data.
List the status pages on the account, read a single page, and update its settings.
Read and update the configuration for the status embed widget shown on external sites.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
IncidentsList, read, create, update, and delete incidents, including filtered views of unresolved, scheduled, and upcoming incidents, and edit a past incident update.8 | ||||||
| GET | /pages/{page_id}/incidents | Get a list of incidents on a page. | read | — | Current | |
The Manage API key is page-scoped and admin-level, with no read-only or per-endpoint scope, so any valid key can read this. Acts onincident Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /pages/{page_id}/incidents/unresolved | Get a list of unresolved incidents on a page. | read | — | Current | |
Returns incidents that are not yet resolved. The Manage API key carries no per-endpoint scope. Acts onincident Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /pages/{page_id}/incidents/scheduled | Get a list of scheduled incidents (planned maintenance) on a page. | read | — | Current | |
Scheduled incidents are the planned-maintenance flavor. The Manage API key carries no per-endpoint scope. Acts onincident Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /pages/{page_id}/incidents/{incident_id} | Get a single incident. | read | — | Current | |
The Manage API key carries no per-endpoint scope. Acts onincident Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /pages/{page_id}/incidents | Create an incident, optionally with an initial update and affected components. | write | — | Current | |
Creating an incident publishes it to the page and can notify subscribers. The Manage API key carries no per-endpoint scope. Acts onincident Permission (capability)None required VersionAvailable since the API’s base version Webhook event incident.updateRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /pages/{page_id}/incidents/{incident_id} | Update an incident, adding a new update or changing its status and affected components. | write | — | Current | |
Posting a new incident update can notify subscribers. The Manage API key carries no per-endpoint scope. Acts onincident Permission (capability)None required VersionAvailable since the API’s base version Webhook event incident.updateRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /pages/{page_id}/incidents/{incident_id} | Delete an incident. | write | — | Current | |
Deletion removes the incident and its history from the page. The Manage API key carries no per-endpoint scope. Acts onincident Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /pages/{page_id}/incidents/{incident_id}/incident_updates/{incident_update_id} | Update the wording or display time of a previous incident update. | write | — | Current | |
Edits a single past update without creating a new one. The Manage API key carries no per-endpoint scope. Acts onincident update Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PostmortemsRead, create or publish, and delete the postmortem attached to an incident.3 | ||||||
| GET | /pages/{page_id}/incidents/{incident_id}/postmortem | Get the postmortem for an incident. | read | — | Current | |
The Manage API key carries no per-endpoint scope. Acts onpostmortem Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /pages/{page_id}/incidents/{incident_id}/postmortem | Create or publish a postmortem for an incident. | write | — | Current | |
Publishing makes the postmortem visible and can notify subscribers. The Manage API key carries no per-endpoint scope. Acts onpostmortem Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /pages/{page_id}/incidents/{incident_id}/postmortem | Delete the postmortem for an incident. | write | — | Current | |
The Manage API key carries no per-endpoint scope. Acts onpostmortem Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ComponentsList, read, create, update, and delete the components whose status the page reports.5 | ||||||
| GET | /pages/{page_id}/components | Get a list of components on a page. | read | — | Current | |
An unpaginated list of components is limited to one request per minute. The Manage API key carries no per-endpoint scope. Acts oncomponent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit1 request per minute (unpaginated) SourceOfficial documentation ↗ | ||||||
| GET | /pages/{page_id}/components/{component_id} | Get a single component. | read | — | Current | |
The Manage API key carries no per-endpoint scope. Acts oncomponent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /pages/{page_id}/components | Create a component on a page. | write | — | Current | |
The Manage API key carries no per-endpoint scope. Acts oncomponent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /pages/{page_id}/components/{component_id} | Update a component, including its operational status. | write | — | Current | |
Changing the status field here moves the component between states such as operational and major_outage. The Manage API key carries no per-endpoint scope. Acts oncomponent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /pages/{page_id}/components/{component_id} | Delete a component. | write | — | Current | |
The Manage API key carries no per-endpoint scope. Acts oncomponent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Component groupsList, read, create, update, and delete the groups that organize components on the page.4 | ||||||
| GET | /pages/{page_id}/component-groups | Get a list of component groups on a page. | read | — | Current | |
The Manage API key carries no per-endpoint scope. Acts oncomponent group Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /pages/{page_id}/component-groups/{id} | Get a single component group. | read | — | Current | |
The Manage API key carries no per-endpoint scope. Acts oncomponent group Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /pages/{page_id}/component-groups | Create a component group. | write | — | Current | |
The Manage API key carries no per-endpoint scope. Acts oncomponent group Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /pages/{page_id}/component-groups/{id} | Update a component group. | write | — | Current | |
The Manage API key carries no per-endpoint scope. Acts oncomponent group Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SubscribersList, read, create, update, and unsubscribe the people and endpoints that receive incident notifications, and read counts by type.6 | ||||||
| GET | /pages/{page_id}/subscribers | Get a list of subscribers on a page. | read | — | Current | |
Returns subscriber contact details such as email addresses or phone numbers. The Manage API key carries no per-endpoint scope. Acts onsubscriber Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /pages/{page_id}/subscribers/{subscriber_id} | Get a single subscriber. | read | — | Current | |
Returns the subscriber's contact details. The Manage API key carries no per-endpoint scope. Acts onsubscriber Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /pages/{page_id}/subscribers | Create a subscriber by email, SMS, Slack, Microsoft Teams, or webhook. | write | — | Current | |
A webhook subscriber registers a receiver URL that Statuspage posts incident updates to. The Manage API key carries no per-endpoint scope. Acts onsubscriber Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /pages/{page_id}/subscribers/{subscriber_id} | Update a subscriber's settings, such as which components they follow. | write | — | Current | |
The Manage API key carries no per-endpoint scope. Acts onsubscriber Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /pages/{page_id}/subscribers/{subscriber_id} | Unsubscribe a subscriber. | write | — | Current | |
Removes the subscriber so they stop receiving notifications. The Manage API key carries no per-endpoint scope. Acts onsubscriber Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /pages/{page_id}/subscribers/count_by_type | Get a count of subscribers grouped by type. | read | — | Current | |
Counts subscribers by channel, such as email, SMS, or webhook. The Manage API key carries no per-endpoint scope. Acts onsubscriber Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Metrics & data pointsList and read metrics, update and delete a metric, add data points to a metric, and reset a metric's data.5 | ||||||
| GET | /pages/{page_id}/metrics | Get a list of metrics on a page. | read | — | Current | |
The Manage API key carries no per-endpoint scope. Acts onmetric Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /pages/{page_id}/metrics/{metric_id} | Get a single metric. | read | — | Current | |
The Manage API key carries no per-endpoint scope. Acts onmetric Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /pages/{page_id}/metrics/{metric_id}/data | Add a data point to a metric. | write | — | Current | |
Adds a timestamped value to the metric's chart on the page. The Manage API key carries no per-endpoint scope. Acts onmetric data point Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /pages/{page_id}/metrics/{metric_id}/data | Reset (clear) all data for a metric. | write | — | Current | |
Clears the metric's recorded data points. The Manage API key carries no per-endpoint scope. Acts onmetric data point Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /pages/{page_id}/metrics/{metric_id} | Update a metric's settings. | write | — | Current | |
The Manage API key carries no per-endpoint scope. Acts onmetric Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PagesList the status pages on the account, read a single page, and update its settings.3 | ||||||
| GET | /pages | Get a list of the status pages on the account. | read | — | Current | |
Lists every page the key's organization can reach. The Manage API key carries no per-endpoint scope. Acts onpage Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /pages/{page_id} | Get a single status page. | read | — | Current | |
The Manage API key carries no per-endpoint scope. Acts onpage Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /pages/{page_id} | Update a status page's settings. | write | — | Current | |
Changes page-wide settings such as name, domain, and appearance. The Manage API key carries no per-endpoint scope. Acts onpage Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Status embedRead and update the configuration for the status embed widget shown on external sites.2 | ||||||
| GET | /pages/{page_id}/status_embed_config | Get the status embed widget configuration. | read | — | Current | |
The Manage API key carries no per-endpoint scope. Acts onstatus embed config Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /pages/{page_id}/status_embed_config | Update the status embed widget configuration. | write | — | Current | |
Changes how the embedded status widget looks on external sites. The Manage API key carries no per-endpoint scope. Acts onstatus embed config Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Statuspage can notify a subscriber when an incident is created or updated, instead of that subscriber polling the page. A webhook subscriber registers a receiver URL, and Statuspage posts the incident payload to it each time the incident changes.
| Event | What it signals | Triggered by |
|---|---|---|
incident notification | Statuspage posts an incident payload to a webhook subscriber's receiver URL when an incident is created and each time it is updated, so the subscriber tracks the incident without polling. | /pages/{page_id}/incidents/pages/{page_id}/incidents/{incident_id} |
Statuspage limits how fast an app or AI agent can call the Manage API, through a per-key request rate measured over a rolling window. The public Status API is not rate limited.
The Manage API limits each API key to a request rate measured over a rolling 60-second window, documented as one request per second, which works out to 60 requests per minute. Some unpaginated list calls, such as listing components and listing page access users, are held to one request per minute. Going over returns a 420 or a 429. The public Status API is not rate limited.
List endpoints page through the page and per_page query parameters, where per_page defaults to 100. To stay inside the per-minute cap on unpaginated component lists, paginated requests should be used for large pages.
Requests and responses are JSON, and a request body may be sent form url-encoded or as JSON as long as the Content-Type header matches. There is no separately documented payload size limit.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | The API key is missing or invalid. | Send a valid key in the Authorization header as 'OAuth {key}'. |
| 403 | Forbidden | The key is valid but not permitted to act on this page or resource. | Use a key whose organization owns the page being called. |
| 404 | Not Found | The page or resource in the path does not exist or is not visible to the key. | Confirm the page_id and resource id are correct. |
| 422 | Unprocessable Entity | The request was well-formed but a field is missing or invalid. The body carries an error and message describing the problem. | Read the message, correct the named field, and resend. |
| 420 | Rate Limited | The per-key rate limit was exceeded. Statuspage returns 420 or 429 when too many requests are made. | Slow down to within one request per second and retry. |
| 429 | Too Many Requests | The per-key rate limit was exceeded. | Wait until the rolling window clears, then retry. |
Statuspage carries one version of its Manage API in the path, v1, and does not use dated version strings. Changes ship in place against that single version.
The Manage API is served under the v1 path at api.statuspage.io and is the current and only supported version. It authenticates with an organization API key, covers incidents, components, component groups, subscribers, metrics, pages, and the status embed, and ships changes in place rather than minting dated versions. An older v0 existed before v1 and is no longer the documented version.
An earlier v0 of the Statuspage API existed before v1. It has been superseded by the v1 Manage API, which is the version documented at developer.statuspage.io.
An integration calls the single v1 Manage API; there is no version header to pin.
Statuspage API reference ↗Bollard AI sits between a team's AI agents and Statuspage. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.