Skip to content
openstatus openstatus
Get Started

Maintenance Reference

Overview

Section titled “Overview”

A maintenance window is a scheduled period during which you expect planned disruption to one or more services — a database upgrade, a deployment, or infrastructure work. Announcing it ahead of time lets you communicate the disruption to your users instead of letting your status page register it as an unexpected outage.

A maintenance belongs to a single status page and targets one or more of that page’s components — monitor-linked or static.

Behavior

Section titled “Behavior”

While a maintenance window is active (the current time is between from and to):

  • The affected components display the Under Maintenance (info) status on the status page.
  • A higher-priority event overrides it: an active incident (error) or an unresolved status report (degraded) takes precedence, so the component shows that status instead. Maintenance only outranks the default operational status.
  • The maintenance is reflected in the historical status bars for the days it overlaps.

Maintenance windows do not exclude downtime from uptime calculations. The uptime percentage is computed from raw check results and is unaffected by maintenance windows; only the displayed status changes.

When a maintenance is created, status page subscribers can be notified that it has been scheduled (see Notify). Updating a maintenance never re-notifies.

Configuration and Properties

Section titled “Configuration and Properties”

Title

Section titled “Title”

Type: String (required) Length: 1–256 characters

A short, human-readable name for the maintenance window.

Example: "Database Upgrade"

Message

Section titled “Message”

Type: String (required)

A description of the maintenance shown to users, explaining what is happening and the expected impact.

Example: "Upgrading our database to improve performance. Brief interruptions may occur."

From

Section titled “From”

Type: Datetime (required) Format: RFC 3339 / ISO 8601 (e.g., 2026-01-20T02:00:00Z)

When the maintenance window starts.

To

Section titled “To”

Type: Datetime (required) Format: RFC 3339 / ISO 8601 (e.g., 2026-01-20T04:00:00Z)

When the maintenance window ends. Must be later than from.

Status Page

Section titled “Status Page”

Type: Integer (required)

The id of the status page this maintenance belongs to. A maintenance is scoped to exactly one status page.

Affected Components

Section titled “Affected Components”

Type: Array of integers (optional) Default: []

The ids of the page components that should display the Under Maintenance status during the window. Each component must belong to the status page referenced above, and can be either a monitor-linked or a static component.

In the v1 REST API these are passed as monitorIds, which accepts monitor components only and is retained for backward compatibility. Static components can be targeted through the dashboard.

Notify

Section titled “Notify”

Type: Boolean (optional) Default: false

A one-time flag evaluated at creation time — it is not stored on the maintenance record and cannot be read back. When set, status page subscribers are notified that the maintenance has been scheduled.

The v1 REST API does not expose this flag; it notifies subscribers automatically when a maintenance is created on a page whose workspace has subscribers enabled.

Relationships

Section titled “Relationships”
  • Status page — a maintenance is tied to a single page. Deleting the page deletes its maintenance windows.
  • Page components — a maintenance can affect multiple components (monitor-linked or static), and a component can be covered by multiple (including overlapping) maintenance windows.
Section titled “Related resources”