Create Maintenance Window

POST /api/maintenance-windows

BodyCopy Anchor Link

{
  "name": "Database migration",
  "startTime": "2026-07-10T22:00:00.000Z",
  "endTime": "2026-07-11T01:00:00.000Z",
  "targets": [
    { "type": "website", "id": "ef8a6564-0ccf-4f3f-a5ef-d2963176b3eb" },
    { "type": "icmp", "id": "3d005a18-fdd8-4dc7-9f26-1a9d409c1bc5" }
  ],
  "tagIds": [7],
  "description": "Planned schema migration",
  "isRecurring": false,
  "isActive": true
}

Required fieldsCopy Anchor Link

• 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)Copy Anchor Link

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

Tag-only (org-wide) modeCopy Anchor Link

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 an organization-wide admin or editor: the role AND an unrestricted customer scope. A customer-bound actor (a readonly user, an editor assigned to customers, a customer-scoped token) does not get an org-wide window: when it is bound to exactly one customer, the window is anchored to that customer and covers only that customer's tagged monitors; when it is bound to several (or none), the request is rejected with 400 tagOnlyNeedsCustomer and it must select monitors or a customer instead. See Roles and the customer scope.
• 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 rulesCopy Anchor Link

• 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 fieldsCopy Anchor Link

RecurrenceCopy Anchor Link

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

Dynamic tag behaviorCopy Anchor Link

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)Copy Anchor Link

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 }
    ]
  }'

ResponseCopy Anchor Link

{
  "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,
  "timezone": "UTC",
  "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 errorsCopy Anchor Link