Maintenance windows Beta

Tell RankNibbler when you're doing planned work, so your team isn't alerted about it and it doesn't count against your uptime. A window can happen once or repeat every few days, weeks or months.

Every endpoint in this group needs an X-API-Key header, and each call counts once against your daily quota. Reading needs access to uptime monitoring in the app; every other method needs permission to manage uptime monitors, which also covers maintenance windows. See Monitoring API: getting started for authentication, rate limits and errors.

Endpoints

Method	Endpoint	Does
`GET`	`/api/v1/maintenance`	List windows, by status or monitor
`POST`	`/api/v1/maintenance`	Create a window, one-off or repeating
`GET`	`/api/v1/maintenance/{id}`	One window
`PATCH`	`/api/v1/maintenance/{id}`	Change a window
`DELETE`	`/api/v1/maintenance/{id}`	Delete a window and its occurrences
`DELETE`	`/api/v1/maintenance?ids=…`	Delete up to 500 windows at once
`GET`	`/api/v1/maintenance/occurrences`	List occurrences in a date range
`GET`	`/api/v1/maintenance/occurrences/{id}`	One occurrence
`PATCH`	`/api/v1/maintenance/occurrences/{id}`	Move or resize one occurrence
`DELETE`	`/api/v1/maintenance/occurrences/{id}`	Cancel one occurrence
`DELETE`	`/api/v1/maintenance/occurrences?ids=…`	Cancel up to 500 occurrences at once

How maintenance works

Windows and occurrences

A window (id like mw_3f9a0c1d2e4b5a6c7d8e) is the plan: a description, a first start and end, how it repeats, and which monitors it covers.
Each time the window happens is an occurrence (a numeric id such as "48213"). A one-off window has one occurrence.
Occurrences are generated up to a year ahead and topped up automatically, so a window that repeats forever always has a year of occurrences.
Only occurrences from now on are generated. If a window's first occurrence is already under way when you create it, that one is kept too.
You can move or cancel a single occurrence without changing the rest.

During an occurrence

Checks keep running, so results and response times are still recorded.
No alert emails are sent, and no uptime.down or uptime.up webhooks go out.
The one exception: if an outage began before the window and the site recovers during it, the uptime.up webhook is still sent.
If the monitor is still down when the window ends, the down alert goes out then.

In reports

Maintenance time counts as maintenance, not downtime, and is left out of uptime percentages.
Summary has maintenanceSeconds. Outages that fell entirely inside maintenance aren't counted in outages.
Outages marks those outages with duringMaintenance: true, and its timeline has a maintenance status.
Performance with includeUptime=true has maintenanceSeconds per bucket.
Get a monitor has a maintenance object with the current and next occurrences, and lastOutage.duringMaintenance.

The window object

window

{
"id": "mw_3f9a0c1d2e4b5a6c7d8e",
"description": "Weekly database backup",
"from": "2026-09-20T02:00:00.000Z",
"to": "2026-09-20T03:00:00.000Z",
"recurrence": "week",
"repeatEvery": 1,
"effectiveTo": null,
"allMonitors": false,
"monitorIds": ["mon_79ce3cf9c4fa56e98af4", "mon_4b1d0a7e2c9f83d56e10"],
"nextOccurrence": { "id": "48213", "from": "2026-09-20T02:00:00.000Z", "to": "2026-09-20T03:00:00.000Z" },
"active": false,
"createdAt": "2026-09-17T10:12:44.000Z",
"updatedAt": "2026-09-17T10:12:44.000Z"
}

Field	Type	Description
`id`	string	The window id, starting `mw_`.
`description`	string	What the work is. Up to 200 characters.
`from`, `to`	string	The first occurrence's start and end. The length of every occurrence is `to` minus `from`.
`recurrence`	string	`none`, `day`, `week` or `month`.
`repeatEvery`	integer	Repeat every this many days, weeks or months, from 1 to 100.
`effectiveTo`	string \| null	No occurrences start after this time. `null` repeats for ever.
`allMonitors`	boolean	`true` covers every monitor in the workspace, including ones added later.
`monitorIds`	string[]	The monitors it covers when `allMonitors` is `false`.
`nextOccurrence`	object \| null	The current or next occurrence (`id`, `from`, `to`). `null` when none are left.
`active`	boolean	`true` while an occurrence is running.
`createdAt`, `updatedAt`	string	When the window was created and last changed.

An occurrence is { id, maintenanceId, description, from, to, modified }, where modified is true for one that was moved on its own.