Part of the Phoenix Alerts Management API reference.

This is the endpoint your monitoring tool calls to page someone. An ingestion key (pi_ prefix) can also call PATCH /v1/alerts/{alert_uuid} to acknowledge or resolve an alert it created — see Alerts — but it can't reach any other endpoint.

Authentication

Authorization: Bearer pi_<your key>

The older x-api-key: pi_<key> header still works too, for tools that can't set a custom Authorization value. If both are present, Authorization: Bearer wins. See API keys to create one.

Send an alert

POST /v1/alerts

Field	Type	Required	Notes
`alert_key`	string	yes	1–255 characters. Your identifier for this alert. Sending the same key again against an active alert de-duplicates instead of creating a new one.
`summary`	string	for new alerts	1–4096 characters. Required when creating an alert; ignored when resolving.
`severity_level`	integer	no	1–5 (1 = critical). Omit to let the escalation policy decide.
`source`	string	no	Up to 255 characters. Name of the tool that generated the alert.
`service_uuid`	string	one of these	The service to route to. See Services.
`service_key`	string	one of these	Same, but by the service's slug instead of UUID.
`team_key`	string	one of these	Route straight to a team's default escalation policy instead of a service.
`team_uuid`	string	one of these	Same, by team UUID.
`occurred_at`	string	no	ISO-8601 timestamp of when the underlying event happened.
`external_reference`	object	no	`{"id": "...", "type": "...", "url": "..."}` — a link back to the originating system.
`custom_details`	object	no	Any key-value metadata. Stored, not searchable.
`event_action`	string	no	`"trigger"` (default) creates or de-duplicates. `"resolve"` closes the matching alert instead — see below.

Example request body:

{
    "alert_key": "high-error-rate",
    "summary": "Error rate exceeded 5% in the last minute",
    "service_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "severity_level": 2,
    "source": "Datadog"
  }

Response (201 for a new alert):

{
  "object": "alert",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "alert_number": 43,
  "alert_key": "server.cpu.high",
  "summary": "CPU usage above 90% for 5 minutes",
  "source": "datadog",
  "severity_level": 2,
  "service": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "API Service",
    "key": "api-service"
  },
  "status": "TRIGGERED",
  "duplicate_count": 0,
  "ingestion_outcome": "CREATED",
  "escalation_policy": {
    "id": "d4e5f6a7-b8c9-0123-def0-123456789012",
    "name": "Default Policy",
    "match_type": "DEFAULT",
    "severity_matched": null
  }
}

You can route by service (service_uuid or service_key) or straight to a team (team_uuid or team_key) if the alert has no natural owning service. If you send service_uuid and it doesn't match a real service, Phoenix Alerts falls back to your account's default routing target instead of failing the request.

Sending the same alert twice

Send the same alert_key again while that alert is still open, and Phoenix Alerts doesn't create a second one — it returns the existing alert with ingestion_outcome: "DEDUPED" and increments duplicate_count, response code 200:

Example request body:

{"alert_key": "server.cpu.high", "summary": "CPU usage above 90% for 5 minutes"}

{
  "object": "alert",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "alert_number": 43,
  "alert_key": "server.cpu.high",
  "summary": "CPU usage above 90% for 5 minutes",
  "source": "datadog",
  "service": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "API Service",
    "key": "api-service"
  },
  "status": "TRIGGERED",
  "duplicate_count": 1,
  "ingestion_outcome": "DEDUPED",
  "escalation_policy": null
}

Sending a higher severity_level than the existing alert has escalates it instead — you'll see ingestion_outcome: "DEDUPED_ESCALATED".

Resolving from your monitoring tool

If your monitoring tool can tell when the underlying problem clears, send the same alert_key again with event_action: "resolve" to close the alert without anyone having to do it by hand:

Example request body:

{"alert_key": "server.cpu.high", "event_action": "resolve"}

If there's no active alert with that key, this is a no-op — it's safe to call even if you're not sure whether the alert is still open.

Common errors

Status	Code	Meaning
400	`NO_ROUTING_TARGET`	No `service_uuid`/`service_key`/`team_uuid`/`team_key` given and your account has no default target configured.
401	`MISSING_API_KEY`	No `Authorization: Bearer` or `x-api-key` header was sent.
401	`INVALID_API_KEY`	The key is invalid or has been revoked.
404	`SERVICE_NOT_FOUND`	`service_key` doesn't match a service on your account.
404	`NO_DEFAULT_POLICY`	`team_key`/`team_uuid` resolves to a team with no default escalation policy.

Every error follows the shape described in Getting started.

Sending alerts

Authentication

Send an alert

Sending the same alert twice

Resolving from your monitoring tool

Common errors