Part of the Phoenix Alerts Management API reference.

A service is what an alert routes to — usually one piece of software or infrastructure you monitor (an API, a database, a background job). Every service belongs to a team, and inherits that team's escalation policy unless you attach a different one.

Before creating a service, the owning team needs an escalation policy with at least one step. See Escalation policies.

Create a service

POST /v1/services

Field	Type	Required	Notes
`name`	string	yes	1–256 characters.
`key`	string	no	URL-safe slug. Generated from `name` when omitted.
`team_uuid`	string	one of `team_uuid`/`team_key`	UUID of the owning team.
`team_key`	string	one of `team_uuid`/`team_key`	Key of the owning team.
`description`	string or null	no	Up to 1024 characters.

Example request body:

{"name": "API Service", "team_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "description": "Core API service"}

Response (201):

{
  "object": "service",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "key": "api-service",
  "name": "API Service",
  "team": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "Platform Team",
    "key": "platform"
  },
  "description": "Core API service",
  "created_at": "2026-06-12T00:00:00.000Z",
  "updated_at": "2026-06-12T00:00:00.000Z",
  "escalation_policy": null
}

The key field returned in the alert-ingestion request as service_key — see Sending alerts.

List services

GET /v1/services

Optionally add ?team_uuid=<uuid> to scope to one team.

The list response doesn't include escalation policy details — fetch a single service for that.

Get a single service

GET /v1/services/{service_uuid}

Response (200) — includes the resolved escalation policy when one is attached:

{
  "object": "service",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "key": "api-service",
  "name": "API Service",
  "team": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "Platform Team",
    "key": "platform"
  },
  "description": "Core API service",
  "created_at": "2026-06-12T00:00:00.000Z",
  "updated_at": "2026-06-12T00:00:00.000Z",
  "escalation_policy": {
    "object": "escalation_policy",
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "name": "Default Policy",
    "is_default": true,
    "steps": []
  }
}

Update a service

PATCH /v1/services/{service_uuid}

All fields are optional — send only what you want to change.

Field	Type	Notes
`name`	string	1–256 characters.
`key`	string	URL-safe slug.
`team_uuid`	string	Reassign to this team, by UUID. Mutually exclusive with `team_key`.
`team_key`	string	Reassign to this team, by key. Mutually exclusive with `team_uuid`.
`description`	string or null	Up to 1024 characters.

Example request body:

{"description": "Updated description"}

Delete a service

DELETE /v1/services/{service_uuid}

Returns 204 on success. If the service still has open alerts, this returns 409 — resolve them first.

Create many services at once

POST /v1/services/bulk

Accepts up to 100 service descriptors in one request. Each one is created independently — one failure doesn't block the rest. The response is always 207, with a status of "created" or "failed" on each item.

Services