---
title: "Flag planned work on one monitor agent's server: no incident, no alert, no downtime"
method: POST
path: "/agents/{id}/maintenance"
tags: ["Agents"]
---

# Flag planned work on one monitor agent's server: no incident, no alert, no downtime

`POST /agents/{id}/maintenance`

## Request

- Base URL: `https://realuptime.io/api/v1`
- URL: `https://realuptime.io/api/v1/agents/{id}/maintenance`
- Auth: HTTP bearer

Accepts an account API key with read-write access to monitors, or the agent's own token with id set to the agent's id or to self. While the window is active the agent's offline and server-health alerts are withheld, and every check that runs from the agent, or whose target host is in hosts or is the host name the agent reports, opens no incident, sends nothing, and does not count against uptime. When the window ends, evaluation resumes from that moment: anything still down is reported then, never backdated. Posting while a window is active extends it to now plus minutes and adds the new hosts.

## Path parameters

- `id` union, required
  - string, uuid
  - 'self'

## Request body

- object
  - `minutes` integer, required
  - `reason` string
  - `hosts` string[]

## Response `201`

The active window.

- object
  - `window` object, nullable, required
    - `id` string, required
    - `agent_id` string, required
    - `starts_at` string, required
    - `ends_at` string, required
    - `reason` string, required
    - `hosts` string[], required
    - `opened_via` 'agent' | 'api' | 'dashboard', required

## Other responses

- `400`: Malformed body, or a host that is not a host name. - `RU-3001` Invalid check request: https://realuptime.io/kb/errors/ru-3001
- `401`: Missing, invalid, or revoked API key. - `RU-1001` Missing API credentials: https://realuptime.io/kb/errors/ru-1001 - `RU-1002` Invalid or revoked API key: https://realuptime.io/kb/errors/ru-1002
- `403`: This key is read-only, or this key is IP-restricted and the request came from outside its allowlist. - `RU-1004` API key is read-only: https://realuptime.io/kb/errors/ru-1004 - `RU-1007` API key is restricted to an IP allowlist: https://realuptime.io/kb/errors/ru-1007
- `404`: No such agent on this account. - `RU-3003` Check not found: https://realuptime.io/kb/errors/ru-3003
- `429`: Per-key rate limit exceeded, a Free account's per-account request budget exceeded, or too many failed authentication attempts. - `RU-2003` API write rate limit exceeded: https://realuptime.io/kb/errors/ru-2003 - `RU-2001` Too many failed authentication attempts: https://realuptime.io/kb/errors/ru-2001
- `503`: This server's database does not support planned work yet. Retry after the next release.

---

[API](https://skmtc.dev/realuptime/apis/realuptime-api-v1.md) · [All operations](https://skmtc.dev/realuptime/apis/realuptime-api-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/realuptime/apis/realuptime-api-v1/revisions/51e481084700?raw)