---
title: "Status Page Rules"
description: "Couple Incident Management to your status pages: rules that flip a page to warning or degraded on incidents of a team, plus a manual override."
---

`GET /api/im/statuspage-rules` · `POST /api/im/statuspage-rules` · `PATCH /api/im/statuspage-rules/:id` · `DELETE /api/im/statuspage-rules/:id` · `POST /api/im/statuspage-rules/override` · `DELETE /api/im/statuspage-rules/override/:statusPageId`

A **status page rule** reads: "incidents of team X at severity `minSeverity` or worse set status page Y to `targetState`". `sev1` is the most severe. With `autoResolve`, the page state is reset when the incident resolves. A **manual override** pins a state on a status page by hand. While a manual override is active, rules neither change nor clear that page.

## Authentication

Requires the base IM access every endpoint in this API needs (an IM-eligible role `admin`, `editor` or `responder`, or an organization-wide API token; Incident Management must be enabled for the organization). Listing rules is open to any IM-eligible role.

- **Creating, updating and deleting rules** require the write bar: your role must be `admin`, or you must be a team admin of the rule's team.
- **Setting or clearing a manual override** requires the `admin` or `editor` role, the same bar as other status page changes.

An organization-wide API token runs with the role of the user who created it. Team-admin membership never applies to a token.

## List rules

`GET /api/im/statuspage-rules`

Returns all rules of your organization, ordered by `id`.

### Example (cURL)

```bash
curl -X GET "$BASE_URL/api/im/statuspage-rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

### Response

`200 OK`

```json
[
  {
    "id": 2,
    "organizationId": 1,
    "teamId": 3,
    "statusPageId": 15,
    "minSeverity": "sev2",
    "targetState": "degraded",
    "autoResolve": true,
    "createdAt": "2026-09-25T09:00:00.000Z",
    "updatedAt": "2026-09-25T09:00:00.000Z"
  }
]
```

## Create a rule

`POST /api/im/statuspage-rules`

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `teamId` | integer | Yes | Team of your organization whose incidents trigger the rule. You need the write bar on it. |
| `statusPageId` | integer | Yes | Status page of your organization. |
| `minSeverity` | string | No | `sev1` to `sev4`, default `sev2`. |
| `targetState` | string | No | `warning` or `degraded` (default). |
| `autoResolve` | boolean | No | Reset the page state when the incident resolves. Default `true`. Also accepts the strings `"true"`/`"false"`. |

### Example (cURL)

```bash
curl -X POST "$BASE_URL/api/im/statuspage-rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "teamId": 3, "statusPageId": 15, "minSeverity": "sev2", "targetState": "degraded" }'
```

### Response

`200 OK`: the created rule (same shape as a list item).

## Update a rule

`PATCH /api/im/statuspage-rules/:id`

Partial update of `teamId`, `statusPageId`, `minSeverity`, `targetState` and `autoResolve` (same validation as on create). Other keys are ignored. You need the write bar on the rule's current team, and, when you change `teamId`, also on the new team.

```bash
curl -X PATCH "$BASE_URL/api/im/statuspage-rules/2" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "minSeverity": "sev1", "targetState": "warning" }'
```

`200 OK`: the updated rule.

## Delete a rule

`DELETE /api/im/statuspage-rules/:id`

```bash
curl -X DELETE "$BASE_URL/api/im/statuspage-rules/2" \
  -H "Authorization: Bearer $TOKEN"
```

`200 OK`

```json
{ "ok": true }
```

## Set a manual override

`POST /api/im/statuspage-rules/override`

Pins a state on a status page and notifies its subscribers. Replaces any override currently on the page, whether set by a rule or by hand.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `statusPageId` | integer | Yes | Status page of your organization. |
| `state` | string | Yes | `operational`, `warning` or `degraded`. |
| `message` | string | No | Text shown with the state. Trimmed and cut to 5000 characters. |

```bash
curl -X POST "$BASE_URL/api/im/statuspage-rules/override" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "statusPageId": 15, "state": "warning", "message": "Delayed email delivery, we are on it." }'
```

`200 OK`

```json
{ "ok": true }
```

## Clear an override

`DELETE /api/im/statuspage-rules/override/:statusPageId`

Removes the current override from the page, whether a rule or a person set it. The page then follows the rules (or, without an active rule, its monitors) again. Subscribers are notified if an override was active.

```bash
curl -X DELETE "$BASE_URL/api/im/statuspage-rules/override/15" \
  -H "Authorization: Bearer $TOKEN"
```

`200 OK`

```json
{ "ok": true }
```

## Common errors

- `401 Unauthorized` when not authenticated
- `403 Forbidden` (`imAccessDenied`) when using a customer-scoped token, or a session without an IM-eligible role
- `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization
- `403 Forbidden` (`imTeamWriteDenied`) when you do not meet the write bar for the rule's team (or the new team)
- `403 Forbidden` (no `data.code`) when setting or clearing an override without the `admin` or `editor` role
- `400 Bad Request` (`invalidRequestBody`) when `:id` or `:statusPageId` is not a positive integer, `teamId` or `statusPageId` is missing or invalid, `minSeverity`, `targetState` or `state` is not an allowed value, or `autoResolve` is not a boolean
- `404 Not Found` (`imStatuspageRuleNotFound`) when the rule does not exist, or belongs to another organization
- `422 Unprocessable Entity` (`invalidTeamId`) when `teamId` does not belong to your organization
- `422 Unprocessable Entity` (`invalidStatusPageId`) when `statusPageId` does not belong to your organization