# Post announcements and incident updates

When something goes wrong, your status page should say so in your own words. From a page's **Announcements** tab you
can declare an **incident** or a **scheduled maintenance**, post updates as the situation develops, resolve it and
add a postmortem. Each declaration and each update is sent to the page's
[subscribers](/status-pages/subscribers/). A separate **announcement banner** pins a neutral notice to the top of
the page.

These are status page announcements - what you tell visitors. They are separate from the incidents HostTracker
records automatically when a monitor goes down ([What is an incident](/incidents/what-is-an-incident/)) and from
[maintenance windows](/maintenance/overview/), which change alerting.

## Incident fields

| Field (UI label) | API field | Allowed values | Default | What it does for you |
|---|---|---|---|---|
| **Type** | `kind` | **Incident** (`incident`) - "Something is broken right now."; **Maintenance** (`maintenance`) - "Planned work you scheduled in advance." | Incident | Incidents raise the page's status banner; maintenance shows as planned work. |
| **Impact** (incidents only) | `impact` | **Minor** (`minor`) - degraded performance banner; **Major** (`major`) - outage banner | Minor | How hard an open incident hits the page banner: Minor shows at least "Degraded Performance", Major shows an outage. |
| **Maintenance window** (maintenance only) | `scheduledStart`, `scheduledEnd` | **Scheduled start (UTC)** and **Scheduled end (UTC)**, both or neither; end after start. Unix seconds in the API. Past times are allowed | none | When the work runs. Without a window the maintenance has no fixed time. |
| **Title** | `title` | Text, up to 200 characters, required | - | The headline visitors see. |
| **Status** | `state` | **Investigating** (`investigating`), **Identified** (`identified`), **Monitoring** (`monitoring`), **Resolved** (`resolved`) | Investigating | Where the incident is. The first status and message become the first timeline entry. |
| **Message** | `message` | Text, up to 2,000 characters, required | - | The first update visitors read. |
| **Affected monitors** | `componentIds` | Component ids on this page | none | Which components the announcement is about; also decides which component-scoped subscribers hear about it. |
| **Save this title and message as a reusable template** | (templates API) | checkbox | off | Saves a template for next time. |
| **Postmortem** (resolved incidents) | `postmortem` | Text | none | A write-up shown with the resolved incident. |

## Declare an incident in the app

1. Open **Status pages** and click **Edit** on the page (or the bullhorn button "Declare an incident on this page" in
   the list), then go to the **Announcements** tab.
2. In **Incidents & maintenance**, click **New announcement**. Pick **Use a template** or **Start from scratch**.
3. Choose the **Type**. For an incident pick the **Impact**; for maintenance fill in the **Maintenance window**
   (times are UTC, not your local time).
4. Enter the **Title**, pick the **Status**, write the **Message** and select the **Affected monitors**.
5. Click **Post**. The incident appears at the top of the public page and is sent to subscribers.

Switching between Incident and Maintenance resets the fields that only apply to the other type (a maintenance window
is cleared, and the impact goes back to Minor).

## Post updates and resolve

Each announcement card shows its type and impact, its status (or, for maintenance with a window, **Scheduled**,
**In progress** or **Completed**), and its timeline (the latest 3 entries, with **Show all**).

- **Post update** - choose the new **Status**, write a message and post. The entry is added to the timeline with a
  timestamp and sent to subscribers.
- **Resolve** - posts a resolved entry and closes the incident. The resolved time is stamped once.
- **Add a follow-up note** - on a resolved incident, adds a note. If you change the status away from Resolved, the
  incident reopens and its resolved time is cleared.
- **Postmortem** - on a resolved incident, **Add postmortem**, then **Save postmortem** (or **Clear**).
- **Edit** - fixes the title, type, affected components or maintenance window. Messages already posted cannot be
  edited; post a new update instead.
- **Delete** - removes the announcement from the page.

**Who is notified:** declaring and every update (including resolve) go to the page's confirmed subscribers whose
scope matches. Edits and deletes are **not** sent to anyone.

## The announcement banner

**Announcement banner** at the top of the Announcements tab is a neutral notice pinned above the services (for
example "Scheduled maintenance Sunday 2-4am UTC"), up to 500 characters. Click **Save banner**; clear the text and
save to remove it. The banner is not sent to subscribers. API field: `settings.announcement`.

## Templates

Templates store a title, a message and a default impact for announcements you post often ("Investigating elevated
errors", "Resolved"). Tick **Save this title and message as a reusable template** when posting, then pick it with
**Use a template**. **Manage** lets you **Delete template**. Templates cannot be edited - delete and recreate.

## Do it with the API or MCP

Scopes `statuspage:read` / `statuspage:write`. Declaring and appending to the timeline **require an
`Idempotency-Key`** (a keyless retry could announce twice).

**Declare** - `POST /statuspage/{id}/incident`:

```bash
curl -X POST https://api2.host-tracker.com/statuspage/PAGE_ID/incident \
  -H "Authorization: Bearer $HT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: incident-2026-10-01-checkout" \
  -d '{
    "title": "Checkout is failing for some customers",
    "state": "investigating",
    "message": "We are looking into elevated errors on checkout.",
    "componentIds": ["COMPONENT_ID"],
    "impact": "major"
  }'
```

A scheduled maintenance uses the same call with `"kind": "maintenance"` and `scheduledStart` / `scheduledEnd` in Unix
seconds.

**Update or resolve** - `POST /statuspage/{id}/incident/{incidentId}/timeline`:

```bash
curl -X POST https://api2.host-tracker.com/statuspage/PAGE_ID/incident/INCIDENT_ID/timeline \
  -H "Authorization: Bearer $HT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: incident-2026-10-01-checkout-update-2" \
  -d '{ "state": "resolved", "message": "Checkout is fully recovered." }'
```

| Task | Operation |
|---|---|
| List / read | `GET /statuspage/{id}/incident` (newest first, each with its `timeline`), `GET /statuspage/{id}/incident/{incidentId}` |
| Fix title, kind, components, window; set or clear the postmortem | `PATCH /statuspage/{id}/incident/{incidentId}` (the timeline is untouched; no notification) |
| Delete | `DELETE /statuspage/{id}/incident/{incidentId}` (no notification) |
| Templates | `GET` / `POST /statuspage/{id}/template` (`{title, message, defaultImpact}`), `DELETE /statuspage/{id}/template/{templateId}` |
| Banner | `PATCH /statuspage/{id}` with `{"settings": {"announcement": "..."}}` |

An incident reads back with `id`, `title`, `state`, `kind`, `impact`, `created`, `resolvedAt`, `scheduledStart`,
`scheduledEnd`, `componentIds`, `componentNames`, `postmortem` and `timeline[]` (`state`, `message`, `at`).

**MCP:** `create_status_page_incident` (arguments `id`, `title`, `message`, `state`, `kind`, `impact`,
`componentIds`, `scheduledStart`, `scheduledEnd`, `idempotencyKey`) and `add_status_page_incident_update` (`id`,
`incidentId`, `message`, `state`, `idempotencyKey`). In the tool, `componentIds` is a **comma-separated string**
(`componentIds="C1,C2"`), not the JSON array the REST body uses; the component ids come from `get_status_page`.
The tools generate an idempotency key when you pass none. Example:

```
create_status_page_incident(id="PAGE_ID", title="Payment delays", state="investigating", impact="minor",
  message="We are investigating delays processing payments.", componentIds="COMPONENT_ID")
add_status_page_incident_update(id="PAGE_ID", incidentId="INCIDENT_ID", state="monitoring",
  message="A fix has been applied; we are monitoring the results.")
```

Both publish immediately and notify subscribers, so have the page owner approve the wording first. Other
operations go through `api_request`.

## Limits and gotchas

- Messages are append-only: fix a mistake with a new update, not an edit.
- The page banner reflects open incidents - an incident left in Investigating keeps the page amber or red. Resolve
  it when the issue is over.
- Backdated maintenance (a window in the past) is allowed; it colours those days blue on the uptime bars.
- A declared maintenance does not suppress alerts or statistics. For that, schedule a
  [maintenance window](/maintenance/create/) on the monitors - with **Show on status page** on, it appears on the
  page by itself.

## Related

- [Let visitors subscribe](/status-pages/subscribers/)
- [Show maintenance windows on your status page](/maintenance/status-page-display/)
- [What is an incident](/incidents/what-is-an-incident/)
- [Status pages overview](/status-pages/overview/)