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

# Change Severity

> Re-assesses an open incident's severity.

Re-assigns an open incident's severity as impact becomes clearer — bump it up (e.g. `medium` → `critical`) or down at any point while the incident is active. The change is recorded on the incident timeline with the old and new severity, the actor, and a timestamp.

<Tip>
  Severity drives the status your affected components show on your public status page. Changing severity re-derives those component statuses automatically, so the status-page banner reflects the new value on the next read.
</Tip>

## Path parameters

<ParamField path="id" type="string" required>
  The UUID of the incident to update.
</ParamField>

## Request body

<ParamField body="severity" type="string" required>
  The new severity. One of `critical`, `high`, `medium`, or `low`. Must differ from the incident's current severity — a no-op change is rejected.
</ParamField>

## Response

Returns the updated incident object.

<ResponseField name="data" type="object" required>
  <Expandable title="properties" defaultOpen>
    <ResponseField name="id" type="string" required>
      Unique identifier for the incident (UUID).
    </ResponseField>

    <ResponseField name="orgId" type="string" required>
      The organization this incident belongs to.
    </ResponseField>

    <ResponseField name="title" type="string" required>
      Short title describing the incident.
    </ResponseField>

    <ResponseField name="severity" type="string" required>
      The new severity level: `critical`, `high`, `medium`, or `low`.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      The incident's current status.
    </ResponseField>

    <ResponseField name="affectedComponents" type="array of object" required>
      Components affected by this incident. Each entry has `id` and `name`. Empty array if none.
    </ResponseField>

    <ResponseField name="createdAt" type="string" required>
      ISO 8601 timestamp of when the incident was created.
    </ResponseField>

    <ResponseField name="updatedAt" type="string" required>
      ISO 8601 timestamp of when the incident was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

## Error responses

| Status | Code                      | Description                                                                                       |
| ------ | ------------------------- | ------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_severity_change` | The severity is unchanged (no-op), not a recognized value, or the incident is already `resolved`. |
| `401`  | `not_authorized`          | Missing or invalid API key.                                                                       |
| `404`  | `not_found`               | No incident with the given ID exists in your organization.                                        |
| `422`  | —                         | Request body failed validation (e.g. `severity` is missing or not one of the allowed values).     |
| `500`  | `server_error`            | An unexpected error occurred on our side.                                                         |

<RequestExample>
  ```bash Escalate to critical theme={null}
  curl --request PATCH \
    --url "https://api.scaling.cloud/v1/incidents/YOUR_INCIDENT_ID/severity" \
    --header "Authorization: Bearer YOUR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "severity": "critical"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "orgId": "org_01HX4K9MNPQRST",
      "title": "Payment service elevated error rate",
      "severity": "critical",
      "status": "identified",
      "affectedComponents": [
        { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "name": "Payments API" }
      ],
      "createdAt": "2025-04-07T08:23:11.000Z",
      "updatedAt": "2025-04-07T09:15:44.000Z"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "statusCode": 400,
    "type": "invalid_request_error",
    "code": "invalid_severity_change",
    "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
  }
  ```

  ```json 401 theme={null}
  {
    "statusCode": 401,
    "type": "not_authorized_error",
    "code": "not_authorized",
    "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
  }
  ```

  ```json 404 theme={null}
  {
    "statusCode": 404,
    "type": "invalid_request_error",
    "code": "not_found",
    "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
  }
  ```

  ```json 500 theme={null}
  {
    "statusCode": 500,
    "type": "internal_error",
    "code": "server_error",
    "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
  }
  ```
</ResponseExample>