Schedules (Bereitschaftspläne)

GET /api/im/schedules · POST /api/im/schedules

Ein Schedule (Bereitschaftsplan) gehört zu genau einem Team und definiert dessen On-Call-Rotation: eine oder mehrere Schichten von Usern, die jeweils daily, weekly oder custom rotieren, optional eingeschränkt auf bestimmte Tageszeiten. Ein Hintergrund-Worker materialisiert die Rotation etwa 90 Tage im Voraus zu konkreten Schichten (im_schedule_shift), genau die, die Wer hat Bereitschaft und die Eskalations-Engine zur Laufzeit tatsächlich lesen. Dieser Endpunkt verwaltet die Definition der Rotation, nicht direkt die materialisierten Schichten.

Authentifizierung

Erfordert den Basis-IM-Zugriff, den jeder Endpunkt dieser API benötigt (eine IM-berechtigte Rolle, oder einen organisationsweiten API-Token; Incident Management muss für die Organisation aktiviert sein). Das Auflisten steht jeder IM-berechtigten Rolle offen. Das Erstellen eines Schedules erfordert zusätzlich die Schreib-Hürde: Deine Rolle muss admin sein, oder du musst Team-Admin des Schedule-Teams sein. Ein organisationsweiter API-Token erfüllt die Organisations-Admin-Hürde.

Schedules auflisten

GET /api/im/schedules

Liefert jeden Schedule deiner Organisation, mit dem Namen des zugehörigen Teams.

Beispiel (cURL)

curl -X GET "$BASE_URL/api/im/schedules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Antwort (Response)

200 OK: ein Array, sortiert nach Name.

[
  {
    "id": 7,
    "organizationId": 1,
    "teamId": 3,
    "teamName": "Platform Team",
    "name": "Primary On-Call",
    "timezone": "Europe/Berlin",
    "rotation": [
      {
        "users": ["u_abc123", "u_def456"],
        "type": "weekly",
        "handoverTime": "09:00",
        "startDate": "2026-01-05"
      }
    ],
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
]

Schedule erstellen

POST /api/im/schedules

Request Body

Ein neu angelegter Schedule hat noch keine Rotation — er entsteht mit rotationMode: "none" und ohne Mitglieder. Kadenz und Mitglieder setzt du mit PATCH /api/im/schedules/:id (siehe unten); dieser Endpunkt nimmt sie nicht entgegen.

Rotationskadenz

Die Kadenz bestimmt, wie oft die Bereitschaft übergeben wird. Sie wird am Schedule per PATCH /api/im/schedules/:id gesetzt.

Die kürzeste mögliche Schicht ist eine Minute (customRepeatUnit: "minutes", customRepeatValue: 1). Übergabezeiten sind bei jeder Kadenz minutengenau, da startsOnTime eine "HH:mm"-Wanduhrzeit ist.

Kadenzen unterhalb eines Tages (minutes, hours) schreiten in absoluter Zeit voran, nicht nach Wanduhr. Über eine Zeitumstellung hinweg übergeben sie deshalb weiterhin alle N Minuten in Echtzeit, statt eine Stunde voller Übergaben zu verdoppeln oder zu überspringen.

Wie weit im Voraus Schichten erzeugt werden

Schichten werden rollierend bis zu 90 Tage im Voraus erzeugt. Eine schnelle Kadenz wird weniger weit vorausberechnet, denn die Zahl der Schichtzeilen ist Horizont geteilt durch Kadenz: Eine Ein-Minuten-Rotation über 90 Tage wären 129.600 Schichten pro Mitglied. Ein solcher Schedule wird stattdessen rund 41 Stunden im Voraus gehalten und stündlich nachgefüllt.

Das ist keine Abdeckungsgrenze. Die Alarmierung liest die aktuell laufende Schicht, und der Materializer läuft weit häufiger, als der Horizont schrumpft. Es bedeutet nur, dass eine Vorschau weit in die Zukunft bei schneller Kadenz kürzer ausfällt. Jede Kadenz ab einer Stunde behält die vollen 90 Tage.

Beispiel (cURL)

curl -X POST "$BASE_URL/api/im/schedules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": 3,
    "name": "Primary On-Call",
    "timezone": "Europe/Berlin",
    "rotation": [
      {
        "users": ["u_abc123", "u_def456"],
        "type": "weekly",
        "handoverTime": "09:00",
        "startDate": "2026-01-05"
      }
    ]
  }'

Antwort (Response)

200 OK: die neu erstellte Schedule-Zeile (gleiche Form wie oben in der Liste, ohne teamName).

Häufige Fehler

• 401 Unauthorized wenn du nicht authentifiziert bist
• 403 Forbidden (imAccessDenied) bei Verwendung eines kunden-gescopten Tokens, oder wenn deine Session keine IM-berechtigte Rolle hat
• 403 Forbidden (imNotEnabled) wenn Incident Management für die Organisation nicht aktiviert ist
• 403 Forbidden (imTeamWriteDenied) (nur beim Erstellen) wenn deine Rolle nicht admin ist und du kein Team-Admin von teamId bist
• 404 Not Found (imTeamNotFound) (nur beim Erstellen) wenn teamId nicht existiert oder zu einer anderen Organisation gehört
• 400 Bad Request (invalidRequestBody) (nur beim Erstellen) wenn name, timezone oder ein Rotationsschicht-Feld fehlt oder fehlerhaft ist (siehe Feldbeschreibungen oben), oder eine Schicht-/Restriktions-/User-Listen-Grenze überschritten wird