# Update severity levels

Replace the organization's severity level configuration.

Source: https://statusdashboard.com/docs/api/event-management/severities/update

`PUT /app/severities`

Replaces the full severity level configuration for the organization. Requires the **Custom Severities** plan feature.

The request body is a **JSON array** of severity objects — the entire configuration is replaced, not merged. Send at least 1 severity level (schema minimum). the organization `severityLevels` limit caps the maximum count. Labels must be unique (case-insensitive). `order` values must be unique and contiguous from `1` through the severity count.

> Unlike most App API resources that use an object wrapper (for example 
>   `{ "title": "…" }`
>   ), severities PUT accepts a 
>   **top-level JSON array**
>   . This matches the full-replacement semantics: the body 
>   *is*
>    the complete new configuration. Clients must send 
>   `Content-Type: application/json`
>    with a raw array as shown below.

***

## Request
See [API Basics](/docs/api) for required headers.

### Request body
```json
[
  {
    "label": "Degraded Performance",
    "description": "Minor service issues, some users may see slow performance.",
    "icon": "alert-triangle",
    "defaultColor": "#CA8A04",
    "order": 1
  },
  {
    "label": "Partial Outage",
    "description": "A major feature or part of the service is unavailable.",
    "icon": "alert-circle",
    "defaultColor": "#EA580C",
    "order": 2
  },
  {
    "label": "Major Outage",
    "description": "A critical service is completely down or all users are affected.",
    "icon": "alert-octagon",
    "defaultColor": "#991B1B",
    "order": 3
  }
]
```

Each array element:

| Field          | Type   | Required | Description                                                                                                                     |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `label`        | string | Yes      | Display name. Must be unique within the array (case-insensitive). Max 50 characters.                                            |
| `description`  | string | Yes      | Human-readable description. Max 150 characters.                                                                                 |
| `icon`         | string | Yes      | Approved icon key. Must be one of the [approved Lucide icons](/docs/events/severities#severity-fields).                         |
| `defaultColor` | string | Yes      | Hex color string (e.g. `#EA580C`).                                                                                              |
| `order`        | number | Yes      | 1-based integer, unique and contiguous from `1` through the severity count. Items are stored and returned sorted by this value. |

***

## Sample request
Uses the seeded default labels, colors, and descriptions from new organizations (see [Default severity levels](/docs/events/severities#default-severity-levels)).

```bash
curl -X PUT https://api.statusdashboard.com/app/severities \
  -H "Authorization: Bearer bcf847abf5c6:def456" \
  -H "Content-Type: application/json" \
  -d '[
    { "label": "Degraded Performance", "description": "Minor service issues, some users may see slow performance.", "icon": "alert-triangle", "defaultColor": "#CA8A04", "order": 1 },
    { "label": "Partial Outage",     "description": "A major feature or part of the service is unavailable.",     "icon": "alert-circle",  "defaultColor": "#EA580C", "order": 2 },
    { "label": "Major Outage",       "description": "A critical service is completely down or all users are affected.", "icon": "alert-octagon", "defaultColor": "#991B1B", "order": 3 }
  ]'
```

## Sample response
**Status: `200 OK`**

The response body contains the **stored** configuration (sorted by `order` ascending).

```json
{
  "message": "Severities updated successfully",
  "severities": [
    { "label": "Degraded Performance", "description": "Minor service issues, some users may see slow performance.", "icon": "alert-triangle", "defaultColor": "#CA8A04", "order": 1 },
    { "label": "Partial Outage",     "description": "A major feature or part of the service is unavailable.",     "icon": "alert-circle",  "defaultColor": "#EA580C", "order": 2 },
    { "label": "Major Outage",       "description": "A critical service is completely down or all users are affected.", "icon": "alert-octagon", "defaultColor": "#991B1B", "order": 3 }
  ]
}
```

***

## Error responses
| Status | When                                                                                                |
| ------ | --------------------------------------------------------------------------------------------------- |
| `400`  | Validation failed — see common messages below.                                                      |
| `400`  | Duplicate labels, invalid icons, invalid hex colors, or fewer than 1 severity level.                |
| `400`  | Severity order values must be unique, contiguous integers from 1 through the severity count         |
| `403`  | Insufficient permissions, Custom Severities feature not enabled, or `severityLevels` limit reached. |