Maintenance Windows

Maintenance windows let you schedule planned downtime, notify subscribers in advance, and keep the status page updated automatically.

Maintenance Lifecycle

Scheduling

Create a maintenance window with a title, description, start/end times, and affected components:

{
  "title": "Database Migration",
  "description": "Scheduled database upgrade to improve performance.",
  "scheduledStart": "2025-01-15T02:00:00Z",
  "scheduledEnd": "2025-01-15T04:00:00Z",
  "componentIds": ["abc123"]
}

Subscribers are notified when maintenance is scheduled, and affected components are displayed on the status page.

Automatic Transitions

Background jobs handle maintenance transitions automatically:

• Auto-start — When the scheduled start time arrives, the maintenance status changes to in_progress and affected components are updated
• Auto-complete — When the scheduled end time arrives, the maintenance is marked completed and components return to their previous status

Manual Controls

You can also manage maintenance manually at any time:

• Start early — PATCH /api/v1/admin/maintenance/:id/start
• Complete manually — PATCH /api/v1/admin/maintenance/:id/complete
• Cancel — DELETE /api/v1/admin/maintenance/:id

Status Page Display

The public status page shows maintenance in three places:

• Upcoming maintenance — Scheduled windows that haven't started yet
• Active maintenance banner — A prominent banner when maintenance is in progress
• Maintenance history — Past maintenance events

Notifications

Subscribers and webhooks are notified at each stage:

• maintenance.scheduled — When a maintenance window is created
• maintenance.started — When maintenance begins (auto or manual)
• maintenance.completed — When maintenance ends

See Notifications and Webhooks for configuration details.

API Reference

See Admin Endpoints — Maintenance for the full API.