Maintenance Windows API

The Maintenance Windows API allows you to programmatically schedule and manage maintenance windows that suppress alerts during planned downtime. Maintenance windows can affect individual monitors, groups of monitors, or entire status pages.

Authentication

The Maintenance Windows API requires API key authentication with issue management scopes:

• issue:read - Required to list and retrieve maintenance windows
• issue:write - Required to create, update, and delete maintenance windows

Create an API key with the appropriate scopes from the API Settings page. For more information about API authentication and scopes, see the API documentation.

Quick Start

Schedule a Maintenance Window

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "name": "Database Maintenance",
        "start": "2023-12-01T02:00:00Z",
        "end": "2023-12-01T04:00:00Z"
    }' \
    https://cronitor.io/api/maintenance_windows

List All Maintenance Windows

curl https://cronitor.io/api/maintenance_windows -u API_KEY:

Update a Maintenance Window

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request PUT \
    --data '{
        "name": "Extended Database Maintenance",
        "start": "2023-12-01T02:00:00Z",
        "end": "2023-12-01T06:00:00Z"
    }' \
    https://cronitor.io/api/maintenance_windows/mw_abc123def456

Maintenance Windows

List Maintenance Windows

Retrieve all maintenance windows for your organization.

Endpoint

GET https://cronitor.io/api/maintenance_windows

Query Parameters

• past (boolean) - Include past maintenance windows
• ongoing (boolean) - Include only ongoing maintenance windows
• upcoming (boolean) - Include only upcoming maintenance windows
• statuspage (string) - Filter by status page key
• env (string) - Filter by environment key
• withAllAffectedMonitors (boolean) - Include details of all affected monitors

Examples

List All Maintenance Windows

curl https://cronitor.io/api/maintenance_windows -u API_KEY:

List Only Ongoing Maintenance Windows

curl "https://cronitor.io/api/maintenance_windows?ongoing=true" -u API_KEY:

List by Status Page

curl "https://cronitor.io/api/maintenance_windows?statuspage=sp_abc123def456" -u API_KEY:

Response

{
  "page": 1,
  "page_count": 1,
  "page_size": 50,
  "total_count": 3,
  "data": [
    {
      "key": "mw_abc123def456",
      "name": "Database Maintenance",
      "description": "Monthly database optimization",
      "start": "2023-12-01T02:00:00Z",
      "end": "2023-12-01T04:00:00Z",
      "duration": 7200,
      "state": "upcoming",
      "environment": "production",
      "affects_all_monitors": false,
      "affects_statuspage_components": true,
      "statuspages": ["sp_abc123def456"],
      "monitors": ["mon_abc123"],
      "groups": ["grp_web_services"],
      "all_affected_monitors": null,
      "created": "2023-11-15T10:00:00Z",
      "updated": "2023-11-15T10:00:00Z"
    }
  ]
}

Create Maintenance Window

Schedule a new maintenance window.

Endpoint

POST https://cronitor.io/api/maintenance_windows

Request Body

{
  "name": "Database Maintenance",
  "description": "Monthly database optimization and cleanup",
  "start": "2023-12-01T02:00:00Z",
  "end": "2023-12-01T04:00:00Z",
  "environment": "production",
  "affects_all_monitors": false,
  "affects_statuspage_components": true,
  "statuspages": ["sp_abc123def456"],
  "monitors": ["mon_abc123", "mon_def456"],
  "groups": ["grp_web_services"]
}

Examples

Basic Maintenance Window

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "name": "Server Maintenance",
        "start": "2023-12-01T02:00:00Z",
        "end": "2023-12-01T04:00:00Z"
    }' \
    https://cronitor.io/api/maintenance_windows

Maintenance Window for Specific Monitors

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "name": "API Maintenance",
        "description": "Upgrading API servers",
        "start": "2023-12-01T02:00:00Z",
        "end": "2023-12-01T04:00:00Z",
        "monitors": ["api_monitor_1", "api_monitor_2"]
    }' \
    https://cronitor.io/api/maintenance_windows

Maintenance Window for Status Page

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "name": "Status Page Maintenance",
        "start": "2023-12-01T02:00:00Z",
        "end": "2023-12-01T04:00:00Z",
        "statuspages": ["sp_abc123def456"],
        "affects_statuspage_components": true
    }' \
    https://cronitor.io/api/maintenance_windows

Maintenance Window Affecting All Monitors

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "name": "Infrastructure Maintenance",
        "description": "Network infrastructure upgrade",
        "start": "2023-12-01T02:00:00Z",
        "end": "2023-12-01T06:00:00Z",
        "affects_all_monitors": true
    }' \
    https://cronitor.io/api/maintenance_windows

Maintenance Window Detail

Get Maintenance Window

Retrieve details for a specific maintenance window.

Endpoint

GET https://cronitor.io/api/maintenance_windows/:key

Query Parameters

• withAllAffectedMonitors (boolean) - Include details of all affected monitors

Example

curl "https://cronitor.io/api/maintenance_windows/mw_abc123def456?withAllAffectedMonitors=true" -u API_KEY:

Response with Affected Monitors

{
  "key": "mw_abc123def456",
  "name": "Database Maintenance",
  "description": "Monthly database optimization",
  "start": "2023-12-01T02:00:00Z",
  "end": "2023-12-01T04:00:00Z",
  "duration": 7200,
  "state": "upcoming",
  "environment": "production",
  "affects_all_monitors": false,
  "affects_statuspage_components": true,
  "statuspages": ["sp_abc123def456"],
  "monitors": ["mon_abc123"],
  "groups": ["grp_web_services"],
  "all_affected_monitors": [
    {
      "key": "mon_abc123",
      "name": "Database Connection Monitor"
    },
    {
      "key": "mon_def456",
      "name": "API Response Monitor"
    }
  ],
  "created": "2023-11-15T10:00:00Z",
  "updated": "2023-11-15T10:00:00Z"
}

Update Maintenance Window

Update an existing maintenance window.

Endpoint

PUT https://cronitor.io/api/maintenance_windows/:key

Request Body

{
  "name": "Extended Database Maintenance",
  "description": "Extended maintenance window for major upgrades",
  "start": "2023-12-01T02:00:00Z",
  "end": "2023-12-01T06:00:00Z",
  "monitors": ["mon_abc123", "mon_def456", "mon_ghi789"]
}

Example

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request PUT \
    --data '{
        "name": "Extended Database Maintenance",
        "end": "2023-12-01T06:00:00Z"
    }' \
    https://cronitor.io/api/maintenance_windows/mw_abc123def456

Partial Update Maintenance Window

Partially update a maintenance window using PATCH.

Endpoint

PATCH https://cronitor.io/api/maintenance_windows/:key

Example

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request PATCH \
    --data '{"description": "Updated maintenance description"}' \
    https://cronitor.io/api/maintenance_windows/mw_abc123def456

Delete Maintenance Window

Cancel a maintenance window (marks as not visible).

Endpoint

DELETE https://cronitor.io/api/maintenance_windows/:key

Example

curl --user API_KEY: \
    --request DELETE \
    https://cronitor.io/api/maintenance_windows/mw_abc123def456

Examples

Schedule Maintenance for Multiple Scopes

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "name": "Comprehensive Maintenance",
        "description": "Maintenance affecting multiple systems",
        "start": "2023-12-01T02:00:00Z",
        "end": "2023-12-01T06:00:00Z",
        "monitors": ["api_monitor", "db_monitor"],
        "groups": ["web_services"],
        "statuspages": ["sp_main"],
        "affects_statuspage_components": true
    }' \
    https://cronitor.io/api/maintenance_windows

Filter Maintenance Windows by Time

# Get only upcoming maintenance windows
curl "https://cronitor.io/api/maintenance_windows?upcoming=true" -u API_KEY:

# Get ongoing maintenance windows for a specific status page
curl "https://cronitor.io/api/maintenance_windows?ongoing=true&statuspage=sp_main" -u API_KEY: