Urgency and priority levels

curl -X PUT http://localhost:5080/api/v1/alerts/importance \
  -H "authorization: Bearer $MS_TOKEN" \
  -H "content-type: application/json" \
  -d @levels.json

curl -X PUT http://localhost:5080/api/v1/alerts/importance \
  -H "authorization: Bearer $MS_TOKEN" \
  -H "content-type: application/json" \
  -d @levels.json

GET /api/v1/alerts/importance
PUT /api/v1/alerts/importance

GET requires alerts.importance.read and PUT requires alerts.importance.manage. Both return the organization’s levels:

{
  "levels": {
    "priorities": [
      {"priority": "P1", "name": "Critical business impact", "description": "Customers cannot pay"},
      {"priority": "P2", "name": "", "description": ""},
      {"priority": "P3", "name": "", "description": ""}
    ],
    "urgencies": [
      {"key": "urgent", "name": "Urgent", "escalates": true, "quiet_hours": "switch", "steps": "high", "severities": ["critical"]},
      {"key": "high", "name": "", "escalates": true, "quiet_hours": "switch", "steps": "high", "severities": ["error"]},
      {"key": "low", "name": "", "escalates": false, "quiet_hours": "block", "steps": "low", "severities": ["warning", "info"]}
    ]
  },
  "updated_by": "3KF1...",
  "updated_at": 1793059200000000
}

An organization that never saved levels gets the built-in ones: P1 to P5, and high and low as described in Urgency, with updated_by empty. PUT takes the levels object and replaces the levels, and records the audit event alert_importance.updated.

Field	Description
`priorities`	1 to 9 levels, `P1`, `P2`, … without a gap. `name` up to 32 characters and `description` up to 200; an empty name uses the key.
`urgencies`	2 to 5 levels, the most urgent first. `key` starts with a lowercase letter and holds lowercase letters, digits, and underscores, up to 32 characters; `high` and `low` must stay. `name` up to 32 characters; an empty name uses the built-in words.
`escalates`	`true` pages along the steps of the escalation policy; `false` notifies the first step only.
`quiet_hours`	`switch` follows the person’s Still get high-urgency alerts during quiet hours; `block` never wakes anyone during quiet hours.
`steps`	Which of a person’s two groups of steps the level uses: `high` or `low`.
`severities`	The severities that go to the level when a policy sets urgency by severity; each of `critical`, `error`, `warning`, and `info` goes to exactly one level.

The levels decide what rules, escalation policies, incidents, and the API may name: a priority beyond the levels or an urgency that is not a level fails with 400 there. An external alert or an alert pipeline that gives a priority beyond the levels gets the lowest one, and an urgency the organization does not have is dropped. Notifications carry the names as {{priority_name}} and {{urgency_name}}.

curl -X PUT http://localhost:5080/api/v1/alerts/importance \
  -H "authorization: Bearer $MS_TOKEN" \
  -H "content-type: application/json" \
  -d @levels.json

Errors

Status	Reason
`400`	The levels break a rule in the table above.
`403`	The token lacks the permission.
`422`	A field has the wrong type, or a key is not a key.

Last modified on October 31, 2026

Overview

Authentication

Intake

Query

APM

RUM

Streams

Alerting

Correlation & Web

Platform & Administration

Urgency and priority levels