# Alerts tools

> MCP tools for Alerts: alerts_acknowledge, alerts_get, alerts_list, alerts_resolve.

- `alerts_acknowledge`: Acknowledge an alert
- `alerts_get`: Get an alert
- `alerts_list`: List alerts
- `alerts_resolve`: Resolve an alert

## `alerts_acknowledge`

**Acknowledge an alert.** Operation [`alerts.acknowledge`](https://ownrecord.io/docs/reference/alerts-acknowledge.md) · Organization level · permission `org:read` · risk tier `write` · since M7

Marks an alert `acked`: someone is working on it. It stays unresolved, so if the same problem is raised
again its `occurrences` go up instead of a new alert appearing. Acknowledging an acknowledged alert changes
nothing; a resolved one answers `alert_resolved`.

Needs write access to what the alert is about at its legal entity or brand, e.g. `registrations:write` for
a registration alert (tax managers, owners, admins) or `ledger:write` for a ledger alert (finance).

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument          | Type         | Required | Description                                                                                                                                                                                              |
| ----------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | ID (`alr_…`) | yes      | –                                                                                                                                                                                                        |
| `idempotency_key` | string       | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean      | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No alert with this ID that you may see, in this organization and mode.
- [`alert_resolved`](https://ownrecord.io/docs/reference/errors.md#alert_resolved): The alert is already resolved.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): Your role may see the alert but not act on what it is about.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The alert changed at the same moment; retry.

### Example

**Take on an automatic block**

Arguments:

```json
{
  "id": "alr_01m4ttwd3veh9apbewxheq5xab",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "alr_01m4ttwd3veh9apbewxheq5xab",
  "object": "alert",
  "code": "REG_AUTO_BLOCKED",
  "severity": "critical",
  "family": "registrations",
  "message": "EU_OSS_NON_UNION was blocked for new consumer sales on 2026-11-07: the grace deadline 2026-11-10 is near and no application was submitted.",
  "link": "/console/acme/e/acme-hr/jurisdictions/EU_OSS_NON_UNION",
  "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
  "brandId": null,
  "livemode": true,
  "status": "acked",
  "occurrences": 1,
  "lastRaisedAt": "2026-10-13T12:00:00.000Z",
  "acknowledgedAt": "2026-10-13T12:30:00.000Z",
  "acknowledgedBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
  "resolvedAt": null,
  "resolvedBy": null,
  "delivery": {
    "status": "delivered",
    "attempts": 1,
    "lastError": null,
    "email": {
      "sent": 2,
      "failed": 0
    },
    "slack": [
      {
        "channelId": "sec_01m4ttwd3veh9apbewxheq5xad",
        "status": "sent",
        "at": "2026-10-13T12:00:00.000Z",
        "error": null
      }
    ]
  },
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-13T12:30:00.000Z",
  "version": 2
}
```

## `alerts_get`

**Get an alert.** Operation [`alerts.get`](https://ownrecord.io/docs/reference/alerts-get.md) · Organization level · permission `org:read` · risk tier `read` · since M7

Returns one alert of the organization in the mode of the request: what happened (`code`, `severity`,
`message`), where to act on it (`link`, a console page), how often it was raised while unresolved
(`occurrences`), who acknowledged or resolved it, and how it was delivered (emails sent, Slack channels).
An alert your role may not see answers `resource_not_found`, as if it didn't exist.

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument | Type         | Required | Description |
| -------- | ------------ | -------- | ----------- |
| `id`     | ID (`alr_…`) | yes      | –           |

- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No alert with this ID that you may see, in this organization and mode.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't read this organization's inbox.

### Example

**An automatic block**

Arguments:

```json
{
  "id": "alr_01m4ttwd3veh9apbewxheq5xab"
}
```

Result `output`:

```json
{
  "id": "alr_01m4ttwd3veh9apbewxheq5xab",
  "object": "alert",
  "code": "REG_AUTO_BLOCKED",
  "severity": "critical",
  "family": "registrations",
  "message": "EU_OSS_NON_UNION was blocked for new consumer sales on 2026-11-07: the grace deadline 2026-11-10 is near and no application was submitted.",
  "link": "/console/acme/e/acme-hr/jurisdictions/EU_OSS_NON_UNION",
  "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
  "brandId": null,
  "livemode": true,
  "status": "open",
  "occurrences": 1,
  "lastRaisedAt": "2026-10-13T12:00:00.000Z",
  "acknowledgedAt": null,
  "acknowledgedBy": null,
  "resolvedAt": null,
  "resolvedBy": null,
  "delivery": {
    "status": "delivered",
    "attempts": 1,
    "lastError": null,
    "email": {
      "sent": 2,
      "failed": 0
    },
    "slack": [
      {
        "channelId": "sec_01m4ttwd3veh9apbewxheq5xad",
        "status": "sent",
        "at": "2026-10-13T12:00:00.000Z",
        "error": null
      }
    ]
  },
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-13T12:00:00.000Z",
  "version": 1
}
```

## `alerts_list`

**List alerts.** Operation [`alerts.list`](https://ownrecord.io/docs/reference/alerts-list.md) · Organization level · permission `org:read` · risk tier `read` · since M7

Lists the organization's alerts in the mode of the request, newest first: the console inbox (spec §24), by
default the unresolved ones (open or acknowledged).
Only the alerts your role may see are listed: each alert is about one area (registrations, ledger, webhooks,
…, its `family`) and is shown to members who may read that area at its legal entity or brand. Owners and
admins see every alert.

By default only unresolved alerts (`open` and `acked`); filter with `status` (one or several), `severity`,
`code` or `entityId`. Paginate with `limit` (1–100, default 10) and `starting_after` (the `next_cursor` of the
previous page); a page can be shorter than `limit` while `has_more` is true.

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument         | Type                                                                              | Required | Description |
| ---------------- | --------------------------------------------------------------------------------- | -------- | ----------- |
| `limit`          | integer                                                                           | no       | (1–100)     |
| `starting_after` | ID (`alr_…`)                                                                      | no       | –           |
| `status`         | one of `open`, `acked`, `resolved` or array of one of `open`, `acked`, `resolved` | no       | –           |
| `severity`       | one of `info`, `high`, `critical` or array of one of `info`, `high`, `critical`   | no       | –           |
| `code`           | string                                                                            | no       | –           |
| `entityId`       | ID (`ent_…`)                                                                      | no       | –           |

- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A filter or pagination value is invalid.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't read this organization's inbox.

### Examples

**The unresolved alerts**

Arguments:

```json
{}
```

Result `output`:

```json
{
  "object": "list",
  "data": [
    {
      "id": "alr_01m4ttwd3veh9apbewxheq5xab",
      "object": "alert",
      "code": "REG_AUTO_BLOCKED",
      "severity": "critical",
      "family": "registrations",
      "message": "EU_OSS_NON_UNION was blocked for new consumer sales on 2026-11-07: the grace deadline 2026-11-10 is near and no application was submitted.",
      "link": "/console/acme/e/acme-hr/jurisdictions/EU_OSS_NON_UNION",
      "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
      "brandId": null,
      "livemode": true,
      "status": "open",
      "occurrences": 1,
      "lastRaisedAt": "2026-10-13T12:00:00.000Z",
      "acknowledgedAt": null,
      "acknowledgedBy": null,
      "resolvedAt": null,
      "resolvedBy": null,
      "delivery": {
        "status": "delivered",
        "attempts": 1,
        "lastError": null,
        "email": {
          "sent": 2,
          "failed": 0
        },
        "slack": [
          {
            "channelId": "sec_01m4ttwd3veh9apbewxheq5xad",
            "status": "sent",
            "at": "2026-10-13T12:00:00.000Z",
            "error": null
          }
        ]
      },
      "createdAt": "2026-10-13T12:00:00.000Z",
      "updatedAt": "2026-10-13T12:00:00.000Z",
      "version": 1
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

**Critical alerts of one legal entity, including resolved ones**

Arguments:

```json
{
  "severity": "critical",
  "status": ["open", "acked", "resolved"],
  "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
  "limit": 1
}
```

Result `output`:

```json
{
  "object": "list",
  "data": [
    {
      "id": "alr_01m4ttwd3veh9apbewxheq5xab",
      "object": "alert",
      "code": "REG_AUTO_BLOCKED",
      "severity": "critical",
      "family": "registrations",
      "message": "EU_OSS_NON_UNION was blocked for new consumer sales on 2026-11-07: the grace deadline 2026-11-10 is near and no application was submitted.",
      "link": "/console/acme/e/acme-hr/jurisdictions/EU_OSS_NON_UNION",
      "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
      "brandId": null,
      "livemode": true,
      "status": "open",
      "occurrences": 1,
      "lastRaisedAt": "2026-10-13T12:00:00.000Z",
      "acknowledgedAt": null,
      "acknowledgedBy": null,
      "resolvedAt": null,
      "resolvedBy": null,
      "delivery": {
        "status": "delivered",
        "attempts": 1,
        "lastError": null,
        "email": {
          "sent": 2,
          "failed": 0
        },
        "slack": [
          {
            "channelId": "sec_01m4ttwd3veh9apbewxheq5xad",
            "status": "sent",
            "at": "2026-10-13T12:00:00.000Z",
            "error": null
          }
        ]
      },
      "createdAt": "2026-10-13T12:00:00.000Z",
      "updatedAt": "2026-10-13T12:00:00.000Z",
      "version": 1
    }
  ],
  "has_more": true,
  "next_cursor": "alr_01m4ttwd3veh9apbewxheq5xab"
}
```

## `alerts_resolve`

**Resolve an alert.** Operation [`alerts.resolve`](https://ownrecord.io/docs/reference/alerts-resolve.md) · Organization level · permission `org:read` · risk tier `write` · since M7

Closes an alert by hand: the problem is dealt with. If it happens again, a new alert is raised (and
delivered again). Many alerts also resolve themselves when their condition clears (e.g. a retried job
finished); then `resolvedBy` is null. Resolving a resolved alert changes nothing.

Needs write access to what the alert is about at its legal entity or brand, as for acknowledging.

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument          | Type         | Required | Description                                                                                                                                                                                              |
| ----------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | ID (`alr_…`) | yes      | –                                                                                                                                                                                                        |
| `idempotency_key` | string       | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean      | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No alert with this ID that you may see, in this organization and mode.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): Your role may see the alert but not act on what it is about.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The alert changed at the same moment; retry.

### Example

**Close an alert that was dealt with**

Arguments:

```json
{
  "id": "alr_01m4ttwd3veh9apbewxheq5xab",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "alr_01m4ttwd3veh9apbewxheq5xab",
  "object": "alert",
  "code": "REG_AUTO_BLOCKED",
  "severity": "critical",
  "family": "registrations",
  "message": "EU_OSS_NON_UNION was blocked for new consumer sales on 2026-11-07: the grace deadline 2026-11-10 is near and no application was submitted.",
  "link": "/console/acme/e/acme-hr/jurisdictions/EU_OSS_NON_UNION",
  "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
  "brandId": null,
  "livemode": true,
  "status": "resolved",
  "occurrences": 1,
  "lastRaisedAt": "2026-10-13T12:00:00.000Z",
  "acknowledgedAt": null,
  "acknowledgedBy": null,
  "resolvedAt": "2026-10-13T12:30:00.000Z",
  "resolvedBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
  "delivery": {
    "status": "delivered",
    "attempts": 1,
    "lastError": null,
    "email": {
      "sent": 2,
      "failed": 0
    },
    "slack": [
      {
        "channelId": "sec_01m4ttwd3veh9apbewxheq5xad",
        "status": "sent",
        "at": "2026-10-13T12:00:00.000Z",
        "error": null
      }
    ]
  },
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-13T12:30:00.000Z",
  "version": 2
}
```