Maintenance Windows API

Maintenance windows allow you to schedule planned downtime for your monitors. During a maintenance window, the monitor will not trigger alerts even if it goes down.

All maintenance window endpoints require authentication. Include the Authorization: Bearer {token} header with all requests.

Maintenance Window Status

Status	Description
`SCHEDULED`	Maintenance window is scheduled but hasn't started yet
`IN_PROGRESS`	Maintenance window is currently active
`COMPLETED`	Maintenance window has ended
`CANCELLED`	Maintenance window was cancelled before completion

List Maintenance Windows

GET/api/maintenance-windows

Retrieve all maintenance windows for the authenticated user's monitors

Headers:

Header	Value
Authorization	`Bearer {access_token}`

Success Response (200 OK):

{
  "maintenanceWindows": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "monitor_id": "monitor-uuid",
      "monitor_name": "Production API",
      "title": "Database Migration",
      "start_time": "2024-01-20T02:00:00Z",
      "end_time": "2024-01-20T04:00:00Z",
      "status": "SCHEDULED",
      "created_by": "user-uuid",
      "created_at": "2024-01-15T10:00:00Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "monitor_id": "monitor-uuid-2",
      "monitor_name": "Database Server",
      "title": "Security Patch Update",
      "start_time": "2024-01-18T00:00:00Z",
      "end_time": "2024-01-18T01:00:00Z",
      "status": "COMPLETED",
      "created_by": "user-uuid",
      "created_at": "2024-01-14T08:00:00Z"
    }
  ]
}

Maintenance windows are sorted by start time in descending order (most recent first).

Create Maintenance Window

POST/api/maintenance-windows

Schedule a new maintenance window

Headers:

Header	Value
Authorization	`Bearer {access_token}`
Content-Type	application/json

Request Body:

Field	Type	Required	Validation
`monitor_id`	UUID	Yes	Must be a monitor owned by the user
`title`	string	Yes	1-200 characters
`start_time`	ISO 8601	Yes	Valid datetime
`end_time`	ISO 8601	Yes	Must be after start_time

Request Example:

{
  "monitor_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Database Migration - v2.5",
  "start_time": "2024-01-20T02:00:00Z",
  "end_time": "2024-01-20T04:00:00Z"
}

Success Response (201 Created):

{
  "maintenanceWindow": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "monitor_id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Database Migration - v2.5",
    "start_time": "2024-01-20T02:00:00Z",
    "end_time": "2024-01-20T04:00:00Z",
    "status": "SCHEDULED",
    "created_by": "user-uuid",
    "created_at": "2024-01-15T10:00:00Z"
  }
}

If the current time is within the maintenance window (start_time has passed but end_time hasn't), the status is automatically set to IN_PROGRESS.

Error Responses:

Status	Error	Description
400	Validation errors	Invalid request body
400	`End time must be after start time`	Invalid time range
404	`Monitor not found`	Monitor doesn't exist or not owned by user

Cancel Maintenance Window

PUT/api/maintenance-windows/:id/cancel

Cancel a scheduled or in-progress maintenance window

Path Parameters:

Parameter	Type	Description
`id`	UUID	Maintenance window ID

Headers:

Header	Value
Authorization	`Bearer {access_token}`

Success Response (200 OK):

{
  "maintenanceWindow": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "monitor_id": "monitor-uuid",
    "title": "Database Migration - v2.5",
    "start_time": "2024-01-20T02:00:00Z",
    "end_time": "2024-01-20T04:00:00Z",
    "status": "CANCELLED",
    "created_by": "user-uuid",
    "created_at": "2024-01-15T10:00:00Z"
  }
}

Error Responses:

Status	Error	Description
404	`Maintenance window not found or already completed`	Invalid ID, not owned by user, or status is COMPLETED

Only maintenance windows with status SCHEDULED or IN_PROGRESS can be cancelled. Completed maintenance windows cannot be cancelled.

Delete Maintenance Window

DELETE/api/maintenance-windows/:id

Permanently delete a maintenance window

Path Parameters:

Parameter	Type	Description
`id`	UUID	Maintenance window ID

Headers:

Header	Value
Authorization	`Bearer {access_token}`

Success Response (200 OK):

{
  "success": true
}

Error Responses:

Status	Error	Description
404	`Maintenance window not found`	Invalid ID or not owned by user

How Maintenance Windows Work

Alert Suppression

During an active maintenance window:

The monitor continues to run checks as normal
If the monitor goes down, no alerts are sent
Incidents are still created for tracking purposes
The status page shows the monitor as "Under Maintenance"

Status Transitions

SCHEDULED → IN_PROGRESS → COMPLETED
         ↘             ↙
           CANCELLED

Transition	Trigger
SCHEDULED → IN_PROGRESS	start_time is reached
IN_PROGRESS → COMPLETED	end_time is reached
SCHEDULED → CANCELLED	User cancels
IN_PROGRESS → CANCELLED	User cancels during maintenance

Best Practices

Schedule in advance - Create maintenance windows well before the planned work
Be conservative with timing - Add buffer time before and after actual work
Use descriptive titles - Include version numbers, ticket IDs, or brief descriptions
Cancel if not needed - Don't leave unnecessary maintenance windows active

Example Workflows

Schedule Weekly Maintenance

// Schedule every Sunday at 3 AM UTC for 2 hours
const response = await fetch('/api/maintenance-windows', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    monitor_id: 'your-monitor-uuid',
    title: 'Weekly Maintenance - Week 3',
    start_time: '2024-01-21T03:00:00Z',
    end_time: '2024-01-21T05:00:00Z'
  })
});

Cancel Due to Postponement

// Cancel a maintenance window if work is postponed
const response = await fetch('/api/maintenance-windows/' + maintenanceId + '/cancel', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer ' + token
  }
});

Error Responses Summary

Status	Error	Description
400	Validation errors	Invalid request body
400	`End time must be after start time`	Invalid time range
404	`Monitor not found`	Monitor doesn't exist or not owned
404	`Maintenance window not found`	Window doesn't exist or not owned
404	`Maintenance window not found or already completed`	Can't cancel completed windows
500	`Failed to create/cancel/delete maintenance window`	Server error