Create Maintenance Window

Create a new maintenance window to suppress alerts during planned downtime

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

One-time Deployment

{
  "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

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.