Better Data

API Reference

Alerts API

Edit this page

Alerts API

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

Scope: Workspace-scoped — requires authenticated organization context and valid credentials for that workspace.

Authentication

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

1Authorization: Bearer YOUR_API_KEY

See Authentication for details.

Base URL

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

Headers

All requests must include:

1Content-Type: application/json
2Authorization: Bearer YOUR_API_KEY

Endpoints

| 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

1curl -X GET "https://app.betterdata.co/api/admin/alerts/config" \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "Content-Type: application/json"

Response:

1{
2  "config": {
3    "enabled": true,
4    "destinations": [
5      {
6        "id": "dest_123",
7        "type": "EMAIL",
8        "value": "alerts@example.com",
9        "name": "Operations Team",
10        "enabled": true
11      },
12      {
13        "id": "dest_456",
14        "type": "WEBHOOK",
15        "value": "https://example.com/webhook",
16        "name": "External System",
17        "enabled": true
18      }
19    ],
20    "alertTypes": {
21      "stockout": true,
22      "lowAtp": true,
23      "forecastDeviation": true,
24      "expiry": true,
25      "slowMoving": false,
26      "overstock": false
27    },
28    "cooldownMinutes": 60
29  }
30}

Update Alert Configuration

1curl -X PUT "https://app.betterdata.co/api/admin/alerts/config" \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "config": {
6      "enabled": true,
7      "destinations": [
8        {
9          "id": "dest_123",
10          "type": "EMAIL",
11          "value": "alerts@example.com",
12          "name": "Operations Team",
13          "enabled": true
14        },
15        {
16          "id": "dest_789",
17          "type": "SLACK",
18          "value": "https://hooks.slack.com/services/...",
19          "name": "Slack Channel",
20          "enabled": true
21        }
22      ],
23      "alertTypes": {
24        "stockout": true,
25        "lowAtp": true,
26        "forecastDeviation": true,
27        "expiry": true,
28        "slowMoving": true,
29        "overstock": true
30      },
31      "cooldownMinutes": 30
32    }
33  }'

Response:

1{
2  "success": true,
3  "config": {
4    "enabled": true,
5    "destinations": [...],
6    "alertTypes": {...},
7    "cooldownMinutes": 30
8  }
9}

Get Alert History

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

Response:

1{
2  "alerts": [
3    {
4      "id": "alert_123",
5      "type": "stockout",
6      "severity": "CRITICAL",
7      "message": "Product SKU-123 is out of stock at location Main Warehouse",
8      "productMasterId": "prod_123",
9      "locationId": "loc_123",
10      "triggeredAt": "2024-03-01T12:00:00Z",
11      "delivered": true,
12      "deliveredAt": "2024-03-01T12:00:05Z"
13    }
14  ],
15  "pagination": {
16    "page": 1,
17    "pageSize": 50,
18    "total": 150,
19    "totalPages": 3
20  }
21}

Common Errors

401 Unauthorized

1{
2  "error": "Unauthorized"
3}

Cause: Missing or invalid API key.

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

400 Bad Request

1{
2  "error": "Invalid configuration",
3  "details": {
4    "cooldownMinutes": ["Must be between 5 and 1440"]
5  }
6}

Cause: Invalid configuration values.

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

403 Forbidden

1{
2  "error": "Forbidden"
3}

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

1{
2  enabled: boolean;
3  destinations: Array<{
4    id: string;
5    type: "EMAIL" | "WEBHOOK" | "SLACK";
6    value: string;
7    name?: string;
8    enabled: boolean;
9  }>;
10  alertTypes: {
11    stockout: boolean;
12    lowAtp: boolean;
13    forecastDeviation: boolean;
14    expiry: boolean;
15    slowMoving: boolean;
16    overstock: boolean;
17  };
18  cooldownMinutes: number; "cmt">// 5-1440
19}

Alert History Item

1{
2  id: string;
3  type: "stockout" | "lowAtp" | "forecastDeviation" | "expiry" | "slowMoving" | "overstock";
4  severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
5  message: string;
6  productMasterId?: string;
7  locationId?: string;
8  channelId?: string;
9  triggeredAt: string; "cmt">// ISO datetime
10  delivered: boolean;
11  deliveredAt?: string; "cmt">// ISO datetime
12  destinations: Array<{
13    type: string;
14    value: string;
15    delivered: boolean;
16    deliveredAt?: string;
17  }>;
18}

Permissions & Roles