Schedules (Bereitschaftspläne)

Ein Schedule (Bereitschaftsplan) gehört zu einem Team und einer seiner Eskalationsstufen. Zeitzone, Gültigkeitszeitraum, Wochenfenster, Rotationskadenz und Rotationsgruppen bestimmen, wer wann Schicht hat. Ein Hintergrund-Worker macht daraus konkrete Schichten bis zu 90 Tage im Voraus; Alarmierung, Wer hat Bereitschaft und der Team-Kalender lesen diese Schichten. Diese Endpunkte verwalten die Definition, nicht die Schichten.

Die Rotation konfigurierst du mit Schedule aktualisieren, oder du legst einen fertig konfigurierten Schedule in einem Aufruf mit Schedule zu einer Stufe hinzufügen an. Schedule-Vorschau zeigt die entstehenden Schichten.

AuthentifizierungAnkerlink kopieren

Basis-IM-Zugriff: eine IM-berechtigte Rolle (admin, editor oder responder) oder ein organisationsweiter API-Token, und Incident Management für die Organisation aktiviert. Auflisten und Lesen darf jeder mit diesem Zugriff. Anlegen und Löschen brauchen die Team-Schreibhürde für das Team des Schedules: Organisationsrolle admin, oder Team-Admin. Ein API-Token läuft mit der Rolle des Users, der ihn erstellt hat, also kommt nur ein Token durch, den ein Organisations-Admin erstellt hat.

Schedules auflistenAnkerlink kopieren

GET /api/im/schedules

Liefert jeden Schedule deiner Organisation, sortiert nach Name.

Query-ParameterAnkerlink kopieren

Beispiel (cURL)Ankerlink kopieren

curl -X GET "$BASE_URL/api/im/schedules?envelope=items" \
  -H "Authorization: Bearer $TOKEN"

Antwort (Response)Ankerlink kopieren

200 OK

{
  "items": [
    {
      "id": 7,
      "organizationId": 1,
      "teamId": 3,
      "teamName": "Platform Team",
      "name": "Primary On-Call",
      "timezone": "Europe/Berlin",
      "tierId": 21,
      "createdAt": "2026-06-02T08:00:00.000Z",
      "updatedAt": "2026-09-14T10:12:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "perPage": 1
}

Listenform: Mit envelope=items kommt die Liste als { items, total, page, perPage }. Ohne den Parameter antwortet der Endpunkt noch in der bisherigen Form (ein blankes Array derselben Schedules); sie ist veraltet, ab dem 18.01.2027 ist { items, ... } der Standard.

Schedule lesenAnkerlink kopieren

GET /api/im/schedules/:id

Liefert die vollständige Konfiguration des Schedules, sein Team und seine Overrides (gleiche Eintragsform wie unter Schedule-Overrides). rotations listet die Rotationsgruppen mit ihren Mitgliedern (mit userImage), in derselben Form wie schedules[].rotations beim Stufe lesen; sie sind außerdem Teil der Eskalationskette des Teams.

Beispiel (cURL)Ankerlink kopieren

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

Antwort (Response)Ankerlink kopieren

200 OK

{
  "id": 7,
  "organizationId": 1,
  "teamId": 3,
  "tierId": 21,
  "name": "Primary On-Call",
  "timezone": "Europe/Berlin",
  "effectiveFrom": null,
  "effectiveUntil": null,
  "weeklySchedules": [],
  "rotationMode": "explicit",
  "rotationRepeats": "weekly",
  "customRepeatUnit": null,
  "customRepeatValue": null,
  "autoRotationSize": null,
  "roundRobinSize": 1,
  "roundRobinCursor": 4,
  "startsOnDayOfWeek": 1,
  "startsOnDateOfMonth": null,
  "startsOnTime": "09:00",
  "createdAt": "2026-06-02T08:00:00.000Z",
  "updatedAt": "2026-09-14T10:12:00.000Z",
  "team": { "id": 3, "name": "Platform Team" },
  "overrides": [],
  "rotations": [
    {
      "id": 31,
      "rotationOrder": 1,
      "members": [
        { "userId": "usr_abc", "userName": "Alex Example", "userImage": null, "memberOrder": 1 }
      ]
    }
  ]
}

roundRobinCursor ist ein interner Zähler für die Round-Robin-Alarmierung und lässt sich nicht setzen.

Schedule erstellenAnkerlink kopieren

POST /api/im/schedules

Legt einen leeren Schedule unter einer Stufe an: 24/7, rotationMode: "none", keine Rotationsgruppen. Er alarmiert niemanden, bis du mit Schedule aktualisieren Rotationsgruppen hinzufügst.

Anfrage (Request Body)Ankerlink kopieren

Beispiel (cURL)Ankerlink kopieren

curl -X POST "$BASE_URL/api/im/schedules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "teamId": 3, "tierId": 21, "name": "Primary On-Call", "timezone": "Europe/Berlin" }'

Antwort (Response)Ankerlink kopieren

200 OK: der neue Schedule, dieselben Felder wie bei Schedule lesen, ohne team und overrides.

Schedule löschenAnkerlink kopieren

DELETE /api/im/schedules/:id

Löscht den Schedule samt Rotationsgruppen, Overrides und Schichten.

Beispiel (cURL)Ankerlink kopieren

curl -X DELETE "$BASE_URL/api/im/schedules/7" \
  -H "Authorization: Bearer $TOKEN"

Antwort (Response)Ankerlink kopieren

200 OK

{ "success": true }

RotationskadenzAnkerlink kopieren

Die Kadenz bestimmt, wie oft die Bereitschaft übergeben wird. Du setzt sie mit Schedule aktualisieren oder beim Hinzufügen eines Schedules zu einer Stufe.

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

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 werdenAnkerlink kopieren

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. Nur eine Vorschau weit in die Zukunft fällt bei schneller Kadenz kürzer aus. Jede Kadenz ab einer Stunde behält die vollen 90 Tage.

Häufige FehlerAnkerlink kopieren

• 401 Unauthorized (unauthorized) wenn du nicht authentifiziert bist
• 403 Forbidden (imAccessDenied) bei einem kunden-gescopten Token, 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) beim Anlegen oder Löschen, wenn du weder Organisations-Admin noch Team-Admin des Teams bist
• 404 Not Found (imScheduleNotFound) wenn :id nicht existiert oder zu einer anderen Organisation gehört
• 404 Not Found (imTeamNotFound) beim Anlegen, wenn teamId nicht existiert oder zu einer anderen Organisation gehört
• 400 Bad Request (invalidRequestBody) wenn :id keine positive Ganzzahl ist, oder beim Anlegen, wenn teamId oder tierId fehlt oder keine positive Ganzzahl ist, tierId keine Stufe von teamId ist, name fehlt oder länger als 120 Zeichen ist, oder timezone fehlt oder keine gültige IANA-Zone ist