# Maintenance API

The Uptizm API has 5 endpoints on this resource, one section each.

## List maintenance windows

`GET /scheduled-maintenances`

The team's maintenance windows, newest window first, cursor-paginated.

- URL: `https://api.uptizm.com/v1/scheduled-maintenances`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `maintenance:read`
- Tag: Maintenance
- operationId: `scheduled-maintenances.index`

### Parameters

- `per_page` (query, integer, min 1, max 200): Page size, clamped to 1 and the endpoint's maximum (200 on most lists).
- `cursor` (query, string): The `meta.next_cursor` of the previous page.

### Response 200

Content type: `application/json`.

- `data` (array of ScheduledMaintenanceResource, required)
  - `id` (string, required)
  - `team_id` (string, required)
  - `status_page_id` (string, required)
  - `title` (string, required)
  - `description` (string or null, required)
  - `suppress_alerts` (boolean, required)
  - `starts_at` (string, required)
  - `ends_at` (string, required)
  - `announced_at` (string or null, required)
  - `monitors` (array of object)
    - `monitor_id` (string, required)
    - `name` (string, required)
  - `created_at` (string or null, required)
  - `updated_at` (string or null, required)
- `links` (object, required)
  - `first` (string or null, required)
  - `last` (string or null, required)
  - `prev` (string or null, required)
  - `next` (string or null, required)
- `meta` (object, required)
  - `path` (string or null, required): Base path for paginator generated URLs.
  - `per_page` (integer, min 0, required): Number of items shown per page.
  - `next_cursor` (string or null, required): The "cursor" that points to the next set of items.
  - `prev_cursor` (string or null, required): The "cursor" that points to the previous set of items.

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Plan a maintenance window

`POST /scheduled-maintenances`

Plans a window on a status page and announces it to the page's confirmed subscribers. While a window is open, incidents on its monitors are held back.

- URL: `https://api.uptizm.com/v1/scheduled-maintenances`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `maintenance:write`
- Tag: Maintenance
- operationId: `scheduled-maintenances.store`

### Parameters

- `Idempotency-Key` (header, string): Any unique string per logical request.

### Request body

Content type: `application/json`.

- `status_page_id` (string, uuid, required)
- `title` (string, max length 200, required)
- `description` (string or null, max length 2000)
- `suppress_alerts` (boolean)
- `starts_at` (string, date-time, required)
- `ends_at` (string, date-time, required)
- `monitor_ids` (array of string, uuid)

### Response 201

Content type: `application/json`.

- `data` (ScheduledMaintenanceResource and object, required)
  - `id` (string, required)
  - `team_id` (string, required)
  - `status_page_id` (string, required)
  - `title` (string, required)
  - `description` (string or null, required)
  - `suppress_alerts` (boolean, required)
  - `starts_at` (string, required)
  - `ends_at` (string, required)
  - `announced_at` (string or null, required)
  - `monitors` (array of object, required)
    - `monitor_id` (string, required)
    - `name` (string, required)
  - `created_at` (string or null, required)
  - `updated_at` (string or null, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 422: Validation error
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Get a maintenance window

`GET /scheduled-maintenances/{maintenance}`

One window with its affected components.

- URL: `https://api.uptizm.com/v1/scheduled-maintenances/{maintenance}`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `maintenance:read`
- Tag: Maintenance
- operationId: `scheduled-maintenances.show`

### Parameters

- `maintenance` (path, string, required): The maintenance ID

### Response 200

Content type: `application/json`.

- `data` (ScheduledMaintenanceResource and object, required)
  - `id` (string, required)
  - `team_id` (string, required)
  - `status_page_id` (string, required)
  - `title` (string, required)
  - `description` (string or null, required)
  - `suppress_alerts` (boolean, required)
  - `starts_at` (string, required)
  - `ends_at` (string, required)
  - `announced_at` (string or null, required)
  - `monitors` (array of object, required)
    - `monitor_id` (string, required)
    - `name` (string, required)
  - `created_at` (string or null, required)
  - `updated_at` (string or null, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 404: Not found
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Update a maintenance window

`PUT /scheduled-maintenances/{maintenance}`

Updates the window.

- URL: `https://api.uptizm.com/v1/scheduled-maintenances/{maintenance}`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `maintenance:write`
- Tag: Maintenance
- operationId: `scheduled-maintenances.update`

### Parameters

- `maintenance` (path, string, required): The maintenance ID

### Request body

Content type: `application/json`.

- `status_page_id` (string, uuid)
- `title` (string, max length 200)
- `description` (string or null, max length 2000)
- `suppress_alerts` (boolean)
- `starts_at` (string, date-time)
- `ends_at` (string, date-time)
- `monitor_ids` (array of string, uuid)

### Response 200

Content type: `application/json`.

- `data` (ScheduledMaintenanceResource and object, required)
  - `id` (string, required)
  - `team_id` (string, required)
  - `status_page_id` (string, required)
  - `title` (string, required)
  - `description` (string or null, required)
  - `suppress_alerts` (boolean, required)
  - `starts_at` (string, required)
  - `ends_at` (string, required)
  - `announced_at` (string or null, required)
  - `monitors` (array of object, required)
    - `monitor_id` (string, required)
    - `name` (string, required)
  - `created_at` (string or null, required)
  - `updated_at` (string or null, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 404: Not found
- 422: Validation error
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Delete a maintenance window

`DELETE /scheduled-maintenances/{maintenance}`

Deletes the window.

- URL: `https://api.uptizm.com/v1/scheduled-maintenances/{maintenance}`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `maintenance:write`
- Tag: Maintenance
- operationId: `scheduled-maintenances.destroy`

### Parameters

- `maintenance` (path, string, required): The maintenance ID

### Response 204

No body.

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 404: Not found
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md