---
title: "Maintenance Window erstellen"
description: "Erstellt ein neues Wartungsfenster. Unterstützt einen einzelnen Monitor (Legacy), mehrere Monitore, tag-basiertes (inkl. organisationsweit) oder kunden-weites Targeting."
---

`POST /api/maintenance-windows`

## Body

```json
{
  "name": "Datenbank-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": "Geplante Schema-Migration",
  "isRecurring": false,
  "isActive": true
}
```

### Pflichtfelder

- `name` (string): Eine freundliche Bezeichnung für das Fenster.
- `startTime` (ISO 8601 Datetime): Zeitpunkt, an dem das Fenster beginnt.
- `endTime` (ISO 8601 Datetime): Zeitpunkt, an dem das Fenster endet. Muss nach `startTime` liegen.
- **Mindestens ein Zielfeld** (siehe unten).

### Zielauswahl (gegenseitig ausschließende Modi)

Genau ein Targeting-Modus muss verwendet werden. `targets` und `tagIds` können innerhalb des Multi-Monitor-Modus kombiniert werden.

| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `websiteId` | number | Legacy: einzelner Website-Monitor |
| `icmpMonitorId` | number | Legacy: einzelner ICMP-Monitor |
| `smtpMonitorId` | number | Legacy: einzelner SMTP-Monitor |
| `sshMonitorId` | number | Legacy: einzelner SSH-Monitor |
| `ftpMonitorId` | number | Legacy: einzelner FTP-Monitor |
| `imapPopMonitorId` | number | Legacy: einzelner IMAP/POP-Monitor |
| `dnsMonitorId` | number | Legacy: einzelner DNS-Monitor |
| `customerIpId` | number | Legacy: einzelne Kunden-IP |
| `customerDomainId` | number | Legacy: einzelne Kunden-Domain |
| `targets` | `{ type, id }[]` | Multi-Monitor: `type` ist eines von `website` \| `dns` \| `icmp` \| `smtp` \| `ssh` \| `ftp` \| `imap_pop` |
| `tagIds` | number[] | Tag-basiert: siehe [Nur-Tag-Modus (organisationsweit)](#nur-tag-modus-organisationsweit) |
| `customerId` | number | Kunden-Ebene: deckt jeden Monitor dieses Kunden ab |

### Nur-Tag-Modus (organisationsweit)

Wird `tagIds` **ohne** `customerId`, `targets` oder Legacy-Felder gesendet, entsteht ein **organisationsweites** Wartungsfenster. Es deckt dynamisch jeden Monitor der gesamten Organisation ab, der aktuell die angegebenen Tags trägt, über alle Kunden hinweg.

```json
{
  "name": "Infra-Tag-Freeze",
  "startTime": "2026-07-10T22:00:00.000Z",
  "endTime": "2026-07-11T01:00:00.000Z",
  "tagIds": [7]
}
```

- **Erfordert Admin- oder Editor-Rolle.** Readonly-Benutzer, die dies versuchen, erhalten `403 Forbidden`.
- Die Tag-Zugehörigkeit wird live zur Prüfzeit aufgelöst: nach der Fenstererstellung getaggte Monitore werden automatisch abgedeckt.
- Alle `tagIds` müssen zur selben Organisation gehören; das Mischen von Tags verschiedener Organisationen gibt `400 mixedTagOrganizations` zurück.

### Kombinationsregeln

- **Mindestens ein** Zielfeld ist erforderlich. Das Weglassen aller Felder ist ein Zod-Validierungsfehler (Standard-`400` mit Validierungsantwort, **kein** `data.code`-Fehler).
- **`customerId` (Kunden-Ebene-Modus)** kann nicht mit `targets`, `tagIds` oder Legacy-Feldern kombiniert werden. Das Kombinieren ist ein Zod-Validierungsfehler (Standard-`400`).
- Alle Monitore in `targets` müssen zum **selben Kunden** gehören; das Mischen von Kunden gibt `{ data: { code: "mixedCustomers" } }` zurück.
- Alle `tagIds` müssen zur selben Organisation gehören; das Mischen gibt `{ data: { code: "mixedTagOrganizations" } }` zurück.

### Optionale Felder

| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `description` | string | Freitext-Notizen (erscheinen in der Historie). |
| `isRecurring` | boolean | Standard `false`. Auf `true` setzen, um `recurrencePattern` zu aktivieren. |
| `recurrencePattern` | object | Erforderlich, wenn `isRecurring` `true` ist. Siehe [Wiederholung](#wiederholung). |
| `isActive` | boolean | Standard `true`. Auf `false` setzen, um ein deaktiviertes Fenster zu erstellen. |
| `timezone` | string | Standard `"UTC"`. Die IANA-Zeitzone (z. B. `"Europe/Berlin"`), in der das Wiederholungsmuster interpretiert wird. Schreibweisen unabhängig von Groß-/Kleinschreibung sowie veraltete IANA-Linknamen (z. B. `"gmt"`, `"Zulu"`) werden akzeptiert und unter der kanonischen Bezeichnung des Laufzeitsystems gespeichert, `"utc"` und `"Zulu"` werden beide als `"UTC"` gespeichert. Ein reiner UTC-Offset (z. B. `"+05:00"`) wird abgewiesen: Er enthält keine Sommerzeit-Regel und kann daher nicht leisten, was ein Zonenname leistet. |

### Wiederholung

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

| Feld | Werte |
|------|-------|
| `frequency` | `daily` \| `weekly` \| `monthly` |
| `interval` | Ganzzahl ≥ 1 (Wiederholung alle N Perioden) |
| `daysOfWeek` | Array von `0`-`6` (0 = Sonntag); verwendet wenn `frequency` `weekly` ist |
| `dayOfMonth` | `1`-`31`; verwendet wenn `frequency` `monthly` ist |
| `endRecurrenceDate` | ISO-Datumsstring; optional, beendet die Wiederholung nach diesem Datum |

## Dynamisches Tag-Verhalten

Die Tag-Abdeckung wird vom Monitoring-Worker live zum Zeitpunkt der Prüfung aufgelöst. Ein Monitor, der *nach* der Fenstererstellung getaggt wird, wird automatisch abgedeckt, ohne das Fenster zu aktualisieren. Das Entfernen eines Tags von einem Monitor beendet die Abdeckung sofort.

## Beispiel (cURL)

```bash
BASE_URL="https://uptimeify.io"
TOKEN="<dein-api-token>"

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

## Antwort (Response)

```json
{
  "id": 42,
  "publicId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "organizationId": 10,
  "customerId": 1,
  "name": "Datenbank-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"
}
```

## Häufige Fehler

| Status | Beschreibung |
|--------|--------------|
| `400` (Validierung) | Kein Zielfeld angegeben, `customerId` mit anderen Zielfeldern kombiniert, oder `timezone` ist ein reiner UTC-Offset oder kein vom Laufzeitsystem erkannter Zonenname. Dies sind Zod-Validierungsfehler; der Response-Body ist ein Standard-Validierungsfehler, **kein** `{ data: { code } }`. |
| `400` `{ data: { code: "mixedCustomers" } }` | `targets` enthält Monitore verschiedener Kunden. |
| `400` `{ data: { code: "mixedTagOrganizations" } }` | `tagIds` enthält Tags aus verschiedenen Organisationen. |
| `401 Unauthorized` | Nicht angemeldet. |
| `403 Forbidden` | Kein Zugriff auf die Organisation, das Ziel liegt außerhalb des Bereichs (globale Support-Konten können keine Wartungsfenster erstellen), oder der Benutzer ist readonly und versucht ein organisationsweites Nur-Tag-Fenster zu erstellen. |
| `404` `{ data: { code: "tagNotFound" } }` | Eine `tagId` existiert nicht in der Organisation. |