1. docs
  2. api
  3. resources
  4. maintenance
Start Monitoring

Maintenance Windows

Schedule and manage maintenance windows. Suppress alerts during planned downtime.Last updated: 2026-02-14

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.

GET /v1/maintenance

Returns a list of all maintenance windows for your team.

Required Scope

maintenance:read

Example Request

cURL

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

Response

{
	"data": [
		{
			"id": "mnt_abc123",
			"teamId": "team_xyz789",
			"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
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": "array",
			"items": {
				"$ref": "#/$defs/maintenanceWindow"
			}
		}
	},
	"$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]+$"
				},
				"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"
				}
			}
		}
	}
}

POST /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)
monitorIdstring | nullNoMonitor ID to apply maintenance to, or null for all monitors
suppressAlertsbooleanNoWhether to suppress alerts during maintenance (default: true)
showOnStatusPagebooleanNoWhether to show maintenance on status page (default: true)

Example Request

cURL

curl -X POST https://api.uptime.example.com/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",
    "monitorId": "mon_def456",
    "suppressAlerts": true,
    "showOnStatusPage": true
  }'

Response

{
	"data": {
		"id": "mnt_abc123",
		"teamId": "team_xyz789",
		"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 with specified monitorId not found
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"
		},
		"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]+$"
				},
				"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 /v1/maintenance/:id

Returns a single maintenance window by ID.

Required Scope

maintenance:read

Example Request

cURL

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

Response

{
	"data": {
		"id": "mnt_abc123",
		"teamId": "team_xyz789",
		"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]+$"
				},
				"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 /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)
monitorIdstring | nullNoMonitor ID to apply maintenance to, or null for all monitors
suppressAlertsbooleanNoWhether to suppress alerts during maintenance
showOnStatusPagebooleanNoWhether to show maintenance on status page

Example Request

cURL

curl -X PUT https://api.uptime.example.com/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",
		"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"
		},
		"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]+$"
				},
				"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 /v1/maintenance/:id

Deletes a maintenance window.

Required Scope

maintenance:write

Example Request

cURL

curl -X DELETE https://api.uptime.example.com/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 /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://api.uptime.example.com/v1/maintenance/mnt_abc123/end \
  -H "Authorization: Bearer uptime_your_api_key"

Response

{
	"data": {
		"id": "mnt_abc123",
		"teamId": "team_xyz789",
		"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]+$"
				},
				"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
monitorIdstring | nullAssociated monitor ID, or null if applies to all monitors
namestringDisplay name of the maintenance window
startsAtstringScheduled start time in ISO 8601 format
endsAtstringScheduled end time in ISO 8601 format
endedEarlyAtstring | nullTime when maintenance was ended early, or null
suppressAlertsbooleanWhether alerts are suppressed during maintenance
showOnStatusPagebooleanWhether maintenance is displayed on the status page
createdAtstringCreation timestamp in ISO 8601 format
updatedAtstringLast update timestamp in ISO 8601 format