Maintenance Windows

Schedule and manage maintenance windows. Suppress alerts during planned downtime.

Last updated: 2026-09-05

Maintenance windows allow you to schedule planned downtime for your monitors. During a maintenance window, alerts can be suppressed and the status page can display a maintenance notice.

Scope

monitorType and monitorId are the window's scope, and together they mean one of three things:

  • Neither — every monitor the team has, of every kind.

  • monitorType alone — every monitor of that kind, including ones created later.

  • monitorType and monitorId — that one monitor, looked up in that kind's monitors.

A monitorId sent on its own is read as an HTTP monitor, which is what it has always meant, so clients written before the other monitor kinds arrived keep working untouched.

A monitorId that does not belong to the team, or that belongs to a different kind of monitor than monitorType names, answers 404 NOT_FOUND with "Monitor not found" — the window is never quietly widened to the whole team instead.

GET /api/v1/maintenance

Returns the maintenance windows for your team. This endpoint is paginated; see Pagination for how to page through the full list.

Required Scope

maintenance:read

Query Parameters

ParameterTypeRequiredDescription
perPageintegerNoResults per page, 1-200 (default: 50)
cursorstringNoPage to fetch, taken from a Link header

Example Request

cURL

curl "https://uptime.sergiodxa.com/api/v1/maintenance?perPage=25" \
  -H "Authorization: Bearer uptime_your_api_key"

Response

{
	"data": {
		"maintenanceWindows": [
			{
				"id": "mnt_abc123",
				"teamId": "team_xyz789",
				"monitorType": "http",
				"monitorId": "mon_def456",
				"name": "Database Migration",
				"startsAt": 1771120800000,
				"endsAt": 1771128000000,
				"endedEarlyAt": null,
				"suppressAlerts": true,
				"showOnStatusPage": true,
				"createdAt": 1771070400000,
				"updatedAt": 1771070400000
			}
		]
	},
	"meta": {
		"requestId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
		"timestamp": "2026-02-14T12:00:00.000Z",
		"pagination": {
			"next": "eyJkIjoiYWZ0ZXIi",
			"prev": null,
			"perPage": 25,
			"total": 31
		}
	}
}

The cursors for this page arrive in meta.pagination:

FieldTypeDescription
meta.pagination.nextstring | nullCursor for the following page, null on the last
meta.pagination.prevstring | nullCursor for the preceding page, null on the first
meta.pagination.perPageintegerResults this page was built with
meta.pagination.totalintegerMaintenance windows matching, across every page

Possible Errors

StatusCodeDescription
400BAD_REQUESTInvalid or malformed cursor
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key doesn't have maintenance:read scope
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Response Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": ["data", "meta"],
	"properties": {
		"data": {
			"type": "object",
			"required": ["maintenanceWindows"],
			"properties": {
				"maintenanceWindows": {
					"type": "array",
					"items": {
						"$ref": "#/$defs/maintenanceWindow"
					}
				}
			}
		},
		"meta": {
			"type": "object",
			"required": ["requestId", "timestamp"],
			"properties": {
				"requestId": {
					"type": "string",
					"format": "uuid"
				},
				"timestamp": {
					"type": "string",
					"format": "date-time"
				},
				"pagination": {
					"type": "object",
					"required": ["next", "prev", "perPage"],
					"properties": {
						"next": {
							"type": ["string", "null"]
						},
						"prev": {
							"type": ["string", "null"]
						},
						"perPage": {
							"type": "integer"
						},
						"total": {
							"type": "integer"
						}
					}
				}
			}
		}
	},
	"$defs": {
		"maintenanceWindow": {
			"type": "object",
			"required": [
				"id",
				"teamId",
				"monitorId",
				"name",
				"startsAt",
				"endsAt",
				"endedEarlyAt",
				"suppressAlerts",
				"showOnStatusPage",
				"createdAt",
				"updatedAt"
			],
			"properties": {
				"id": {
					"type": "string",
					"pattern": "^mnt_[a-zA-Z0-9]+$"
				},
				"teamId": {
					"type": "string",
					"pattern": "^team_[a-zA-Z0-9]+$"
				},
				"monitorType": {
					"type": ["string", "null"],
					"enum": ["http", "dns", "tcp", "cron", null]
				},
				"monitorId": {
					"type": ["string", "null"]
				},
				"name": {
					"type": "string",
					"minLength": 1,
					"maxLength": 255
				},
				"startsAt": {
					"type": "integer"
				},
				"endsAt": {
					"type": "integer"
				},
				"endedEarlyAt": {
					"type": ["integer", "null"]
				},
				"suppressAlerts": {
					"type": "boolean"
				},
				"showOnStatusPage": {
					"type": "boolean"
				},
				"createdAt": {
					"type": "integer"
				},
				"updatedAt": {
					"type": "integer"
				}
			}
		}
	}
}

POST /api/v1/maintenance

Creates a new maintenance window.

Required Scope

maintenance:write

Request Body

FieldTypeRequiredDescription
namestringYesName of the maintenance window (1-255 characters)
startsAtstringYesStart time in ISO 8601 format
endsAtstringYesEnd time in ISO 8601 format (must be after startsAt)
monitorTypestring | nullNoLimit the window to one kind of monitor: http, dns, tcp or cron. Sent on its own, the window covers every monitor of that kind, including ones created later.
monitorIdstring | nullNoLimit the window to a single monitor, or null for all monitors. Sent together with monitorType, the id is looked up in that kind's monitors; sent on its own it is read as an HTTP monitor, which is what it has always meant.
suppressAlertsbooleanNoWhether to suppress alerts during maintenance (default: true)
showOnStatusPagebooleanNoWhether to show maintenance on status page (default: true)

Example Request

cURL

curl -X POST https://uptime.sergiodxa.com/api/v1/maintenance \
  -H "Authorization: Bearer uptime_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Database Migration",
    "startsAt": "2026-02-15T02:00:00Z",
    "endsAt": "2026-02-15T04:00:00Z",
    "monitorType": "http",
    "monitorId": "mon_def456",
    "suppressAlerts": true,
    "showOnStatusPage": true
  }'

Response

{
	"data": {
		"id": "mnt_abc123",
		"teamId": "team_xyz789",
		"monitorType": "http",
		"monitorId": "mon_def456",
		"name": "Database Migration",
		"startsAt": "2026-02-15T02:00:00Z",
		"endsAt": "2026-02-15T04:00:00Z",
		"endedEarlyAt": null,
		"suppressAlerts": true,
		"showOnStatusPage": true,
		"createdAt": "2026-02-14T10:00:00Z",
		"updatedAt": "2026-02-14T10:00:00Z"
	}
}

Possible Errors

StatusCodeDescription
400VALIDATION_ERRORInvalid request body or validation failed
400INVALID_DATE_RANGEendsAt must be after startsAt
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key doesn't have maintenance:write scope
404NOT_FOUNDMonitor not found for the given scope
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Request Body Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": ["name", "startsAt", "endsAt"],
	"properties": {
		"name": {
			"type": "string",
			"minLength": 1,
			"maxLength": 255
		},
		"startsAt": {
			"type": "string",
			"format": "date-time"
		},
		"endsAt": {
			"type": "string",
			"format": "date-time"
		},
		"monitorType": {
			"type": ["string", "null"],
			"enum": ["http", "dns", "tcp", "cron", null]
		},
		"monitorId": {
			"type": ["string", "null"],
			"pattern": "^mon_[a-zA-Z0-9]+$"
		},
		"suppressAlerts": {
			"type": "boolean",
			"default": true
		},
		"showOnStatusPage": {
			"type": "boolean",
			"default": true
		}
	}
}

Response Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": ["data"],
	"properties": {
		"data": {
			"type": "object",
			"required": [
				"id",
				"teamId",
				"monitorId",
				"name",
				"startsAt",
				"endsAt",
				"endedEarlyAt",
				"suppressAlerts",
				"showOnStatusPage",
				"createdAt",
				"updatedAt"
			],
			"properties": {
				"id": {
					"type": "string",
					"pattern": "^mnt_[a-zA-Z0-9]+$"
				},
				"teamId": {
					"type": "string",
					"pattern": "^team_[a-zA-Z0-9]+$"
				},
				"monitorType": {
					"type": ["string", "null"],
					"enum": ["http", "dns", "tcp", "cron", null]
				},
				"monitorId": {
					"type": ["string", "null"],
					"pattern": "^mon_[a-zA-Z0-9]+$"
				},
				"name": {
					"type": "string",
					"minLength": 1,
					"maxLength": 255
				},
				"startsAt": {
					"type": "string",
					"format": "date-time"
				},
				"endsAt": {
					"type": "string",
					"format": "date-time"
				},
				"endedEarlyAt": {
					"type": ["string", "null"],
					"format": "date-time"
				},
				"suppressAlerts": {
					"type": "boolean"
				},
				"showOnStatusPage": {
					"type": "boolean"
				},
				"createdAt": {
					"type": "string",
					"format": "date-time"
				},
				"updatedAt": {
					"type": "string",
					"format": "date-time"
				}
			}
		}
	}
}

GET /api/v1/maintenance/:id

Returns a single maintenance window by ID.

Required Scope

maintenance:read

Example Request

cURL

curl https://uptime.sergiodxa.com/api/v1/maintenance/mnt_abc123 \
  -H "Authorization: Bearer uptime_your_api_key"

Response

{
	"data": {
		"id": "mnt_abc123",
		"teamId": "team_xyz789",
		"monitorType": "http",
		"monitorId": "mon_def456",
		"name": "Database Migration",
		"startsAt": "2026-02-15T02:00:00Z",
		"endsAt": "2026-02-15T04:00:00Z",
		"endedEarlyAt": null,
		"suppressAlerts": true,
		"showOnStatusPage": true,
		"createdAt": "2026-02-14T10:00:00Z",
		"updatedAt": "2026-02-14T10:00:00Z"
	}
}

Possible Errors

StatusCodeDescription
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key doesn't have maintenance:read scope
404NOT_FOUNDMaintenance window not found
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Response Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": ["data"],
	"properties": {
		"data": {
			"type": "object",
			"required": [
				"id",
				"teamId",
				"monitorId",
				"name",
				"startsAt",
				"endsAt",
				"endedEarlyAt",
				"suppressAlerts",
				"showOnStatusPage",
				"createdAt",
				"updatedAt"
			],
			"properties": {
				"id": {
					"type": "string",
					"pattern": "^mnt_[a-zA-Z0-9]+$"
				},
				"teamId": {
					"type": "string",
					"pattern": "^team_[a-zA-Z0-9]+$"
				},
				"monitorType": {
					"type": ["string", "null"],
					"enum": ["http", "dns", "tcp", "cron", null]
				},
				"monitorId": {
					"type": ["string", "null"],
					"pattern": "^mon_[a-zA-Z0-9]+$"
				},
				"name": {
					"type": "string",
					"minLength": 1,
					"maxLength": 255
				},
				"startsAt": {
					"type": "string",
					"format": "date-time"
				},
				"endsAt": {
					"type": "string",
					"format": "date-time"
				},
				"endedEarlyAt": {
					"type": ["string", "null"],
					"format": "date-time"
				},
				"suppressAlerts": {
					"type": "boolean"
				},
				"showOnStatusPage": {
					"type": "boolean"
				},
				"createdAt": {
					"type": "string",
					"format": "date-time"
				},
				"updatedAt": {
					"type": "string",
					"format": "date-time"
				}
			}
		}
	}
}

PUT /api/v1/maintenance/:id

Updates an existing maintenance window.

Required Scope

maintenance:write

Request Body

FieldTypeRequiredDescription
namestringNoName of the maintenance window (1-255 characters)
startsAtstringNoStart time in ISO 8601 format
endsAtstringNoEnd time in ISO 8601 format (must be after startsAt)
monitorTypestring | nullNoThe kind of monitor the window is limited to: http, dns, tcp or cron
monitorIdstring | nullNoThe single monitor the window is limited to, or null for all monitors
suppressAlertsbooleanNoWhether to suppress alerts during maintenance
showOnStatusPagebooleanNoWhether to show maintenance on status page

monitorType and monitorId are the window's scope, and they move as a pair: send either one and both are rewritten, so narrowing a window to a whole kind of monitor cannot leave the previous monitor's id behind it. Mention neither and the scope is left exactly as it is.

  • {"monitorType": "dns"} — every DNS monitor

  • {"monitorType": "dns", "monitorId": "..."} — that one DNS monitor

  • {"monitorId": null} — back to team-wide

  • {"monitorId": "..."} — that one HTTP monitor

A monitorId that does not belong to the team, or that belongs to a different kind of monitor than monitorType names, answers 404 NOT_FOUND.

Example Request

cURL

curl -X PUT https://uptime.sergiodxa.com/api/v1/maintenance/mnt_abc123 \
  -H "Authorization: Bearer uptime_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Extended Database Migration",
    "endsAt": "2026-02-15T06:00:00Z"
  }'

Response

{
	"data": {
		"id": "mnt_abc123",
		"teamId": "team_xyz789",
		"monitorType": "http",
		"monitorId": "mon_def456",
		"name": "Extended Database Migration",
		"startsAt": "2026-02-15T02:00:00Z",
		"endsAt": "2026-02-15T06:00:00Z",
		"endedEarlyAt": null,
		"suppressAlerts": true,
		"showOnStatusPage": true,
		"createdAt": "2026-02-14T10:00:00Z",
		"updatedAt": "2026-02-14T11:30:00Z"
	}
}

Possible Errors

StatusCodeDescription
400VALIDATION_ERRORInvalid request body or validation failed
400INVALID_DATE_RANGEendsAt must be after startsAt
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key doesn't have maintenance:write scope
404NOT_FOUNDMaintenance window or monitor not found
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Request Body Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"properties": {
		"name": {
			"type": "string",
			"minLength": 1,
			"maxLength": 255
		},
		"startsAt": {
			"type": "string",
			"format": "date-time"
		},
		"endsAt": {
			"type": "string",
			"format": "date-time"
		},
		"monitorType": {
			"type": ["string", "null"],
			"enum": ["http", "dns", "tcp", "cron", null]
		},
		"monitorId": {
			"type": ["string", "null"],
			"pattern": "^mon_[a-zA-Z0-9]+$"
		},
		"suppressAlerts": {
			"type": "boolean"
		},
		"showOnStatusPage": {
			"type": "boolean"
		}
	}
}

Response Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": ["data"],
	"properties": {
		"data": {
			"type": "object",
			"required": [
				"id",
				"teamId",
				"monitorId",
				"name",
				"startsAt",
				"endsAt",
				"endedEarlyAt",
				"suppressAlerts",
				"showOnStatusPage",
				"createdAt",
				"updatedAt"
			],
			"properties": {
				"id": {
					"type": "string",
					"pattern": "^mnt_[a-zA-Z0-9]+$"
				},
				"teamId": {
					"type": "string",
					"pattern": "^team_[a-zA-Z0-9]+$"
				},
				"monitorType": {
					"type": ["string", "null"],
					"enum": ["http", "dns", "tcp", "cron", null]
				},
				"monitorId": {
					"type": ["string", "null"],
					"pattern": "^mon_[a-zA-Z0-9]+$"
				},
				"name": {
					"type": "string",
					"minLength": 1,
					"maxLength": 255
				},
				"startsAt": {
					"type": "string",
					"format": "date-time"
				},
				"endsAt": {
					"type": "string",
					"format": "date-time"
				},
				"endedEarlyAt": {
					"type": ["string", "null"],
					"format": "date-time"
				},
				"suppressAlerts": {
					"type": "boolean"
				},
				"showOnStatusPage": {
					"type": "boolean"
				},
				"createdAt": {
					"type": "string",
					"format": "date-time"
				},
				"updatedAt": {
					"type": "string",
					"format": "date-time"
				}
			}
		}
	}
}

DELETE /api/v1/maintenance/:id

Deletes a maintenance window.

Required Scope

maintenance:write

Example Request

cURL

curl -X DELETE https://uptime.sergiodxa.com/api/v1/maintenance/mnt_abc123 \
  -H "Authorization: Bearer uptime_your_api_key"

Response

Returns 204 No Content on success.

Possible Errors

StatusCodeDescription
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key doesn't have maintenance:write scope
404NOT_FOUNDMaintenance window not found
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Response Schema

Returns 204 No Content with an empty response body on success.

POST /api/v1/maintenance/:id/end

Ends a maintenance window early. Sets the endedEarlyAt timestamp to the current time.

Required Scope

maintenance:write

Example Request

cURL

curl -X POST https://uptime.sergiodxa.com/api/v1/maintenance/mnt_abc123/end \
  -H "Authorization: Bearer uptime_your_api_key"

Response

{
	"data": {
		"id": "mnt_abc123",
		"teamId": "team_xyz789",
		"monitorType": "http",
		"monitorId": "mon_def456",
		"name": "Database Migration",
		"startsAt": "2026-02-15T02:00:00Z",
		"endsAt": "2026-02-15T04:00:00Z",
		"endedEarlyAt": "2026-02-15T03:15:00Z",
		"suppressAlerts": true,
		"showOnStatusPage": true,
		"createdAt": "2026-02-14T10:00:00Z",
		"updatedAt": "2026-02-15T03:15:00Z"
	}
}

Possible Errors

StatusCodeDescription
400ALREADY_ENDEDMaintenance window has already ended
400NOT_STARTEDMaintenance window has not started yet
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key doesn't have maintenance:write scope
404NOT_FOUNDMaintenance window not found
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Response Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": ["data"],
	"properties": {
		"data": {
			"type": "object",
			"required": [
				"id",
				"teamId",
				"monitorId",
				"name",
				"startsAt",
				"endsAt",
				"endedEarlyAt",
				"suppressAlerts",
				"showOnStatusPage",
				"createdAt",
				"updatedAt"
			],
			"properties": {
				"id": {
					"type": "string",
					"pattern": "^mnt_[a-zA-Z0-9]+$"
				},
				"teamId": {
					"type": "string",
					"pattern": "^team_[a-zA-Z0-9]+$"
				},
				"monitorType": {
					"type": ["string", "null"],
					"enum": ["http", "dns", "tcp", "cron", null]
				},
				"monitorId": {
					"type": ["string", "null"],
					"pattern": "^mon_[a-zA-Z0-9]+$"
				},
				"name": {
					"type": "string",
					"minLength": 1,
					"maxLength": 255
				},
				"startsAt": {
					"type": "string",
					"format": "date-time"
				},
				"endsAt": {
					"type": "string",
					"format": "date-time"
				},
				"endedEarlyAt": {
					"type": ["string", "null"],
					"format": "date-time"
				},
				"suppressAlerts": {
					"type": "boolean"
				},
				"showOnStatusPage": {
					"type": "boolean"
				},
				"createdAt": {
					"type": "string",
					"format": "date-time"
				},
				"updatedAt": {
					"type": "string",
					"format": "date-time"
				}
			}
		}
	}
}

Response Fields

FieldTypeDescription
idstringUnique maintenance window identifier
teamIdstringTeam that owns this maintenance window
monitorTypestring | nullKind of monitor the window is limited to, or null if it applies to every kind
monitorIdstring | nullAssociated monitor ID, or null if applies to all monitors
namestringDisplay name of the maintenance window
startsAtintegerScheduled start time as a Unix timestamp in milliseconds
endsAtintegerScheduled end time as a Unix timestamp in milliseconds
endedEarlyAtinteger | nullWhen maintenance was ended early, in milliseconds, or null
suppressAlertsbooleanWhether alerts are suppressed during maintenance
showOnStatusPagebooleanWhether maintenance is displayed on the status page
createdAtintegerCreation time as a Unix timestamp in milliseconds
updatedAtintegerLast update time as a Unix timestamp in milliseconds