Schedules (Bereitschaftspläne)

Incident-Management-Bereitschaftspläne auflisten und erstellen: die Rotation, die festlegt, wer für ein Team wann Bereitschaft hat.

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

Feld	Typ	Erforderlich	Beschreibung
`teamId`	number	Ja	Das Team, dem der Schedule gehört. Muss zu deiner Organisation gehören.
`name`	string	Ja	Name des Schedules, bis zu 120 Zeichen.
`timezone`	string	Ja	IANA-Zeitzone (z. B. `Europe/Berlin`). Jede Übergabe und tageszeitliche Einschränkung wird in dieser Zone ausgewertet, auch über die Sommerzeit hinweg.
`rotation`	array	Nein	Rotationsschichten, bis zu 20. Standard ist ein leeres Array (ein Schedule ohne Rotation alarmiert niemanden, bis Schichten hinzugefügt werden). Jede Schicht: `{ users: string[], type: 'daily' \| 'weekly' \| 'custom', intervalDays?: number, handoverTime: "HH:mm", startDate: "yyyy-MM-dd", restrictions?: Array<{ dow: number[], from: "HH:mm", to: "HH:mm" }> }`. `intervalDays` ist erforderlich (und nur relevant), wenn `type` `custom` ist. `dow` in `restrictions` nutzt ISO-Wochentage (1 = Montag .. 7 = Sonntag), bis zu 30 Restriktionen pro Schicht. Bis zu 200 User pro Schicht.

Jede User-ID in rotation[].users muss zu deiner Organisation gehören. Eine Rotation, die einen organisationsfremden User nennt, wird strikt abgelehnt statt stillschweigend verworfen, da im_schedule_shift.user_id selbst keine Organisationsgrenze kennt.

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

Schedules (Bereitschaftspläne)

Auf dieser Seite