Escalation Policies

Escalation policies define an ordered sequence of who to notify — and how long to wait between each step — when an alert remains unacknowledged.

Creating an escalation policy

POST /api/v1/escalation-policies
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Critical Service On-Call",
  "rules": [
    {
      "level": 1,
      "delay_minutes": 0,
      "notify_type": "channel",
      "notify_id": "<notification-channel-uuid>"
    },
    {
      "level": 2,
      "delay_minutes": 5,
      "notify_type": "team",
      "notify_id": "<team-uuid>"
    },
    {
      "level": 3,
      "delay_minutes": 15,
      "notify_type": "user",
      "notify_id": "<user-uuid>"
    }
  ]
}

Fields

Field	Type	Required	Description
name	string	✅	Policy display name
rules	array	No	Ordered escalation steps

Rule fields

Field	Type	Description
level	int	Step order (1 = first, 2 = second, ...)
delay_minutes	int	Minutes to wait before this level activates
notify_type	string	"team", "user", or "channel"
notify_id	string	UUID of the team, user, or notification channel

Level 1 with delay_minutes: 0 fires immediately when an alert is created. Subsequent levels fire only if the alert is not acknowledged within that delay.

---

Listing and deleting

# List all escalation policies
GET /api/v1/escalation-policies

# Delete an escalation policy
DELETE /api/v1/escalation-policies/{id}

---

Example: 3-level escalation

{
  "name": "Production Incidents",
  "rules": [
    { "level": 1, "delay_minutes": 0,  "notify_type": "channel", "notify_id": "slack-channel-uuid" },
    { "level": 2, "delay_minutes": 5,  "notify_type": "team",    "notify_id": "oncall-team-uuid"   },
    { "level": 3, "delay_minutes": 15, "notify_type": "user",    "notify_id": "manager-user-uuid"  }
  ]
}

This fires immediately to Slack, escalates to the on-call team after 5 minutes if unacknowledged, then pages the engineering manager after 15 minutes.