Maintenance window reference

The full request schemas live in the auto-generated API Reference. This page is the human-readable cheat sheet for /maintenance_windows.

Request settings

Field	Type	Default	Description
`name`	string	required	Window label.
`tags`	string[]	required	Must be non-empty. A monitor is covered when its tags overlap this list.
`schedule_type`	enum	required	`one_time` or `recurring`.
`timezone`	string	`UTC`	IANA timezone name. Recurrence times are interpreted in this timezone.
`starts_at`	rfc3339	required for `one_time`	Window start. Must be before `ends_at`.
`ends_at`	rfc3339	required for `one_time`	Window end.
`recurrence`	object	required for `recurring`	Recurrence rule (below).

{ "type": "daily", "start_time": "02:00", "end_time": "03:00" }

{ "type": "weekly", "days": ["sun"], "start_time": "02:00", "end_time": "04:00" }

Key	Type	Description
`type`	enum	`daily` or `weekly`.
`start_time` / `end_time`	string	24-hour `HH:MM` in the window’s `timezone`. An `end_time` earlier than `start_time` wraps past midnight (e.g. `23:00` to `01:00`).
`days`	string[]	Weekly only; must be non-empty. Day names, case-insensitive: full English names (`monday` .. `sunday`) or three-letter abbreviations (`mon` .. `sun`). Anything else is rejected with a 400.

Field	Type	Description
`id`	uuid	Window ID.
`account_id`	uuid	Owning account.
`is_currently_active`	bool	Whether the window is in effect right now, computed server-side.
`created_at` / `updated_at`	rfc3339	Timestamps.

The check applies to notifications that carry monitor context (HTTP and cron monitors). While a matching window is active:

Failure notifications are held, not dropped: they are stored and re-evaluated when the window’s current occurrence ends, so a monitor still down after the window pages then.
Recovery notifications are suppressed and clear the held failure for that monitor, so a blip fully inside the window pages no one.
Checks keep running and results keep being recorded throughout.

Method	Path	Purpose
`GET`	`/maintenance_windows`	List.
`POST`	`/maintenance_windows`	Create.
`PUT`	`/maintenance_windows/{window_id}`	Update (partial; omitted fields keep their value).
`DELETE`	`/maintenance_windows/{window_id}`	Delete.