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.

Scope: Tenant-scoped; requires authenticated org context
Availability: Not available in SuperAdmin

Authentication

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

Authorization: Bearer YOUR_API_KEY

See 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

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

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

Response:

{
  "config": {
    "enabled": true,
    "destinations": [
      {
        "id": "dest_123",
        "type": "EMAIL",
        "value": "[e-mail]",
        "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

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": "[e-mail]",
          "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:

{
  "success": true,
  "config": {
    "enabled": true,
    "destinations": [...],
    "alertTypes": {...},
    "cooldownMinutes": 30
  }
}

Get Alert History

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:

{
  "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

{
  "error": "Unauthorized"
}

Cause: Missing or invalid API key.

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

400 Bad Request

{
  "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

{
  "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

{
  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

{
  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
• Authentication
• Common Errors
• Admin: Alerts Configuration

---

Permissions & Roles

Alert configuration requires tenant admin permissions. Alert history viewing may require admin.alerts.read permission.