Maintenance Windows

A maintenance window tells DevHelm “I expect these monitors to fail (or look weird) for a defined period — please don’t page on-call.” Use them around deploys, database migrations, scheduled provider maintenance, or any time you’d rather absorb a few minutes of red than wake someone up. Maintenance windows are a runtime state operation, not a piece of infrastructure. You schedule them, you cancel them, they expire — like an incident, not like a monitor. That distinction shapes which surfaces support them.

How they work

While a maintenance window is active for a monitor:

Alert suppression — notification policies are bypassed and no channels fire (when suppressAlerts is true, the default).
Severity tagging — any incident that opens during the window is created at severity MAINTENANCE instead of DOWN or DEGRADED.
Monitoring continues — checks still run, results are still recorded, and the timeline still tells the truth. Suppression silences the noise; it does not pause the data.

When the window ends — or you cancel it — alerting resumes immediately on the next failed check.

Surface support (v1)

Maintenance windows are imperative state. They live behind the surfaces that operate on state — not the ones that describe infrastructure.

Surface	Supports maintenance windows?	Why
REST API (`/api/v1/maintenance-windows`)	Yes	Source of truth
Dashboard UI	Yes	Schedule from the monitor or org-wide
CLI imperative (`devhelm maintenance-windows ...`)	Yes	Same as `devhelm incidents create` — a state operation
Python SDK (`client.maintenance_windows`)	Yes	Same as `client.incidents`
JS / TS SDK (`client.maintenanceWindows`)	Yes	Same as `client.incidents`
MCP server tools (`create_maintenance_window`, …)	Yes	AI agents schedule them around deploys
Terraform provider	No (intentional)	Windows are state, not infrastructure
CLI declarative (`devhelm.yml` + `devhelm deploy`)	No (intentional)	Same — `devhelm.yml` describes monitors and channels, not transient operational state

Why not Terraform? Why not `devhelm.yml`?

Terraform and devhelm.yml are declarative: they describe the desired long-lived state of your monitoring stack — which monitors exist, what channels are wired up, who gets paged. A maintenance window is transient operational state, owned by whoever is performing the maintenance:

Putting a maintenance window in Terraform would mean every deploy that schedules a window also generates a Git commit, a PR, an apply — for something that will be gone in 30 minutes.
Putting one in devhelm deploy would mean the YAML diverges from the live state the moment the window opens, and devhelm plan would show it as drift.
Worst of all, removing the window from the file (after the deploy succeeds) would not cancel an active window — devhelm deploy would interpret the absence as “the window doesn’t exist yet” and re-create it on the next CI run.

The right tool for “schedule a window during my deploy” is the imperative one your deploy script can call directly: the CLI, an SDK, or the MCP tool. The right tool for “describe the monitors and channels I always want to exist” is devhelm.yml or Terraform. They don’t compete; they cover different jobs. If you need recurring maintenance (e.g., every Sunday 02:00 UTC), the API supports it with repeatRule (an iCal RRULE) — no Terraform required.

Request fields

Both create (POST /api/v1/maintenance-windows) and update (PUT /api/v1/maintenance-windows/{id}) accept the same body:

Field	Type	Required	Description
`monitorId`	UUID	No	Single monitor to scope the window to. Omit (or `null`) for an org-wide window covering every monitor.
`startsAt`	datetime	Yes	When the window opens. ISO 8601 with explicit timezone (UTC preferred).
`endsAt`	datetime	Yes	When the window closes. Must be strictly after `startsAt`.
`repeatRule`	string	No	iCal RRULE for recurring windows (max 100 chars). Omit for one-time.
`reason`	string	No	Human-readable description shown in the dashboard and audit log.
`suppressAlerts`	boolean	No	Default `true`. Set `false` to record the window for audit without silencing notifications.

Each window covers one monitor or the entire organization — there is no native “this list of monitors” form. To cover several specific monitors, schedule one window per monitor (the CLI’s --monitor flag does this for you when you pass several IDs).

Quick examples

devhelm maintenance-windows create \
  --start "2026-05-15T14:00:00Z" \
  --end "2026-05-15T14:30:00Z" \
  --reason "Quarterly DB upgrade" \
  --monitor <monitor-id>

from devhelm import Devhelm

client = Devhelm()  # reads DEVHELM_API_TOKEN, org/workspace headers from env

window = client.maintenance_windows.create({
    "monitorId": "<monitor-id>",
    "startsAt": "2026-05-15T14:00:00Z",
    "endsAt": "2026-05-15T14:30:00Z",
    "reason": "Quarterly DB upgrade",
})

import {Devhelm} from '@devhelm/sdk'

const client = new Devhelm({token: process.env.DEVHELM_API_TOKEN!})

const window = await client.maintenanceWindows.create({
  monitorId: '<monitor-id>',
  startsAt: '2026-05-15T14:00:00Z',
  endsAt: '2026-05-15T14:30:00Z',
  reason: 'Quarterly DB upgrade',
})

curl -X POST https://api.devhelm.io/api/v1/maintenance-windows \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "monitorId": "<monitor-id>",
    "startsAt": "2026-05-15T14:00:00Z",
    "endsAt": "2026-05-15T14:30:00Z",
    "reason": "Quarterly DB upgrade",
    "suppressAlerts": true
  }'

Omit monitorId (or --monitor) to make the window org-wide.

Recurring windows

Use repeatRule with an iCal RRULE for recurring schedules. The startsAt / endsAt define the first occurrence; the RRULE generates the rest.

{
  "startsAt": "2026-04-15T02:00:00Z",
  "endsAt":   "2026-04-15T04:00:00Z",
  "repeatRule": "FREQ=WEEKLY;BYDAY=TU",
  "reason": "Weekly infra maintenance"
}

Common patterns:

RRULE	Schedule
`FREQ=WEEKLY;BYDAY=TU`	Every Tuesday
`FREQ=MONTHLY;BYMONTHDAY=1`	First day of each month
`FREQ=WEEKLY;BYDAY=SA;INTERVAL=2`	Every other Saturday

Update or cancel

If the deploy runs long, extend the window — don’t let it expire and have alerts flood in:

devhelm maintenance-windows update <window-id> \
  --start "2026-05-15T14:00:00Z" \
  --end   "2026-05-15T15:00:00Z" \
  --reason "Migration still running"

The update endpoint is a full replacement (PUT, not PATCH) — pass the complete intended state, not a delta. Once the deploy succeeds, cancel the window so alerting resumes:

devhelm maintenance-windows cancel <window-id>

There’s no “uncancel” — schedule a new window if you need to restore suppression.

Listing

devhelm maintenance-windows list                       # all windows
devhelm maintenance-windows list --status active       # currently in progress
devhelm maintenance-windows list --status upcoming     # scheduled, not yet open
devhelm maintenance-windows list --monitor <monitor-id>

The --status values are active and upcoming; past / cancelled windows are not returned today (omit --status for the broadest result).