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

# Notifications & Alert Rules

> Browse your notifications feed, mark items read, and create alert rules that fire when predictions or issue counts cross a threshold.

Causeloop keeps you informed through two complementary systems: a **notifications feed** that logs events relevant to you, and **alert rules** that proactively push signals to Slack, PagerDuty, or email when risk crosses a threshold you define.

<Note>
  This page covers the notifications feed and alert rule management. For notification delivery preferences (which channels you receive notifications on, and for which event types), see [Settings → Notifications](/product-guide/settings/notifications).
</Note>

## Notifications feed

### Viewing your notifications

Click the **bell icon** in the top bar to open the notifications panel. The bell displays an unread badge count that updates in real time.

The feed is available via `GET /v1/me/notifications/feed`. It supports:

| Parameter | Description                              |
| --------- | ---------------------------------------- |
| `unread`  | `true` to show only unread notifications |
| `limit`   | Page size (default 20)                   |
| `cursor`  | Pagination cursor                        |

Each notification item contains:

| Field                       | Description                                                                 |
| --------------------------- | --------------------------------------------------------------------------- |
| `id`                        | Notification ID                                                             |
| `type`                      | Dot-separated event type (e.g. `prediction.alert`, `verification.verified`) |
| `title`                     | Human-readable summary                                                      |
| `entity_type` / `entity_id` | The target entity this notification is about (e.g. `pattern` / `pat_...`)   |
| `link`                      | In-app URL derived from the target entity (e.g. `/patterns/{id}`)           |
| `read`                      | `true` if the notification has been read                                    |
| `created_at`                | ISO 8601 UTC timestamp                                                      |

### Notification types

Notification rows are materialized from real product events, fanned out to one row per active workspace member — never a demo placeholder. Every notification you see maps to something that actually happened:

| Type                    | Trigger                                                                                                                  |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `prediction.alert`      | Crest forewarning — a pattern's recurrence hazard crossed an alert rule's threshold                                      |
| `verification.verified` | A fix's proof-window CUSUM statistic crossed its positive boundary — the fix held                                        |
| `verification.failed`   | A fix's proof-window CUSUM statistic crossed its negative boundary — the fix did not hold and the recommendation reopens |
| `engine.run.completed`  | An engine run finished — the message includes the resulting loop and theme counts                                        |

### Marking notifications read

**Mark a single notification read**

Click the notification row to open the linked entity. The notification is marked read automatically. You can also call `POST /v1/me/notifications/feed/{id}/read` directly.

**Mark all notifications read**

Click **Mark all read** in the notifications panel header, or call:

```bash theme={null}
POST /v1/me/notifications/feed/read-all
{}
```

To clear only a specific category, pass a `type` prefix:

```bash theme={null}
POST /v1/me/notifications/feed/read-all
{ "type": "prediction." }
```

This returns `{ "marked": 8, "unread_count": 4 }` — the count of items marked and the remaining unread count.

**Dismiss a notification**

Click the dismiss (×) button on a notification row, or call `DELETE /v1/me/notifications/feed/{id}`.

### Unread count

The unread badge is driven by `GET /v1/me/notifications/unread-count`. The Dashboard bell icon uses the same endpoint to show the badge dot.

***

## Alert rules

Alert rules let you define conditions on predictions or issues that trigger proactive notifications — before an incident occurs.

### The Alert rules panel

Alert rules appear on the [Predictions screen](/product-guide/predictions#alert-rules-panel) in a sidebar panel. Each rule shows:

* **Name** — a human-readable label (e.g. "Critical pattern alert")
* **Condition summary** — threshold, window, and delivery channels (e.g. `≥85% / 3D · SLACK + PAGERDUTY`)
* **Enabled toggle** — click to enable or disable the rule without deleting it

### Creating an alert rule

<Steps>
  <Step title="Open the Predictions screen">
    Navigate to **Predictions** in the left sidebar.
  </Step>

  <Step title="Click New alert rule">
    The rule creation dialog opens. (Alternatively, use the API directly — see below.)
  </Step>

  <Step title="Set the rule name">
    Enter a descriptive name, such as "Inventory N+1 watch".
  </Step>

  <Step title="Define the scope">
    Choose which patterns or entity types this rule watches. Examples:

    * A specific `pattern_id` to watch one pattern
    * A workspace-wide rule that watches all predictions
  </Step>

  <Step title="Set the threshold">
    Enter the probability threshold (0.0–1.0) and the prediction window in days (≥ 1). The rule fires when any in-scope prediction exceeds this probability within the window.
  </Step>

  <Step title="Choose delivery channels">
    Select one or more channels: `email`, `slack`, `pagerduty`, or `in_app`. For Slack, configure the channel ID in your [integration settings](/integrations/overview). For PagerDuty, configure the service key.
  </Step>

  <Step title="Save">
    The rule is active immediately. You can test it against live data using `POST /v1/alert-rules/{id}/test`.
  </Step>
</Steps>

The rule is created via `POST /v1/alert-rules` with a body such as:

```json theme={null}
{
  "name": "Critical pattern alert",
  "scope": { "workspace": true },
  "threshold": {
    "probability": 0.85,
    "window_days": 3
  },
  "channels": ["slack", "pagerduty"],
  "severity": "critical"
}
```

### Managing alert rules

| Action        | How                                                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| List rules    | `GET /v1/alert-rules`                                                                                                    |
| Get a rule    | `GET /v1/alert-rules/{id}`                                                                                               |
| Update a rule | `PATCH /v1/alert-rules/{id}` — update name, threshold, channels, or enabled state                                        |
| Delete a rule | `DELETE /v1/alert-rules/{id}`                                                                                            |
| Test a rule   | `POST /v1/alert-rules/{id}/test` — evaluates the rule against current live predictions and returns whether it would fire |
| Snooze a rule | `PATCH /v1/alert-rules/{id}/snooze` — suppress the rule for a duration (e.g. during a planned maintenance window)        |

### Snoozing a rule

To silence an alert rule temporarily without deleting it:

```bash theme={null}
PATCH /v1/alert-rules/{id}/snooze
{
  "snoozed_until": "2026-06-20T09:00:00Z"
}
```

The rule resumes firing automatically after `snoozed_until`. To un-snooze early, send `snoozed_until: null`.

### Alert rule fields

| Field                   | Type           | Description                                                |
| ----------------------- | -------------- | ---------------------------------------------------------- |
| `name`                  | string         | Rule display name (required, non-empty)                    |
| `scope`                 | object         | Which patterns or entities the rule watches                |
| `threshold.probability` | float          | Minimum probability to trigger (0.0–1.0)                   |
| `threshold.window_days` | integer        | Prediction window in days (≥ 1)                            |
| `channels`              | string\[]      | Delivery channels: `email`, `slack`, `pagerduty`, `in_app` |
| `severity`              | string         | Alert severity: `critical`, `high`, `medium`, `low`        |
| `enabled`               | boolean        | Whether the rule is active                                 |
| `snoozed_until`         | string \| null | ISO timestamp; rule is silenced until this time            |

## API reference

**Notifications**

| Endpoint                                   | Description                     |
| ------------------------------------------ | ------------------------------- |
| `GET /v1/me/notifications/feed`            | Paginated notification feed     |
| `GET /v1/me/notifications/unread-count`    | Unread badge count              |
| `POST /v1/me/notifications/feed/read-all`  | Mark all (or a category) read   |
| `POST /v1/me/notifications/feed/{id}/read` | Mark a single notification read |
| `DELETE /v1/me/notifications/feed/{id}`    | Dismiss a notification          |

**Alert rules**

| Endpoint                            | Description                 |
| ----------------------------------- | --------------------------- |
| `GET /v1/alert-rules`               | List workspace alert rules  |
| `POST /v1/alert-rules`              | Create an alert rule        |
| `GET /v1/alert-rules/{id}`          | Get an alert rule           |
| `PATCH /v1/alert-rules/{id}`        | Update an alert rule        |
| `DELETE /v1/alert-rules/{id}`       | Delete an alert rule        |
| `POST /v1/alert-rules/{id}/test`    | Test rule against live data |
| `PATCH /v1/alert-rules/{id}/snooze` | Snooze a rule               |

## Related pages

<CardGroup cols={2}>
  <Card title="Predictions" icon="chart-line" href="/product-guide/predictions">
    Alert rules fire on prediction thresholds — review the predictions screen.
  </Card>

  <Card title="Search & Activity" icon="magnifying-glass" href="/product-guide/search-activity">
    The activity feed shows all fired alerts as events.
  </Card>

  <Card title="Settings — Notifications" icon="sliders" href="/product-guide/settings/notifications">
    Configure which channels you receive notifications on and for which event types.
  </Card>
</CardGroup>