---
title: "Create a maintenance window"
method: POST
path: "/maintenance-windows"
tags: ["Maintenance windows"]
---

# Create a maintenance window

`POST /maintenance-windows`

## Request

- Base URL: `https://api.spectate.net/v1`
- URL: `https://api.spectate.net/v1/maintenance-windows`
- Auth: HTTP bearer

One-off with `starts_at` and `ends_at`, or weekly with `schedule`. Targets must belong to the
team (`422` otherwise).

## Request body

- CreateMaintenanceWindow: A new window: one-off with `starts_at` and `ends_at`, or weekly with `schedule`, never both.
  - `name` string, required: Name, up to 255 characters
  - `reason` string, nullable: Why, for the team; up to 500 characters
  - `starts_at` string, date-time, nullable: A one-off window's start
  - `ends_at` string, date-time, nullable: A one-off window's end, after `starts_at` and in the future
  - `schedule` MaintenanceWindowSchedule: When a weekly window runs. An end time before the start time runs past midnight.
    - `timezone` string, required: Time zone of the times. The window follows the clock in this zone across daylight saving
    - `days` integer[], required: Days it starts on: 1 is Monday, 7 is Sunday
    - `start_time` string, required: Start time, `HH:MM`
    - `end_time` string, required: End time, `HH:MM`
  - `repeat_until` string, date, nullable: A weekly window's last date, in its time zone
  - `covers_everything` boolean: `true`: covers everything in the team. Default `false`
  - `exclude_from_uptime` boolean: `false`: failed checks during the window count as downtime. Default `true`
  - `targets` MaintenanceWindowTargetInput[]: What it covers, at most 200, from the team. Required unless `covers_everything` is `true`
    - `type` 'monitor' | 'host' | 'domain' | 'alert_source' | 'project', required: What a maintenance window can cover.
    - `id` string, uuid, required: Its ID

## Response `201`

The new window.

- MaintenanceWindow: Planned work. While a window runs, alerts on what it covers are muted, and failed checks don't count as downtime unless `exclude_from_uptime` is `false`.
  - `id` string, uuid, required: Window ID
  - `name` string, required: Name
  - `reason` string, nullable, required: Why, for the team; `null` for none
  - `starts_at` string, date-time, nullable, required: A one-off window's start; `null` for a weekly window
  - `ends_at` string, date-time, nullable, required: A one-off window's end; `null` for a weekly window
  - `schedule` MaintenanceWindowSchedule, required: When a weekly window runs. An end time before the start time runs past midnight.
    - `timezone` string, required: Time zone of the times. The window follows the clock in this zone across daylight saving
    - `days` integer[], required: Days it starts on: 1 is Monday, 7 is Sunday
    - `start_time` string, required: Start time, `HH:MM`
    - `end_time` string, required: End time, `HH:MM`
  - `repeat_until` string, date, nullable, required: A weekly window's last date, in its time zone; `null` for no last date
  - `covers_everything` boolean, required: `true`: covers everything in the team, and `targets` is ignored
  - `exclude_from_uptime` boolean, required: `true`: failed checks during the window don't count as downtime
  - `active` boolean, required: `true` while it runs
  - `paused_at` string, date-time, nullable, required: When it was paused; `null` if it isn't. A paused window covers nothing
  - `next_start_at` string, date-time, nullable, required: When the current or next occurrence starts; `null` when none is to come
  - `current_end_at` string, date-time, nullable, required: When the running occurrence ends; `null` when it isn't running
  - `targets` MaintenanceWindowTarget[], required: What it covers
    - `type` 'monitor' | 'host' | 'domain' | 'alert_source' | 'project', required: What a maintenance window can cover.
    - `id` string, uuid, required: Its ID
    - `name` string, required: Its name
  - `created_at` string, date-time, required: When it was created

## Other responses

- `401`: `UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.
- `403`: `FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.
- `422`: `VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.
- `429`: `RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.

---

[API](https://skmtc.dev/spectate/apis/spectate-api.md) - [All operations](https://skmtc.dev/spectate/apis/spectate-api/llms.txt) - [OpenAPI document](https://skmtc.dev/spectate/apis/spectate-api/revisions/9b1a233997de?raw)