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, 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.

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

event · string · required

The text customers read. Required, along with status_page_id.

status_page_id · string · required

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.

status · enum · default: "investigating"

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.

notify_subscribers · boolean · default: "false"

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.

started_at · date-time

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.

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.

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:

1. Investigating

   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.

2. Identified

   Post again with status: "identified" once you know the cause. A new update, not an edit of the first — subscribers get the progression.

3. Monitoring

   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.

4. Resolved

   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:

"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 Incidents

Publishing status page updates from the Rootly UI and from Slack.

Status Page Public API

The read-only public JSON API served on your status page’s own domain.