Create Maintenance Window

Overview

Create a maintenance window to suppress alerts during planned maintenance periods. Maintenance windows can be one-time events or recurring schedules, and can target specific checks or entire check groups.

Request Examples

{
  "name": "Production API Deployment",
  "startsAt": "2024-02-15T20:00:00.000Z",
  "endsAt": "2024-02-15T22:00:00.000Z",
  "repeatInterval": "NONE",
  "tags": ["deployment", "api", "production"],
  "checkIds": [
    "check_api_health",
    "check_api_auth",
    "check_api_users"
  ],
  "checkGroupIds": [
    "group_production_api"
  ]
}

Response Example

{
  "id": "mw_789123456",
  "name": "Production API Deployment",
  "startsAt": "2024-02-15T20:00:00.000Z",
  "endsAt": "2024-02-15T22:00:00.000Z",
  "repeatInterval": "NONE",
  "repeatEndsAt": null,
  "tags": ["deployment", "api", "production"],
  "checkIds": [
    "check_api_health",
    "check_api_auth",
    "check_api_users"
  ],
  "checkGroupIds": [
    "group_production_api"
  ],
  "createdAt": "2024-01-25T10:30:00.000Z",
  "updatedAt": "2024-01-25T10:30:00.000Z"
}

Configuration Options

Basic Settings

Required Fields:

name (string): Descriptive name for the maintenance window
startsAt (string): ISO 8601 timestamp when maintenance begins
endsAt (string): ISO 8601 timestamp when maintenance ends
repeatInterval (string): NONE, DAILY, WEEKLY, or MONTHLY

Optional Fields:

repeatEndsAt (string): When recurring maintenance should stop (required for recurring windows)
tags (array): Tags for organization and filtering

Repeat Intervals

NONE (One-time):

Single maintenance window
No repeat configuration needed

DAILY:

Repeats every day at the same time
Requires repeatEndsAt to define when to stop

WEEKLY:

Repeats on the same day of the week
Based on the day of startsAt
Requires repeatEndsAt

MONTHLY:

Repeats on the same date each month
Based on the date of startsAt
Requires repeatEndsAt

Important: For recurring windows, the duration is calculated from the initial startsAt and endsAt, then applied to each recurrence.

Resource Targeting

Individual Checks:

{
  "checkIds": [
    "check_api_health",
    "check_database_ping",
    "check_frontend_load"
  ]
}

Check Groups:

{
  "checkGroupIds": [
    "group_production_api",
    "group_database_cluster"
  ]
}

Combined Targeting:

{
  "checkIds": ["check_special_case"],
  "checkGroupIds": ["group_main_services"]
}

Note: You can target specific checks, entire check groups, or both in the same maintenance window.

Timezone Considerations

All timestamps should be in UTC (ISO 8601 format with Z suffix). Consider these factors:

Server Timezones: Convert local maintenance times to UTC
Daylight Saving: UTC avoids DST complications
Global Teams: UTC provides consistent scheduling across regions

Example Conversion:

// Convert local time to UTC
const localTime = new Date('2024-02-15 20:00:00'); // Local time
const utcTime = localTime.toISOString(); // "2024-02-15T20:00:00.000Z"

Code Examples

curl -X POST "https://api.checklyhq.com/v1/maintenance-windows" \
  -H "Authorization: Bearer cu_1234567890abcdef" \
  -H "X-Checkly-Account: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Emergency Database Maintenance",
    "startsAt": "2024-02-20T02:00:00.000Z",
    "endsAt": "2024-02-20T04:00:00.000Z",
    "repeatInterval": "NONE",
    "tags": ["emergency", "database"],
    "checkGroupIds": ["group_database_monitoring"]
  }'

Validation Rules

Time Validation

endsAt must be after startsAt
repeatEndsAt must be after startsAt (for recurring windows)
Minimum duration: 1 minute
Maximum duration: 7 days per window
Cannot create windows that started in the past

Resource Validation

At least one checkId or checkGroupId must be specified
Check IDs must exist and belong to your account
Check Group IDs must exist and belong to your account
Cannot exceed 100 checks per maintenance window

Repeat Validation

repeatEndsAt is required for DAILY, WEEKLY, and MONTHLY intervals
repeatEndsAt is ignored for NONE interval
Maximum repeat duration: 1 year
Recurring windows cannot exceed 1000 occurrences

Best Practices

Naming Conventions

Use descriptive names that include:

Purpose: What maintenance is being performed
Frequency: One-time, weekly, monthly, etc.
Scope: Which systems are affected

Examples:

“Monthly Security Patch Tuesday”
“Weekly Database Backup Window”
“Q1 Infrastructure Upgrade”
“Emergency API Hotfix Deployment”

Scheduling Strategy

Buffer Time: Add 15-30 minutes buffer before and after expected maintenance
Timezone Awareness: Use UTC to avoid DST issues
Overlap Prevention: Avoid overlapping maintenance windows
Communication: Coordinate with team schedules and business hours

Resource Targeting

Group-Based: Use check groups for easier management
Granular Control: Target specific checks only when necessary
Impact Assessment: Consider downstream dependencies
Testing: Test maintenance windows in non-production first

Recurring Maintenance

End Dates: Always set appropriate repeatEndsAt dates
Review Schedule: Regularly review and update recurring windows
Seasonal Adjustments: Account for holidays and business cycles
Cleanup: Remove expired recurring maintenance windows

Maintenance windows are crucial for preventing alert fatigue during planned downtime. They ensure your team focuses on real issues rather than expected maintenance notifications.

Authorizations

Authorization

string

header

required

The Checkly Public API uses API keys to authenticate requests. You can get the API Key here.

Your API key is like a password: keep it secure!

Authentication to the API is performed using the Bearer auth method in the Authorization header and using the account ID.

For example, set Authorization header while using cURL:

curl -H "Authorization: Bearer [apiKey]" "X-Checkly-Account: [accountId]"

Headers

x-checkly-account

string

Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general

Body

application/json

name

string

required

The maintenance window name.

Example:

"Maintenance Window"

startsAt

string<date>

required

The start date of the maintenance window.

Example:

"2022-08-24"

endsAt

string<date>

required

The end date of the maintenance window.

Example:

"2022-08-25"

repeatUnit

string

required

The repeat strategy for the maintenance window.

Example:

"DAY"

Response

Created

number

required

The id of the maintenance window.

Example:

1

name

string

required

The maintenance window name.

Example:

"Maintenance Window"

startsAt

string<date>

required

The start date of the maintenance window.

Example:

"2022-08-24"

endsAt

string<date>

required

The end date of the maintenance window.

Example:

"2022-08-25"

repeatUnit

string

required

The repeat strategy for the maintenance window.

Example:

"DAY"

created_at

string<date>

required

The creation date of the maintenance window.

updated_at

string<date>

required

The last date that the maintenance window was updated.

Platform

Detect

Communicate

Resolve

Create Maintenance Window

Overview

Request Examples

Response Example

Configuration Options

Code Examples

Validation Rules

Best Practices

Authorizations

Headers

Body

Response

Platform

Detect

Communicate

Resolve

​Overview

​Request Examples

​Response Example

​Configuration Options

​Code Examples

​Validation Rules

​Best Practices

Authorizations

Headers

Body

Response

Overview

Request Examples

Response Example

Configuration Options

Code Examples

Validation Rules

Best Practices