Teams

List, read, create, update and delete Incident Management teams, including the team-level escalation and engagement-report settings.

A team is the top-level ownership unit in Incident Management: escalation tiers, schedules, overrides and incidents all belong to exactly one team. This page covers the team itself. Members are on Team Members, the escalation chain on Escalation Tiers.

Authentication

Every endpoint needs base IM access: an IM-eligible role (admin, editor or responder) or an organization-wide API token, and Incident Management must be activated for the organization. Reads are open to any caller with that access.

Writes need more:

Create needs the organization admin role.
Update and delete need the team write bar: organization admin role, or team admin (imRole: "admin") of this team.

An API token runs with the role of the user who created it. Only a token created by an organization admin passes either write bar.

Teams of another organization always answer 404, never 403.

List teams

GET /api/im/teams

Returns every team of your organization, ordered by name, with a member count and a short member list.

Example (cURL)

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

Response

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 is only filled for organization admins (and tokens created by one). Everyone else gets null, and a member without a display name then has an empty name. src is the member's avatar URL or null.

Get a team

GET /api/im/teams/:id

Returns the team, its settings and its members with their notification readiness.

Example (cURL)

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

Response

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 is the membership id that Team Members uses in its paths, not the user id.
user.email follows the same rule as in the list. user.phone is the verified phone number in full for organization admins, otherwise masked to the last four digits (***5678).
user.activeChannels lists the notification channels the member has switched on.
user.phoneVerified is true when the member has a confirmed phone number, so SMS and voice can reach them.
user.notificationRules says which channels the member's own rule chain uses: high for sev1/sev2, low for sev3/sev4, each with hasPushRule, hasSmsRule, hasVoiceRule and hasEmailRule. Only these flags are returned, never delays or numbers, so every IM role sees them; the phone masking above is unchanged.

Create a team

POST /api/im/teams

Request Body

Field	Type	Required	Description
`name`	string	Yes	Team name, trimmed, 1 to 120 characters.
`labelColor`	string	No	Free-form color label, e.g. `#4f46e5`. Empty becomes `null`.
`analyticsEnabled`	boolean	No	Only `true` switches it on. Default `false`.
`timezone`, `escalationRepeats`, `escalationRepeatsAfterMinutes`, `escalationRepeatsStopMode`, `engagementReportEnabled`, `engagementReportDayOfWeek`, `engagementReportTime`		No	The team settings from Update a team, same types and rules. They are written together with the team, so it never exists without them. Omitted fields take their defaults.

The team is always created in your own organization. The creator is not added as a member.

Example (cURL)

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

Response

200 OK

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

Update a team

PATCH /api/im/teams/:id

Every field is optional. Only fields present in the body change.

Request Body

Field	Type	Description
`name`	string	1 to 120 characters after trimming.
`labelColor`	string \| null	Color label. `null` or an empty string clears it.
`analyticsEnabled`	boolean	Team analytics on or off.
`timezone`	string \| null	IANA zone, used as the timezone of the default schedule a new tier gets. `null` clears it (new tiers then use `UTC`). Existing schedules keep their own timezone.
`escalationRepeats`	integer	How many more times the whole escalation chain runs after the last tier, `0` or more.
`escalationRepeatsAfterMinutes`	integer \| null	Minutes before each repeat of the chain, `0` or more.
`escalationRepeatsStopMode`	string	`acknowledged` or `resolved`: the incident state that stops the repeats.
`engagementReportEnabled`	boolean	Weekly engagement report on or off.
`engagementReportDayOfWeek`	integer \| null	ISO weekday of the report, 1 = Monday to 7 = Sunday.
`engagementReportTime`	string \| null	Time of the report, `"HH:mm"`.

Example (cURL)

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

Response

200 OK: the team's fields after the update (no members, no timestamps).

{
  "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"
}

Delete a team

DELETE /api/im/teams/:id

Deletes the team together with its memberships, escalation tiers, schedules, overrides and channels. The request is refused while something outside the team still points at it (see the two 409 codes below).

Example (cURL)

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

Response

200 OK

{ "success": true }

Common errors

401 Unauthorized (unauthorized) when not authenticated
403 Forbidden (imAccessDenied) for a customer-scoped token, or a session without an IM-eligible role
403 Forbidden (imNotEnabled) when Incident Management is not activated for the organization
403 Forbidden (imTeamWriteDenied) on create when you are not an organization admin, on update or delete when you are neither organization admin nor team admin
404 Not Found (imTeamNotFound) when the team does not exist or belongs to another organization
400 Bad Request (invalidRequestBody) when :id is not a positive integer, name is missing, empty or longer than 120 characters, labelColor is neither string nor null, analyticsEnabled is not a boolean, or timezone is not a valid IANA zone
422 Unprocessable Entity (imInvalidNumber) when escalationRepeats or escalationRepeatsAfterMinutes is not an integer of 0 or more
422 Unprocessable Entity (imInvalidStopMode) when escalationRepeatsStopMode is not acknowledged or resolved
422 Unprocessable Entity (imInvalidRequestBody) when engagementReportEnabled is not a boolean
422 Unprocessable Entity (imInvalidDayOfWeek) when engagementReportDayOfWeek is not 1 to 7
422 Unprocessable Entity (imInvalidTimeOfDay) when engagementReportTime is not "HH:mm"
409 Conflict (imTeamChannelReferencesExist) on delete when one of the team's channels is the organization's fallback channel. data.fallbackChannels names it; pick another fallback first.
409 Conflict (imTeamRoutingReferencesExist) on delete when a routing rule still targets the team. data.references lists the rules; change or delete them first.
409 Conflict (imTeamSourceReferencesExist) on delete when an alert source still belongs to the team. Move it to another team or delete it first.
409 Conflict (imTeamIncidentReferencesExist) on delete when incidents still belong to the team. A team with incident history cannot be deleted.

Teams

AuthenticationCopy Anchor Link

List teamsCopy Anchor Link

Example (cURL)Copy Anchor Link

ResponseCopy Anchor Link

Get a teamCopy Anchor Link

Example (cURL)Copy Anchor Link

ResponseCopy Anchor Link

Create a teamCopy Anchor Link

Request BodyCopy Anchor Link

Example (cURL)Copy Anchor Link

ResponseCopy Anchor Link

Update a teamCopy Anchor Link

Request BodyCopy Anchor Link

Example (cURL)Copy Anchor Link

ResponseCopy Anchor Link

Delete a teamCopy Anchor Link

Example (cURL)Copy Anchor Link

ResponseCopy Anchor Link

Common errorsCopy Anchor Link

On this page

Authentication

List teams

Example (cURL)

Response

Get a team

Example (cURL)

Response

Create a team

Request Body

Example (cURL)

Response

Update a team

Request Body

Example (cURL)

Response

Delete a team

Example (cURL)

Response

Common errors