> ## Documentation Index
> Fetch the complete documentation index at: https://docs.use.observer/llms.txt
> Use this file to discover all available pages before exploring further.

# Schedule your first maintenance

> Schedule a maintenance window with auto-start and auto-complete.

Maintenance windows differ from incidents in two ways: they are
planned in advance, and Observer auto-transitions them through their
lifecycle on a cron tick (so you do not have to remember to mark
"started" / "completed" manually).

## Steps

**1. Open the new-maintenance form**

In the console, open **Incidents** and select **Schedule maintenance**.
The form opens with **Type** set to **Maintenance**, drops the severity
field, and adds a **Window** section with **Starts** and **Ends**.

**2. Set the window**

Pick the start and end times in your local timezone. The cron
auto-transitions the maintenance through:

* `scheduled` → `in_progress` when `now() >= scheduled_start_at`.
* `in_progress` → `completed` when `now() >= scheduled_end_at`.

A `maintenance.starting_soon` webhook fires one hour before
`scheduled_start_at` (idempotent; once per maintenance row).

**3. Pick affected services**

The public page renders a banner for the maintenance starting within
24 hours and a sticky banner while in progress. The banner lists
affected services so customers know which surfaces are impacted.

**4. Publish**

Select **Publish and notify subscribers** to make the maintenance public. The page
banner appears within 24 hours of the scheduled start. The window
is also listed in the page's calendar feed and, once it is less than
60 days away, in the
[Upcoming maintenance](https://docs.use.observer/docs/guides/maintenance-calendar.md) section.
Subscribers receive `maintenance.scheduled` when you publish and
`maintenance.starting_soon` one hour out.

**Save as draft** keeps the maintenance private: it does not appear
on the status page, notifies nobody, and the cron does not start or
complete it. Publish it later from the maintenance row under
**Incidents** > **Open** (drafts are listed there), and `maintenance.scheduled` fires at that point.
Maintenances created through `POST /api/v1/maintenances` publish
immediately.

## Cancel a scheduled maintenance

Open the maintenance from **Incidents** > **Scheduled** and select
**Cancel maintenance**. `canceled_at` is set, the banner is removed, and
the `maintenance.canceled` webhook fires.

> [!NOTE]
>
> **Manual override**
>
> The lifecycle transitions can be triggered manually via the API
> (`POST /api/v1/maintenances/{id}/start` and `/complete`) when the
> cron schedule does not match the actual change-window timing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.