> For the complete documentation index, see [llms.txt](https://docs.visualsentinel.com/llms.txt)

# Maintenance API

Scheduled maintenance windows. This page lists all 6 endpoints in the Maintenance area of the Visual Sentinel REST API.

Base URL: `https://visualsentinel.com`. Unless an endpoint says otherwise it accepts an API key or a session cookie, see [Authentication](https://docs.visualsentinel.com/guides/authentication.md). Most error responses use the [ErrorResponse](https://docs.visualsentinel.com/reference/models/error-response.md) shape, see [Errors](https://docs.visualsentinel.com/guides/errors.md) and [Rate limits](https://docs.visualsentinel.com/guides/rate-limits.md).

## Endpoints

- [List maintenance windows](#list-maintenance-windows): `GET /api/maintenance`
- [Create maintenance window](#create-maintenance-window): `POST /api/maintenance`
- [Get maintenance window](#get-maintenance-window): `GET /api/maintenance/{id}`
- [Update maintenance window](#update-maintenance-window): `PATCH /api/maintenance/{id}`
- [Delete maintenance window](#delete-maintenance-window): `DELETE /api/maintenance/{id}`
- [Cancel maintenance window](#cancel-maintenance-window): `POST /api/maintenance/{id}/cancel`

## List maintenance windows

`GET /api/maintenance`

List maintenance windows that occur between `from` and `to` (default: 90 days ago to about a year ahead).

**Parameters**

- `from` (query, string (date-time), optional)
- `to` (query, string (date-time), optional)
- `status` (query, string, optional): One of: `scheduled`, `in-progress`, `completed`, `cancelled`.

**Responses**

- `200`: Maintenance windows. Body: object.
- `400`: Invalid `from` or `to`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `maintenanceWindows` | array of [MaintenanceWindow](https://docs.visualsentinel.com/reference/models/maintenance-window.md) | No |   |

## Create maintenance window

`POST /api/maintenance`

Schedule a maintenance window. Alerts for the linked monitors are suppressed while it is active, and status pages show it.

Request body (required): [CreateMaintenanceWindowRequest](https://docs.visualsentinel.com/reference/models/create-maintenance-window-request.md).

**Responses**

- `200`: Maintenance window created. Body: object.
- `400`: `title`, `startTime` or `endTime` missing or invalid, end not after start, longer than 90 days, or an unknown `recurrenceKind`.
- `403`: Read-only role or an API key without `maintenance:write`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `maintenanceWindow` | [MaintenanceWindow](https://docs.visualsentinel.com/reference/models/maintenance-window.md) | No |   |
| `message` | string | No |   |

## Get maintenance window

`GET /api/maintenance/{id}`

Get details of a specific maintenance window.

**Parameters**

- `id` (path, string (uuid), required)

**Responses**

- `200`: Maintenance window details.

## Update maintenance window

`PATCH /api/maintenance/{id}`

Update a maintenance window. Send only the fields that change.

**Parameters**

- `id` (path, string (uuid), required)

Request body (required): [UpdateMaintenanceWindowRequest](https://docs.visualsentinel.com/reference/models/update-maintenance-window-request.md).

**Responses**

- `200`: Maintenance window updated. Body: object.
- `400`: Invalid dates, end not after start, longer than 90 days, or an unknown `recurrenceKind`.
- `404`: Maintenance window not found.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `maintenanceWindow` | object | No |   |
| `maintenanceWindow.id` | string (uuid) | No |   |
| `maintenanceWindow.title` | string | No |   |
| `message` | string | No |   |

## Delete maintenance window

`DELETE /api/maintenance/{id}`

Delete a maintenance window.

**Parameters**

- `id` (path, string (uuid), required)

**Responses**

- `200`: Maintenance window deleted.

## Cancel maintenance window

`POST /api/maintenance/{id}/cancel`

Cancel a window. For a repeating window, `action: "skip-next"` skips one occurrence (the next one, or `occurrence`) and `action: "stop-repeating"` turns it into a one-off; without an action the whole window is cancelled.

**Parameters**

- `id` (path, string (uuid), required)

Request body (optional): object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `action` | string | No | One of: `skip-next`, `stop-repeating`. |
| `occurrence` | string (date-time) | No | With `skip-next`: the future occurrence start to skip. |

**Responses**

- `200`: Done. Body: object.
- `400`: No next occurrence to skip.
- `404`: Maintenance window not found.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ok` | boolean | No |   |

## Data models

Request and response shapes these endpoints use: [MaintenanceWindow](https://docs.visualsentinel.com/reference/models/maintenance-window.md), [CreateMaintenanceWindowRequest](https://docs.visualsentinel.com/reference/models/create-maintenance-window-request.md), [UpdateMaintenanceWindowRequest](https://docs.visualsentinel.com/reference/models/update-maintenance-window-request.md).

Generated from the OpenAPI 3.1 specification at [https://docs.visualsentinel.com/openapi.json](https://docs.visualsentinel.com/openapi.json), the same file the interactive reference reads.