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

# Alerts & Monitoring

> Monitor data quality with automated alerts, webhook notifications, weekly digests, and mobile push notifications.

## What triggers alerts

ORCA automatically generates alerts when it detects changes in your data quality. Alerts are created after each analysis job completes by comparing results against previous runs of the same file.

| Alert type                  | Trigger condition                                                  | Severity                |
| --------------------------- | ------------------------------------------------------------------ | ----------------------- |
| `quality_drop`              | Quality score dropped by more than 5 points                        | `warning` or `critical` |
| `quality_improved`          | Quality score improved by more than 5 points                       | `info`                  |
| `gdpr_detected`             | New GDPR-sensitive columns found that were not in the previous run | `warning`               |
| `new_issue`                 | New high-severity format violations (above 10% rate)               | `warning`               |
| `ai_readiness_drop`         | AI readiness score dropped by 10 or more points                    | `warning` or `critical` |
| `ai_readiness_grade_change` | AI readiness grade dropped (e.g. B to C)                           | `warning`               |
| `ai_readiness_critical`     | AI readiness score fell below 60                                   | `critical`              |
| `contract_violation`        | A data contract rule was violated                                  | Matches rule severity   |

## Severity levels

| Severity   | Meaning                                                  |
| ---------- | -------------------------------------------------------- |
| `info`     | Positive or informational change (e.g. quality improved) |
| `warning`  | Notable degradation that should be reviewed              |
| `critical` | Significant regression requiring immediate attention     |

Critical alerts automatically trigger email notifications to users who have opted in via their alert preferences.

## Viewing alerts

### From the UI

Navigate to **Alerts** in the sidebar. Alerts are displayed newest first with filters for severity, type, and acknowledgment status. The navigation badge shows the count of unacknowledged alerts.

### From the API

```bash theme={null}
# List alerts (filterable)
curl https://api.orca-klavest.app/api/v1/alerts?severity=critical&acknowledged=false \
  -H "Authorization: Bearer $TOKEN"
```

Response:

```json theme={null}
{
  "data": {
    "alerts": [
      {
        "id": "a1b2c3d4-...",
        "type": "quality_drop",
        "severity": "critical",
        "title": "Quality score dropped 12 points on sales_data.csv",
        "message": "Score decreased from 85 to 73.",
        "acknowledged": false,
        "created_at": "2026-03-31T10:00:00Z"
      }
    ],
    "total": 1
  }
}
```

## Acknowledging alerts

Acknowledging an alert marks it as reviewed. This is audit-logged with the user who acknowledged it and the timestamp.

```bash theme={null}
# Acknowledge a single alert
curl -X POST https://api.orca-klavest.app/api/v1/alerts/{alert_id}/acknowledge \
  -H "Authorization: Bearer $TOKEN"

# Acknowledge all unacknowledged alerts
curl -X POST https://api.orca-klavest.app/api/v1/alerts/acknowledge-all \
  -H "Authorization: Bearer $TOKEN"
```

## Webhook integration

ORCA can deliver alerts to Slack and Microsoft Teams via webhooks. When an alert is created, it is automatically forwarded to all configured webhooks for your organisation.

Configure webhooks from **Settings > Webhooks** or via the API:

```bash theme={null}
curl -X POST https://api.orca-klavest.app/api/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data Team Slack",
    "url": "https://hooks.slack.com/services/...",
    "provider": "slack",
    "enabled": true
  }'
```

Webhook payloads include the alert type, severity, title, message, and metadata.

## Weekly digest emails

ORCA sends a weekly digest email summarising your organisation's data quality trends:

* Overall quality score changes
* AI readiness score movements and grade changes
* Number of new alerts and unresolved issues
* Top recommendations for improvement

Digest emails are sent to all organisation members. Individual users can manage their email preferences from **Settings > Notifications**.

## Push notifications (mobile)

The ORCA mobile app supports push notifications for critical alerts. When a critical alert is created, users with push notifications enabled receive an immediate notification on their device.

To enable push notifications:

1. Open the ORCA mobile app.
2. Go to **Settings > Notifications**.
3. Toggle on push notifications and allow the system permission.

Push tokens are registered via `expo-notifications` and stored securely on the server.

## API reference

| Method | Endpoint                                | Description                                                |
| ------ | --------------------------------------- | ---------------------------------------------------------- |
| `GET`  | `/api/v1/alerts`                        | List alerts (filter by `severity`, `type`, `acknowledged`) |
| `GET`  | `/api/v1/alerts/unacknowledged-count`   | Get count of unacknowledged alerts                         |
| `POST` | `/api/v1/alerts/{alert_id}/acknowledge` | Acknowledge a single alert                                 |
| `POST` | `/api/v1/alerts/acknowledge-all`        | Acknowledge all alerts                                     |