Teams

Ein Team ist die oberste Besitz-Einheit in Incident Management: Eskalationsstufen, Schedules, Overrides und Incidents gehören jeweils zu genau einem Team. Diese Seite behandelt das Team selbst. Mitglieder stehen unter Team-Mitglieder, die Eskalationskette unter Eskalationsstufen.

AuthentifizierungAnkerlink kopieren

Jeder Endpunkt braucht den Basis-IM-Zugriff: eine IM-berechtigte Rolle (admin, editor oder responder) oder einen organisationsweiten API-Token, und Incident Management muss für die Organisation aktiviert sein. Lesen darf jeder mit diesem Zugriff.

Schreiben braucht mehr:

• Anlegen braucht die Organisationsrolle admin.
• Ändern und Löschen brauchen die Team-Schreibhürde: Organisationsrolle admin, oder Team-Admin (imRole: "admin") dieses Teams.

Ein API-Token läuft mit der Rolle des Users, der ihn erstellt hat. Nur ein Token, den ein Organisations-Admin erstellt hat, nimmt eine der beiden Schreibhürden.

Teams einer anderen Organisation antworten immer mit 404, nie mit 403.

Teams auflistenAnkerlink kopieren

GET /api/im/teams

Liefert jedes Team deiner Organisation, sortiert nach Name, mit Mitgliederzahl und einer kurzen Mitgliederliste.

Beispiel (cURL)Ankerlink kopieren

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

Antwort (Response)Ankerlink kopieren

200 OK

[
  {
    "id": 3,
    "name": "Platform Team",
    "labelColor": "#4f46e5",
    "analyticsEnabled": true,
    "createdAt": "2026-06-02T08:00:00.000Z",
    "memberCount": 2,
    "members": [
      { "userId": "u_abc123", "name": "Ada Lovelace", "email": "ada@example.com", "src": null },
      { "userId": "u_def456", "name": "Bob Fixit", "email": "bob@example.com", "src": "https://uptimeify.io/avatars/u_def456.png" }
    ]
  }
]

members[].email ist nur für Organisations-Admins gefüllt (und für Tokens, die einer von ihnen erstellt hat). Alle anderen bekommen null, und ein Mitglied ohne Anzeigenamen hat dann einen leeren name. src ist die Avatar-URL des Mitglieds oder null.

Team lesenAnkerlink kopieren

GET /api/im/teams/:id

Liefert das Team, seine Einstellungen und seine Mitglieder samt Benachrichtigungsbereitschaft.

Beispiel (cURL)Ankerlink kopieren

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

Antwort (Response)Ankerlink kopieren

200 OK

{
  "id": 3,
  "name": "Platform Team",
  "labelColor": "#4f46e5",
  "analyticsEnabled": true,
  "organizationId": 1,
  "createdAt": "2026-06-02T08:00:00.000Z",
  "updatedAt": "2026-09-14T10:12:00.000Z",
  "timezone": "Europe/Berlin",
  "escalationRepeats": 1,
  "escalationRepeatsAfterMinutes": 15,
  "escalationRepeatsStopMode": "acknowledged",
  "engagementReportEnabled": true,
  "engagementReportDayOfWeek": 1,
  "engagementReportTime": "09:00",
  "members": [
    {
      "id": 17,
      "userId": "u_abc123",
      "imRole": "admin",
      "user": {
        "name": "Ada Lovelace",
        "email": "ada@example.com",
        "image": null,
        "phone": "+4915112345678",
        "activeChannels": ["email", "push", "sms"],
        "phoneVerified": true,
        "notificationRules": {
          "high": { "hasPushRule": true, "hasSmsRule": true, "hasVoiceRule": false, "hasEmailRule": true },
          "low": { "hasPushRule": true, "hasSmsRule": false, "hasVoiceRule": false, "hasEmailRule": true }
        }
      }
    }
  ]
}

• members[].id ist die Mitgliedschafts-ID, die Team-Mitglieder in seinen Pfaden verwendet, nicht die User-ID.
• user.email folgt derselben Regel wie in der Liste. user.phone ist die verifizierte Telefonnummer, vollständig für Organisations-Admins, sonst auf die letzten vier Ziffern gekürzt (***5678).
• user.activeChannels listet die Benachrichtigungskanäle, die das Mitglied eingeschaltet hat.
• user.phoneVerified ist true, wenn das Mitglied eine bestätigte Telefonnummer hat, SMS und Anruf es also erreichen.
• user.notificationRules zeigt, welche Kanäle die eigene Regelkette des Mitglieds nutzt: high für sev1/sev2, low für sev3/sev4, jeweils mit hasPushRule, hasSmsRule, hasVoiceRule und hasEmailRule. Es kommen nur diese Schalter zurück, nie Verzögerungen oder Nummern, deshalb sieht sie jede IM-Rolle; die Maskierung der Telefonnummer oben bleibt unverändert.

Team anlegenAnkerlink kopieren

POST /api/im/teams

Anfrage (Request Body)Ankerlink kopieren

Das Team entsteht immer in deiner eigenen Organisation. Wer es anlegt, wird nicht automatisch Mitglied.

Beispiel (cURL)Ankerlink kopieren

curl -X POST "$BASE_URL/api/im/teams" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Platform Team", "labelColor": "#4f46e5" }'

Antwort (Response)Ankerlink kopieren

200 OK

{
  "id": 3,
  "name": "Platform Team",
  "labelColor": "#4f46e5",
  "analyticsEnabled": false,
  "memberCount": 0
}

Team ändernAnkerlink kopieren

PATCH /api/im/teams/:id

Jedes Feld ist optional. Nur die im Body vorhandenen Felder ändern sich.

Anfrage (Request Body)Ankerlink kopieren

Beispiel (cURL)Ankerlink kopieren

curl -X PATCH "$BASE_URL/api/im/teams/3" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "escalationRepeats": 1, "escalationRepeatsAfterMinutes": 15 }'

Antwort (Response)Ankerlink kopieren

200 OK: die Felder des Teams nach der Änderung (ohne Mitglieder, ohne Zeitstempel).

{
  "id": 3,
  "name": "Platform Team",
  "labelColor": "#4f46e5",
  "analyticsEnabled": true,
  "timezone": "Europe/Berlin",
  "escalationRepeats": 1,
  "escalationRepeatsAfterMinutes": 15,
  "escalationRepeatsStopMode": "acknowledged",
  "engagementReportEnabled": true,
  "engagementReportDayOfWeek": 1,
  "engagementReportTime": "09:00"
}

Team löschenAnkerlink kopieren

DELETE /api/im/teams/:id

Löscht das Team samt Mitgliedschaften, Eskalationsstufen, Schedules, Overrides und Kanälen. Die Anfrage wird abgelehnt, solange etwas außerhalb des Teams noch darauf zeigt (siehe die beiden 409-Codes unten).

Beispiel (cURL)Ankerlink kopieren

curl -X DELETE "$BASE_URL/api/im/teams/3" \
  -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 Anlegen, wenn du kein Organisations-Admin bist, beim Ändern oder Löschen, wenn du weder Organisations-Admin noch Team-Admin bist
• 404 Not Found (imTeamNotFound) wenn das Team nicht existiert oder zu einer anderen Organisation gehört
• 400 Bad Request (invalidRequestBody) wenn :id keine positive Ganzzahl ist, name fehlt, leer oder länger als 120 Zeichen ist, labelColor weder String noch null ist, analyticsEnabled kein Boolean ist, oder timezone keine gültige IANA-Zone ist
• 422 Unprocessable Entity (imInvalidNumber) wenn escalationRepeats oder escalationRepeatsAfterMinutes keine Ganzzahl ab 0 ist
• 422 Unprocessable Entity (imInvalidStopMode) wenn escalationRepeatsStopMode nicht acknowledged oder resolved ist
• 422 Unprocessable Entity (imInvalidRequestBody) wenn engagementReportEnabled kein Boolean ist
• 422 Unprocessable Entity (imInvalidDayOfWeek) wenn engagementReportDayOfWeek nicht 1 bis 7 ist
• 422 Unprocessable Entity (imInvalidTimeOfDay) wenn engagementReportTime nicht "HH:mm" ist
• 409 Conflict (imTeamChannelReferencesExist) beim Löschen, wenn ein Kanal des Teams der Fallback-Kanal der Organisation ist. data.fallbackChannels nennt ihn; wähle zuerst einen anderen Fallback.
• 409 Conflict (imTeamRoutingReferencesExist) beim Löschen, wenn eine Routing-Regel noch auf das Team zeigt. data.references listet die Regeln; ändere oder lösche sie zuerst.
• 409 Conflict (imTeamSourceReferencesExist) beim Löschen, wenn noch eine Alarmquelle zum Team gehört. Verschiebe sie zuerst in ein anderes Team oder lösche sie.
• 409 Conflict (imTeamIncidentReferencesExist) beim Löschen, wenn noch Incidents zum Team gehören. Ein Team mit Incident-Historie kann nicht gelöscht werden.