Preview Maintenance Occurrences

Computes the upcoming occurrences of a (not-yet-saved) recurrence pattern, without creating a window.

POST /api/maintenance-windows/preview-occurrences

Pure computation: this endpoint never touches the database. It runs the same zone-aware recurrence engine the alert-suppression path uses (occurrencesInRange), so the preview can never drift from what a saved window with the same startTime/endTime/recurrencePattern/ timezone will actually suppress. Useful for showing "what does this pattern mean" before submitting Create Maintenance Window or Update Maintenance Window.

Body

{
  "startTime": "2026-08-10T02:00:00.000Z",
  "endTime": "2026-08-10T03:00:00.000Z",
  "isRecurring": true,
  "recurrencePattern": {
    "frequency": "weekly",
    "interval": 1,
    "daysOfWeek": [1, 3]
  },
  "timezone": "Europe/Berlin"
}

Fields

Field	Type	Description
`startTime`	ISO 8601 datetime	Required. Start of the first occurrence.
`endTime`	ISO 8601 datetime	Required. End of the first occurrence. Must be after `startTime`.
`isRecurring`	boolean	Required. When `false`, the response contains only the single anchor occurrence.
`recurrencePattern`	object	Required when `isRecurring` is `true`. Same shape as Create Maintenance Window.
`timezone`	string	Default `"UTC"`. The IANA zone the pattern is interpreted in, same validation and canonicalization as the `timezone` field on create/update.

The response returns at most 5 upcoming occurrences, looking forward up to 5 years from the current time.

Example (cURL)

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

curl -X POST "$BASE_URL/api/maintenance-windows/preview-occurrences" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "startTime": "2026-08-10T02:00:00.000Z",
    "endTime": "2026-08-10T03:00:00.000Z",
    "isRecurring": true,
    "recurrencePattern": { "frequency": "weekly", "interval": 1, "daysOfWeek": [1, 3] },
    "timezone": "Europe/Berlin"
  }'

Response

{
  "occurrences": [
    { "start": "2026-08-10T00:00:00.000Z", "end": "2026-08-10T01:00:00.000Z" },
    { "start": "2026-08-12T00:00:00.000Z", "end": "2026-08-12T01:00:00.000Z" },
    { "start": "2026-08-17T00:00:00.000Z", "end": "2026-08-17T01:00:00.000Z" }
  ]
}

occurrences may be an empty array (e.g. a recurrence pattern whose endRecurrenceDate has already passed relative to the preview horizon).

Sending isRecurring: true without a recurrencePattern is not an error. The window is treated as non-recurring and the response contains only the single occurrence described by startTime and endTime, the same fallback the recurrence engine applies to a malformed pattern.

Common errors

Status	Description
`400` (validation)	`timezone` is a raw UTC offset or not a zone name the runtime recognizes. Standard Zod validation error body, not `{ data: { code } }`.
`400` `{ data: { code: "invalidWindow" } }`	`endTime` is not after `startTime`.
`401 Unauthorized`	Not logged in.