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

# Alerts API

> API reference for alert configuration, history, and triggering

# Alerts API

The Alerts API provides endpoints for configuring alert settings, viewing alert history, and manually triggering alerts.

<Note>
  **Scope**: Tenant-scoped; requires authenticated org context\
  **Availability**: Not available in SuperAdmin
</Note>

## Authentication

All requests require authentication. Include your API key in the `Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

See [Authentication](/api-reference/authentication) for details.

## Base URL

```
https://app.betterdata.co/api/admin/alerts
```

## Headers

All requests must include:

```
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```

## Endpoints

{/* this block is generated; do not edit by hand */}

| Method | Path                        | Summary                    | Auth    | Stability | Permissions        |
| ------ | --------------------------- | -------------------------- | ------- | --------- | ------------------ |
| `GET`  | `/api/admin/alerts/config`  | Get alert configuration    | session | stable    | admin.alerts.read  |
| `PUT`  | `/api/admin/alerts/config`  | Update alert configuration | session | stable    | admin.alerts.write |
| `GET`  | `/api/admin/alerts/history` | Get alert history          | session | stable    | admin.alerts.read  |
| `POST` | `/api/admin/alerts/trigger` | Manually trigger an alert  | session | beta ⚠️   | admin.alerts.write |

## Example Requests

### Get Alert Configuration

```bash theme={null}
curl -X GET "https://app.betterdata.co/api/admin/alerts/config" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

**Response:**

```json theme={null}
{
  "config": {
    "enabled": true,
    "destinations": [
      {
        "id": "dest_123",
        "type": "EMAIL",
        "value": "alerts@example.com",
        "name": "Operations Team",
        "enabled": true
      },
      {
        "id": "dest_456",
        "type": "WEBHOOK",
        "value": "https://example.com/webhook",
        "name": "External System",
        "enabled": true
      }
    ],
    "alertTypes": {
      "stockout": true,
      "lowAtp": true,
      "forecastDeviation": true,
      "expiry": true,
      "slowMoving": false,
      "overstock": false
    },
    "cooldownMinutes": 60
  }
}
```

### Update Alert Configuration

```bash theme={null}
curl -X PUT "https://app.betterdata.co/api/admin/alerts/config" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "enabled": true,
      "destinations": [
        {
          "id": "dest_123",
          "type": "EMAIL",
          "value": "alerts@example.com",
          "name": "Operations Team",
          "enabled": true
        },
        {
          "id": "dest_789",
          "type": "SLACK",
          "value": "https://hooks.slack.com/services/...",
          "name": "Slack Channel",
          "enabled": true
        }
      ],
      "alertTypes": {
        "stockout": true,
        "lowAtp": true,
        "forecastDeviation": true,
        "expiry": true,
        "slowMoving": true,
        "overstock": true
      },
      "cooldownMinutes": 30
    }
  }'
```

**Response:**

```json theme={null}
{
  "success": true,
  "config": {
    "enabled": true,
    "destinations": [...],
    "alertTypes": {...},
    "cooldownMinutes": 30
  }
}
```

### Get Alert History

```bash theme={null}
curl -X GET "https://app.betterdata.co/api/admin/alerts/history?fromDate=2024-01-01&toDate=2024-12-31&alertType=stockout&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

**Response:**

```json theme={null}
{
  "alerts": [
    {
      "id": "alert_123",
      "type": "stockout",
      "severity": "CRITICAL",
      "message": "Product SKU-123 is out of stock at location Main Warehouse",
      "productMasterId": "prod_123",
      "locationId": "loc_123",
      "triggeredAt": "2024-03-01T12:00:00Z",
      "delivered": true,
      "deliveredAt": "2024-03-01T12:00:05Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "total": 150,
    "totalPages": 3
  }
}
```

## Common Errors

### 401 Unauthorized

```json theme={null}
{
  "error": "Unauthorized"
}
```

**Cause**: Missing or invalid API key.

**Solution**: Include a valid API key in the `Authorization` header.

### 400 Bad Request

```json theme={null}
{
  "error": "Invalid configuration",
  "details": {
    "cooldownMinutes": ["Must be between 5 and 1440"]
  }
}
```

**Cause**: Invalid configuration values.

**Solution**: Review the configuration schema and ensure all values are valid.

### 403 Forbidden

```json theme={null}
{
  "error": "Forbidden"
}
```

**Cause**: Insufficient permissions. Alert configuration requires tenant admin permissions.

**Solution**: Ensure your API key has tenant admin permissions.

## Query Parameters

### Alert History

* `fromDate`: Start date (ISO string)
* `toDate`: End date (ISO string)
* `alertType`: Filter by alert type (`stockout`, `lowAtp`, `forecastDeviation`, `expiry`, `slowMoving`, `overstock`)
* `severity`: Filter by severity (`CRITICAL`, `HIGH`, `MEDIUM`, `LOW`)
* `delivered`: Filter by delivery status (boolean)
* `page`: Page number (default: 1)
* `limit`: Page size (default: 50, max: 100)

## Request/Response Schemas

### Alert Configuration

```typescript theme={null}
{
  enabled: boolean;
  destinations: Array<{
    id: string;
    type: "EMAIL" | "WEBHOOK" | "SLACK";
    value: string;
    name?: string;
    enabled: boolean;
  }>;
  alertTypes: {
    stockout: boolean;
    lowAtp: boolean;
    forecastDeviation: boolean;
    expiry: boolean;
    slowMoving: boolean;
    overstock: boolean;
  };
  cooldownMinutes: number; // 5-1440
}
```

### Alert History Item

```typescript theme={null}
{
  id: string;
  type: "stockout" | "lowAtp" | "forecastDeviation" | "expiry" | "slowMoving" | "overstock";
  severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
  message: string;
  productMasterId?: string;
  locationId?: string;
  channelId?: string;
  triggeredAt: string; // ISO datetime
  delivered: boolean;
  deliveredAt?: string; // ISO datetime
  destinations: Array<{
    type: string;
    value: string;
    delivered: boolean;
    deliveredAt?: string;
  }>;
}
```

***

## Related Pages

* [API Overview](/api-reference/overview)
* [Authentication](/api-reference/authentication)
* [Common Errors](/api-reference/errors)
* [Admin: Alerts Configuration](/admin/alerts-config)

***

## Permissions & Roles

<Warning>
  Alert configuration requires tenant admin permissions. Alert history viewing may require `admin.alerts.read` permission.
</Warning>