> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rootly.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Driving a Status Page from the API
> Create, update, and delete status page events programmatically with the Rootly API — post an update, revise it, and remove one posted in error.
## Overview
Incident updates can be posted to a status page through the API instead of the Rootly UI. This is how you drive a status page from a script, a deploy pipeline, or your own tooling — and how you post updates from a system that already knows something is wrong.
A status page update is a **status page event** attached to an incident. Five operations cover the whole lifecycle:
| Operation | Endpoint |
| - | - |
| Create an update | `POST /v1/incidents/{incident_id}/status-page-events` |
| List an incident's updates | `GET /v1/incidents/{incident_id}/status-page-events` |
| Read one update | `GET /v1/status-page-events/{id}` |
| Revise an update | `PUT /v1/status-page-events/{id}` |
| Remove an update | `DELETE /v1/status-page-events/{id}` |
Full request and response schemas for each are in the **API Reference** tab. This page covers the flows and the fields that decide what your customers see.
This is the write path, and it requires a Rootly API key. It is not the same as the read-only [Status Page Public API](/configuration/status-page-public-api), which serves current status on your status page's own domain with no key at all.
***
## Posting an Update
`POST /v1/incidents/{incident_id}/status-page-events` creates an update on an incident and publishes it to a status page.
```bash theme={null}
curl --request POST \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Bearer YOUR-API-KEY' \
--url https://api.rootly.com/v1/incidents/INCIDENT_ID/status-page-events \
--data '{
"data": {
"type": "incident_status_page_events",
"attributes": {
"event": "We are investigating elevated error rates on checkout.",
"status_page_id": "STATUS_PAGE_ID",
"status": "investigating",
"notify_subscribers": true
}
}
}'
```
### Fields
The text customers read. Required, along with `status_page_id`.
Which status page to publish to. A request without it is rejected. An organization with more than one page needs this to be right — there is no undo on a customer-facing post beyond deleting it afterwards.
Publish a private incident's updates only to a private status page. The API accepts a private incident's update on a public page.
`investigating`, `identified`, `monitoring`, `resolved`, `scheduled`, `in_progress`, or `completed`.
The first four describe an unplanned incident. The last three describe planned maintenance, and a scheduled maintenance accepts only those. Some organizations also have `planning`, `verifying`, and `cancelled` for maintenance, or can use their team's own lifecycle status names on an internal status page.
When omitted, `status` is saved as `investigating` without being checked against the incident's kind, so a scheduled maintenance posted without one shows on the page with an unplanned-incident status. Always set it.
Whether to notify subscribers about this update, by email, and by text message for incidents. Scheduled maintenance updates go by email only. **Defaults to `false`** — omit it and the update appears on the page silently. Updates on test and backfilled incidents never notify, whatever this is set to.
When the event started. Defaults to the time of creation.
**`notify_subscribers` defaults to `false`.** A script that posts updates without setting it produces a status page that looks current to anyone who visits and sends nothing to the people who asked to be told. Set it explicitly on every call, to `true` or `false`, so the choice is visible in the code rather than inherited from a default.
***
## Revising an Update
`PUT /v1/status-page-events/{id}` edits an update already published. Use it to correct a typo or sharpen wording — the update stays in place rather than being replaced by a new one.
```bash theme={null}
curl --request PUT \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Bearer YOUR-API-KEY' \
--url https://api.rootly.com/v1/status-page-events/EVENT_ID \
--data '{
"data": {
"type": "incident_status_page_events",
"attributes": {
"event": "We are investigating elevated error rates on checkout."
}
}
}'
```
Only the attributes you send are changed. The `id` in the body is accepted for JSON:API client compatibility but ignored — the update being changed is the one named in the path.
The example above fixes the wording of an update already posted, which is what `PUT` is for. Note that it does **not** send `status`: changing the status here rewrites history rather than advancing it. Subscribers are notified only when an update is created, so revising one notifies no one, even with `notify_subscribers: true`.
Revising is not the same as progressing an incident. To move from investigating to identified to resolved as a sequence customers can follow, post a **new** update at each stage. Editing the previous one erases the history of what you told them and when.
***
## Removing an Update
`DELETE /v1/status-page-events/{id}` removes an update from the status page.
```bash theme={null}
curl --request DELETE \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Bearer YOUR-API-KEY' \
--url https://api.rootly.com/v1/status-page-events/EVENT_ID
```
Deletion removes the update from the page. It does not unsend anything already delivered — subscribers who were notified keep the email, and anyone who read the page still read it. Treat deletion as tidying the record, not as a recall.
***
## A Worked Sequence
Driving one incident from first signal to all-clear is four calls, each a `POST`:
Post the first update as soon as you know customers are affected, with `status: "investigating"` and `notify_subscribers: true`. Say what is affected and that you are looking, not what caused it.
Post again with `status: "identified"` once you know the cause. A new update, not an edit of the first — subscribers get the progression.
Post with `status: "monitoring"` when the fix is out and you are watching. This is the update teams most often skip, and the one that stops customers from asking whether anyone is still there.
Post with `status: "resolved"` to close it out.
***
## Affected Components
The create endpoint accepts a `status_page_components` array, setting each affected component to `operational`, `degraded_performance`, `partial_outage`, or `major_outage`.
This field is in Early Access and is not generally available — contact Rootly Support to request access.
Each entry takes the component's ID and the status to record for it:
```json theme={null}
"status_page_components": [
{ "status_page_component_id": "COMPONENT_ID", "status": "partial_outage" },
{ "status_page_component_id": "ANOTHER_COMPONENT_ID", "status": "degraded_performance" }
]
```
Only `status_page_component_id` is required by the schema. Two behaviours to know if you use it: a status is required per component except on scheduled maintenance incidents, and it is ignored for terminal event statuses (`resolved`, `completed`), which clear component impact instead.
***
## Related Pages
Publishing status page updates from the Rootly UI and from Slack.
The read-only public JSON API served on your status page's own domain.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.