Maintenance windows

The maintenance window object:

{
  "id": "5f2c…",
  "object": "maintenance_window",
  "name": "DB migration",
  "description": "Quarterly index rebuild",
  "monitor_ids": ["0b0f6a41-…"],
  "monitor_tags": ["prod"],
  "starts_at": "2026-08-30T22:00:00.000Z",
  "duration_minutes": 60,
  "timezone": "UTC",
  "recurrence": "once",
  "recurrence_until": null,
  "suppress_alerts": true,
  "exclude_from_sla": true,
  "enabled": true,
  "created_at": "2026-08-24T12:00:00.000Z"
}

During an active window, alerts for the covered monitors are suppressed and (optionally) the time is excluded from uptime/SLA — checks keep running. See maintenance windows.

List windows

GET /v1/maintenance-windows — most recent first. Query: limit, cursor (pass the previous page's next_cursor).

curl https://watchfor.io/api/v1/maintenance-windows \
  -H "Authorization: Bearer wf_live_YOUR_KEY"

Get a window

GET /v1/maintenance-windows/{id}

Create a window

POST /v1/maintenance-windows — requires write scope. The classic CI use case: open a window right before a deploy.

Body fields: name (required), startsAt (required, ISO 8601), durationMinutes (required, 5–43200), monitorIds and/or monitorTags, description, timezone (default UTC), recurrence (once|daily|weekly|monthly), recurrenceUntil, suppressAlerts (default true), excludeFromSla (default true).

curl -X POST https://watchfor.io/api/v1/maintenance-windows \
  -H "Authorization: Bearer wf_live_YOUR_KEY" \
  -H "Idempotency-Key: deploy-v2.14" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deploy v2.14",
    "startsAt": "2026-08-30T22:00:00Z",
    "durationMinutes": 30,
    "monitorTags": ["prod"]
  }'

Returns 201 with the created window. Send an Idempotency-Key header (as above) to make retries safe — a CI job that times out and retries won't open two windows. Publishing a window to status pages (statusPageIds, autoPublish) is dashboard-only for now and rejected with 400 if sent.

Update a window

PATCH /v1/maintenance-windows/{id} — requires write scope. Send only the fields you want to change; enabled: false disables the window without deleting it.

curl -X PATCH https://watchfor.io/api/v1/maintenance-windows/5f2c… \
  -H "Authorization: Bearer wf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "durationMinutes": 90 }'

Delete a window

DELETE /v1/maintenance-windows/{id} — requires write scope. If the window is active right now, its alert silences are lifted immediately.

curl -X DELETE https://watchfor.io/api/v1/maintenance-windows/5f2c… \
  -H "Authorization: Bearer wf_live_YOUR_KEY"

Returns 204 No Content.