# Alert events

Base URL: `https://api.brixsignage.com`. Send `Authorization: Bearer $BRIX_API_KEY` unless an operation says Auth: none.

## GET /v1/alert-events

List alert events

List alerts that have fired against your screens, each combined with the screen's name. This endpoint is read-only: alerts open automatically when a condition is detected and close automatically on recovery. Only currently open alerts are returned, as a limited list, so a long history does not push them out.

Open events (up to 300, newest first) followed by recently closed ones (up to 300). Not paginated.

**Notes.**
- The route-registry description names `alert-rule.view`, but the route is gated by `screen.view`; `screen.view` is what a key needs.

Auth: Bearer token. Permission: `screen.view`.

```bash
curl "https://api.brixsignage.com/v1/alert-events" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of AlertEvent |  |
| `data[].id` | string | Alert event id. |
| `data[].code` | string | What fired, e.g. `connection-lost`, `display-off`, `storage-critical`. |
| `data[].severity` | string | `info`, `warning` or `critical`. |
| `data[].screenId` | string |  |
| `data[].screenName` | string | `(unknown screen)` if the screen is gone. |
| `data[].message` | string |  |
| `data[].nextAction` | string | Suggested next step; may be empty. |
| `data[].openedAt` | string | ISO-8601 timestamp (UTC). |
| `data[].closedAt` | string \| null | Null while open. |
| `data[].detail` | object \| null | Structured detail keyed by `kind` (`recovery`, `outage-history`, `network-unstable`, `display-off`), or null. |

Response 401: Missing, expired or revoked bearer token.

| Field | Type | Description |
| --- | --- | --- |
| `error` | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
| `message` | string | Human-readable explanation. Safe to show an operator. |
| `requestId` | string | Present on 5xx: quote it to support. |

Response 403: The token lacks the permission this operation needs (see `x-brix-permission`).

| Field | Type | Description |
| --- | --- | --- |
| `error` | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
| `message` | string | Human-readable explanation. Safe to show an operator. |
| `requestId` | string | Present on 5xx: quote it to support. |

Response 5XX: Server error. The body carries a `requestId` to quote to support.

| Field | Type | Description |
| --- | --- | --- |
| `error` | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
| `message` | string | Human-readable explanation. Safe to show an operator. |
| `requestId` | string | Present on 5xx: quote it to support. |

## POST /v1/alert-events/{id}/close

Close an alert event

Manually close an alert event before it would close automatically on recovery. Access is checked against the screen where the alert fired.

**Notes.**
- The route-registry description names `alert-rule.edit`, but the route is gated by `screen.edit` at the event's location.

Auth: Bearer token. Permission: `screen.edit`.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Alert event id. |

```bash
curl -X POST "https://api.brixsignage.com/v1/alert-events/{id}/close" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | AlertEvent | One firing of an alert rule against a screen. |
| `data.id` | string | Alert event id. |
| `data.code` | string | What fired, e.g. `connection-lost`, `display-off`, `storage-critical`. |
| `data.severity` | string | `info`, `warning` or `critical`. |
| `data.screenId` | string |  |
| `data.screenName` | string | `(unknown screen)` if the screen is gone. |
| `data.message` | string |  |
| `data.nextAction` | string | Suggested next step; may be empty. |
| `data.openedAt` | string | ISO-8601 timestamp (UTC). |
| `data.closedAt` | string \| null | Null while open. |
| `data.detail` | object \| null | Structured detail keyed by `kind` (`recovery`, `outage-history`, `network-unstable`, `display-off`), or null. |

Response 401: Missing, expired or revoked bearer token.

| Field | Type | Description |
| --- | --- | --- |
| `error` | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
| `message` | string | Human-readable explanation. Safe to show an operator. |
| `requestId` | string | Present on 5xx: quote it to support. |

Response 403: The token lacks the permission this operation needs (see `x-brix-permission`).

| Field | Type | Description |
| --- | --- | --- |
| `error` | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
| `message` | string | Human-readable explanation. Safe to show an operator. |
| `requestId` | string | Present on 5xx: quote it to support. |

Response 404: No such event.

| Field | Type | Description |
| --- | --- | --- |
| `error` | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
| `message` | string | Human-readable explanation. Safe to show an operator. |
| `requestId` | string | Present on 5xx: quote it to support. |

Response 409: `already_closed`.

| Field | Type | Description |
| --- | --- | --- |
| `error` | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
| `message` | string | Human-readable explanation. Safe to show an operator. |
| `requestId` | string | Present on 5xx: quote it to support. |

Response 5XX: Server error. The body carries a `requestId` to quote to support.

| Field | Type | Description |
| --- | --- | --- |
| `error` | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
| `message` | string | Human-readable explanation. Safe to show an operator. |
| `requestId` | string | Present on 5xx: quote it to support. |