> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Urgency and priority levels

> Read and set the organization's priority levels and urgency levels: their names, and how each urgency level pages.

```http theme={null}
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:

```json theme={null}
{
  "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](https://docs.molesignal.com/en-US/alerting/on-call.md#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}}`.

```bash cURL theme={null}
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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.