# Update the alert settings

> The alert_settings.update operation: PATCH /api/v1/alert_settings in the REST API and the alert_settings_update tool in the MCP server.

Sets whether high alerts are emailed in the mode of the request: `immediate` (the default) emails them to
the members whose role handles them as they are raised; `off` keeps them in the inbox (and the Slack
channels that take high alerts). Critical alerts are always emailed. Pass `expectedVersion` (the settings'
`version`, 0 while the defaults apply) to refuse the change if someone else changed the settings meanwhile.

Needs `org:write` (owners and admins).

## At a glance

- **REST:** `PATCH /api/v1/alert_settings`
- **MCP tool:** `alert_settings_update`
- **Operation ID:** `alert_settings.update`
- **Scope:** Organization
- **Permission:** `org:write`
- **Risk tier:** `write`
- **Dry run:** Supported (send `Ownrecord-Dry-Run: true`)
- **Idempotency:** `Idempotency-Key` optional
- **Modes:** Test and live
- **Authentication:** API key with the `org:write` scope
- **Since:** M7

## Request

### Body

A JSON object (`Content-Type: application/json`):

| Field             | Type                      | Required | Description |
| ----------------- | ------------------------- | -------- | ----------- |
| `email`           | object                    | Yes      |             |
| `email.high`      | one of `immediate`, `off` | Yes      |             |
| `expectedVersion` | integer (at least 0)      | No       |             |

## Response

`200 OK` with a JSON object:

| Field                         | Type                      | Description |
| ----------------------------- | ------------------------- | ----------- |
| `object`                      | `"alert_settings"`        |             |
| `livemode`                    | boolean                   |             |
| `email`                       | object                    |             |
| `email.high`                  | one of `immediate`, `off` |             |
| `slackChannels`               | array of object           |             |
| `slackChannels[].id`          | `sec_…` ID                |             |
| `slackChannels[].object`      | `"slack_channel"`         |             |
| `slackChannels[].name`        | string                    |             |
| `slackChannels[].urlHint`     | string                    |             |
| `slackChannels[].minSeverity` | one of `high`, `critical` |             |
| `slackChannels[].createdAt`   | date-time                 |             |
| `slackChannels[].createdBy`   | string                    |             |
| `slackChannels[].lastTest`    | object or null            |             |
| `updatedAt`                   | date-time or null         |             |
| `version`                     | integer (at least 0)      |             |

## Examples

### Keep high alerts out of email

```http
PATCH /api/v1/alert_settings
Authorization: Bearer or_test_…
Content-Type: application/json

{
  "email": {
    "high": "off"
  },
  "expectedVersion": 2
}
```

Response (`200`):

```json
{
  "object": "alert_settings",
  "livemode": true,
  "email": {
    "high": "off"
  },
  "slackChannels": [
    {
      "id": "sec_01m4ttwd3veh9apbewxheq5xad",
      "object": "slack_channel",
      "name": "#tax-alerts",
      "urlHint": "hooks.slack.com …x7Qa",
      "minSeverity": "high",
      "createdAt": "2026-10-13T12:00:00.000Z",
      "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
      "lastTest": null
    }
  ],
  "updatedAt": "2026-10-13T12:00:00.000Z",
  "version": 3
}
```

## Errors

| Code                                                                                   | HTTP status | When                                                            | What to do                                                                      |
| -------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400         | `email.high` isn't `immediate` or `off`.                        | Fix the fields listed in `details.issues` and send the request again.           |
| [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict)   | 409         | The settings changed since `expectedVersion`; reload and retry. | Fetch the object again and retry the change.                                    |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403         | You can't change this organization's settings.                  | Ask an organization owner or admin for a role or scope that allows this action. |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).