Team-Overrides

Diese Endpunkte verwalten alle Overrides eines Teams an einer Stelle:

• Team-Overrides (scheduleId: null) brauchen keinen Schedule. Sie gelten überall, wo die Bereitschaft des Teams aufgelöst wird (Alarmierung, Bereitschaft jetzt, Kalender), ein Team kann also allein über Overrides laufen.
• Schedule-Overrides (scheduleId gesetzt) sind dieselben Overrides wie unter Schedule-Overrides, nur über das Team angesprochen.

Felder und Bedeutung (type, Vertretungen, Geltungsbereich, Stufe, Vorrang) stehen unter Override-Felder. Diese Seite ergänzt ein Feld:

Ein offline-Team-Override nimmt die Person nur heraus, solange sie in dieser Stufe tatsächlich eine Schicht hat. Hat sie dort keine Bereitschaft, bewirkt er nichts.

AuthentifizierungAnkerlink kopieren

Basis-IM-Zugriff: eine IM-berechtigte Rolle oder ein organisationsweiter API-Token, und Incident Management für die Organisation aktiviert. Auflisten darf jeder mit diesem Zugriff. Hinzufügen, Ändern und Löschen brauchen die Team-Schreibhürde: Organisationsrolle admin, oder Team-Admin dieses Teams. 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.

Overrides auflistenAnkerlink kopieren

GET /api/im/teams/:id/overrides

Liefert alle Overrides des Teams, Team-Overrides und Schedule-Overrides, sortiert nach id.

Beispiel (cURL)Ankerlink kopieren

curl -X GET "$BASE_URL/api/im/teams/3/overrides" \
  -H "Authorization: Bearer $TOKEN"

Antwort (Response)Ankerlink kopieren

200 OK: dieselbe Eintragsform wie die Liste der Schedule-Overrides.

[
  {
    "id": 31,
    "scheduleId": null,
    "userId": "u_def456",
    "userName": "Bob Fixit",
    "userImage": null,
    "type": "online",
    "applyScope": "this_team",
    "escalationTierOrder": 1,
    "startsAt": "2026-12-24T18:00:00.000Z",
    "endsAt": "2026-12-26T08:00:00.000Z",
    "createdAt": "2026-10-09T10:00:00.000Z",
    "coveredBy": []
  }
]

Override hinzufügenAnkerlink kopieren

POST /api/im/teams/:id/overrides

Beispiel (cURL)Ankerlink kopieren

Bob übernimmt über Weihnachten Stufe 1:

curl -X POST "$BASE_URL/api/im/teams/3/overrides" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "u_def456",
    "type": "online",
    "escalationTierOrder": 1,
    "startsAt": "2026-12-24T18:00:00.000Z",
    "endsAt": "2026-12-26T08:00:00.000Z"
  }'

Antwort (Response)Ankerlink kopieren

200 OK

{
  "id": 31,
  "teamId": 3,
  "scheduleId": null,
  "userId": "u_def456",
  "type": "online",
  "applyScope": "this_team",
  "escalationTierOrder": 1,
  "startsAt": "2026-12-24T18:00:00.000Z",
  "endsAt": "2026-12-26T08:00:00.000Z",
  "createdAt": "2026-10-09T10:00:00.000Z",
  "coveredByUserIds": []
}

Override ändernAnkerlink kopieren

PATCH /api/im/teams/:id/overrides/:overrideId

Ein vollständiger Ersatz: Sende jedes Feld erneut. Das gilt auch für scheduleId: Lässt du es weg, wird aus einem Schedule-Override ein Team-Override. Änderst du es, wandert der Override zwischen Team-Ebene und einem Schedule des Teams. Der Override behält seine id und damit seinen Vorrang.

Beispiel (cURL)Ankerlink kopieren

curl -X PATCH "$BASE_URL/api/im/teams/3/overrides/31" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "u_def456",
    "type": "online",
    "escalationTierOrder": null,
    "scheduleId": null,
    "startsAt": "2026-12-24T18:00:00.000Z",
    "endsAt": "2026-12-27T08:00:00.000Z"
  }'

Antwort (Response)Ankerlink kopieren

200 OK: dieselbe Form wie beim Hinzufügen.

Override löschenAnkerlink kopieren

DELETE /api/im/teams/:id/overrides/:overrideId

Beispiel (cURL)Ankerlink kopieren

curl -X DELETE "$BASE_URL/api/im/teams/3/overrides/31" \
  -H "Authorization: Bearer $TOKEN"

Antwort (Response)Ankerlink kopieren

200 OK

{ "success": true }

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 Hinzufügen, Ändern oder Löschen, wenn du weder Organisations-Admin noch Team-Admin dieses Teams bist
• 404 Not Found (imTeamNotFound) wenn das Team nicht existiert oder zu einer anderen Organisation gehört
• 404 Not Found (imOverrideNotFound) wenn :overrideId kein Override dieses Teams ist
• 404 Not Found (imScheduleNotFound) wenn scheduleId kein Schedule dieses Teams ist
• 404 Not Found (userNotFound) wenn userId oder eine Vertretung nicht existiert oder zu einer anderen Organisation gehört
• 400 Bad Request (invalidRequestBody) wenn eine Pfad-ID keine positive Ganzzahl ist, scheduleId weder positive Ganzzahl noch null ist, oder ein Feld eine der unter Schedule-Overrides genannten Prüfungen nicht besteht
• 400 Bad Request (imUserNotEligible) wenn die betroffene Person oder eine Vertretung inaktiv ist oder nicht die Organisationsrolle admin, editor oder responder hat