Part of the Phoenix Alerts Management API reference.
A team groups the people who own a set of services. Teams have an on-call schedule, one or more escalation policies, and members with either the MEMBER or TEAM_ADMIN role.
Create a team
POST /v1/teams
Field | Type | Required | Notes |
| string | yes | 1–256 characters. |
| string | no | URL-safe slug. Generated from |
Example request body:
{"name": "Platform Team"}
Response (201, or 200 if a team with that key already exists):
{
"object": "team",
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Platform Team",
"key": "platform",
"created_at": "2026-06-12T00:00:00.000Z",
"updated_at": "2026-06-12T00:00:00.000Z"
}
List teams
GET /v1/teams
Optionally filter by name substring with ?name=.
Each item includes member_count, policy_count, and service_count, but not the full member list.
Get a single team
GET /v1/teams/{team_uuid}
Returns the team with its member list. Add ?expand=services,escalation_policies to embed those too.
Update or delete a team
PATCH /v1/teams/{team_uuid}
DELETE /v1/teams/{team_uuid}
PATCH accepts name and key. DELETE returns 409 if the team still has members — remove them first.
Add a member
POST /v1/teams/{team_uuid}/membersField | Type | Required | Notes |
| string | yes | UUID of the user to add. See Users. |
| string | no |
|
Example request body:
{"user_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"}
Returns 409 if the user is already on the team.
Update or remove a member
PATCH /v1/teams/{team_uuid}/members/{user_uuid}
DELETE /v1/teams/{team_uuid}/members/{user_uuid}
PATCH accepts role and/or in_rotation (whether the member is included in the on-call rotation) — send at least one.
DELETE removes the member. It returns 409 if that would leave an escalation policy step with no one reachable — reassign the step first.
Create many teams at once
POST /v1/teams/bulk
Same partial-success shape as bulk service creation: up to 100 teams, 207 response, per-item status.