Skip to main content

​
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

MethodPathSummaryAuthStabilityPermissions
GET/api/admin/alerts/configGet alert configurationsessionstableadmin.alerts.read
PUT/api/admin/alerts/configUpdate alert configurationsessionstableadmin.alerts.write
GET/api/admin/alerts/historyGet alert historysessionstableadmin.alerts.read
POST/api/admin/alerts/triggerManually trigger an alertsessionbeta ⚠️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": "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

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: 
{
  "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;
  }>;
}

​
Permissions & Roles

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