---
title: Maintenance Windows API
description: Schedule and manage maintenance windows to suppress alerts during planned downtime via the Cronitor 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. {% .lead %}

## 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](/app/settings/api) page. For more information about API authentication and scopes, see the [API documentation](/docs/api).

---

## Quick Start

### Schedule a Maintenance Window
```bash
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
```bash
curl https://cronitor.io/api/maintenance_windows -u API_KEY:
```

### Update a Maintenance Window
```bash
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
```bash
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
```bash
curl https://cronitor.io/api/maintenance_windows -u API_KEY:
```

##### List Only Ongoing Maintenance Windows
```bash
curl "https://cronitor.io/api/maintenance_windows?ongoing=true" -u API_KEY:
```

##### List by Status Page
```bash
curl "https://cronitor.io/api/maintenance_windows?statuspage=sp_abc123def456" -u API_KEY:
```

#### Response
```json
{
  "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
```bash
POST https://cronitor.io/api/maintenance_windows
```

#### Request Body
```json
{
  "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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
GET https://cronitor.io/api/maintenance_windows/:key
```

#### Query Parameters
- **`withAllAffectedMonitors`** (boolean) - Include details of all affected monitors

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

#### Response with Affected Monitors
```json
{
  "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
```bash
PUT https://cronitor.io/api/maintenance_windows/:key
```

#### Request Body
```json
{
  "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
```bash
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
```bash
PATCH https://cronitor.io/api/maintenance_windows/:key
```

#### Example
```bash
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
```bash
DELETE https://cronitor.io/api/maintenance_windows/:key
```

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

---

## Examples

### Schedule Maintenance for Multiple Scopes
```bash
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
```bash
# 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:
```