Create Maintenance Window

POST /api/maintenance-windows

Body

{
  "name": "Database migration",
  "startTime": "2026-07-10T22:00:00.000Z",
  "endTime": "2026-07-11T01:00:00.000Z",
  "targets": [
    { "type": "website", "id": 101 },
    { "type": "icmp", "id": 5 }
  ],
  "tagIds": [7],
  "description": "Planned schema migration",
  "isRecurring": false,
  "isActive": true
}

Required fields

• name (string): A friendly label for the window.
• startTime (ISO 8601 datetime): When the window begins.
• endTime (ISO 8601 datetime): When the window ends. Must be after startTime.
• At least one targeting field (see below).

Target selection (mutually exclusive modes)

Exactly one targeting mode must be used. targets and tagIds may be combined within the multi-monitor mode.

Tag-only (org-wide) mode

Sending tagIds without customerId, targets, or any legacy field creates an org-wide maintenance window. The window dynamically covers every monitor across the entire organization that currently carries the specified tags — across all customers.

{
  "name": "Infra tag freeze",
  "startTime": "2026-07-10T22:00:00.000Z",
  "endTime": "2026-07-11T01:00:00.000Z",
  "tagIds": [7]
}

• Requires admin or editor role. A readonly user attempting this receives 403 Forbidden.
• The tag membership is resolved live at check time — monitors tagged after the window is created are automatically covered.
• All tagIds must belong to the same organization; mixing tags from different organizations returns 400 mixedTagOrganizations.

Combination rules

• Minimum one targeting field is required. Omitting all is a Zod validation error (standard 400 with a validation body, not a data.code error).
• customerId (customer-level mode) cannot be combined with targets, tagIds, or any legacy field. Combining them is a Zod validation error (standard 400).
• All monitors in targets must belong to the same customer; mixing customers returns { data: { code: "mixedCustomers" } }.
• All tagIds must belong to the same organization; mixing organizations returns { data: { code: "mixedTagOrganizations" } }.

Optional fields

Recurrence

{
  "frequency": "weekly",
  "interval": 1,
  "daysOfWeek": [1, 3],
  "dayOfMonth": null,
  "endRecurrenceDate": "2026-12-31"
}

Dynamic tag behavior

Tag coverage is resolved live by the monitoring worker at check time. A monitor tagged after the window is created is automatically covered — no window update needed. Removing a tag from a monitor drops it from coverage immediately.

Example (cURL)

BASE_URL="https://uptimeify.io"
TOKEN="<your-api-token>"

curl -X POST "$BASE_URL/api/maintenance-windows" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Database migration",
    "startTime": "2026-07-10T22:00:00.000Z",
    "endTime": "2026-07-11T01:00:00.000Z",
    "targets": [
      { "type": "website", "id": 101 }
    ]
  }'

Response

{
  "id": 42,
  "publicId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "organizationId": 10,
  "customerId": 1,
  "name": "Database migration",
  "description": null,
  "startTime": "2026-07-10T22:00:00.000Z",
  "endTime": "2026-07-11T01:00:00.000Z",
  "isRecurring": false,
  "recurrencePattern": null,
  "isActive": true,
  "targets": [
    { "type": "website", "id": 101 }
  ],
  "tags": [],
  "websiteId": null,
  "icmpMonitorId": null,
  "smtpMonitorId": null,
  "sshMonitorId": null,
  "ftpMonitorId": null,
  "imapPopMonitorId": null,
  "dnsMonitorId": null,
  "customerIpId": null,
  "customerDomainId": null,
  "createdAt": "2026-06-29T10:00:00.000Z",
  "updatedAt": "2026-06-29T10:00:00.000Z"
}

Common errors