Maintenance Windows API

Schedule and manage planned maintenance windows through the Ionhour REST API, suppressing alerts and incident creation while you work on the affected services.

Maintenance windows let you suppress alerts and incidents during planned downtime. See Maintenance Windows for conceptual documentation.

These are dashboard API endpoints — they require an OAuth session token ($ACCESS_TOKEN) and do not accept ionh_ API keys. To open and close maintenance windows from CI/CD or an external system with an API key, use the Integration API (POST /api/v1/maintenance-windows), where endAt acts as a natural TTL that auto-completes the window. See which credential goes where.

Create Maintenance Window

POST /maintenance-windows

Request Body

Field	Type	Required	Description
`workspaceId`	number	Yes	Workspace this window belongs to
`name`	string	Yes	Window name
`description`	string	No	Description of the maintenance activity
`startAt`	string	Yes	ISO datetime when maintenance begins
`endAt`	string	Yes	ISO datetime when maintenance ends
`projectIds`	number[]	Yes	Projects affected by this maintenance
`suppressAlerts`	boolean	No	Suppress alert notifications (default: true)
`suppressIncidents`	boolean	No	Suppress incident creation (default: true)
`autoPublishToStatusPage`	boolean	No	Auto-publish to status page (default: false)
`timezone`	string	No	Timezone for start/end times (default: `UTC`)
`recurringCron`	string	No	Cron expression for recurring windows (`null` = one-time)

Example

curl -X POST https://api.ionhour.com/api/maintenance-windows \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": 1,
    "name": "Database migration - March 2025",
    "description": "Upgrading PostgreSQL from 15 to 16",
    "startAt": "2025-03-15T02:00:00Z",
    "endAt": "2025-03-15T04:00:00Z",
    "projectIds": [1, 3],
    "suppressAlerts": true,
    "suppressIncidents": true,
    "autoPublishToStatusPage": true
  }'

List Maintenance Windows

GET /maintenance-windows

Query Parameters

Parameter	Type	Required	Description
`workspaceId`	number	Yes	Filter by workspace
`state`	string	No	Filter by state: `SCHEDULED`, `ACTIVE`, `COMPLETED`, `CANCELLED`

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.ionhour.com/api/maintenance-windows?workspaceId=1&state=SCHEDULED"

Get Maintenance Window

GET /maintenance-windows/:id

Returns a window with its target projects.

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://api.ionhour.com/api/maintenance-windows/1

Update Maintenance Window

PUT /maintenance-windows/:id

Updates a maintenance window. Only SCHEDULED windows can be modified — ACTIVE, COMPLETED, and CANCELLED windows are immutable.

curl -X PUT https://api.ionhour.com/api/maintenance-windows/1 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"endAt": "2025-03-15T06:00:00Z"}'

Cancel Maintenance Window

POST /maintenance-windows/:id/cancel

Cancels a scheduled or active maintenance window. Suppression stops immediately.

curl -X POST https://api.ionhour.com/api/maintenance-windows/1/cancel \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Delete Maintenance Window

DELETE /maintenance-windows/:id

curl -X DELETE https://api.ionhour.com/api/maintenance-windows/1 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Window States

State	Description
`SCHEDULED`	Created but not yet active. Can be modified or cancelled.
`ACTIVE`	Currently in effect. Suppression is active for targeted projects.
`COMPLETED`	End time has passed. Suppression no longer active.
`CANCELLED`	Manually cancelled. Suppression stopped immediately.

Maintenance Windows API

On this page