Skip to main content

Create Alert Rule

Create a new alert rule to receive notifications when data conditions are met.

Endpoint​

POST /api/alerts

Authentication​

Key TypeAllowed
Admin (dakkio_a_)✅ Yes
Write (dakkio_w_)✅ Yes
Read (dakkio_r_)❌ No

Recommended: Use a Write key (dakkio_w_) for creating alerts.

Natural Language Conditions

dakkio supports natural language alert conditions. Write conditions in plain English:

  • "temperature is greater than 30"
  • "humidity is less than 40"
  • "pressure drops below 1000"
  • "cpu usage exceeds 80 percent"

Request​

Headers​

HeaderTypeRequiredDescription
X-API-Keystring✅ YesYour Write or Admin API key
Content-Typestring✅ YesMust be application/json

Body Parameters​

ParameterTypeRequiredDescription
bucketIdstring✅ YesThe bucket ID
dataSourceIdstring✅ YesThe data source to monitor
namestring✅ YesAlert rule name
conditionstring✅ YesNatural language condition
webhookUrlstring✅ YesURL to receive notifications
cooldownMinutesnumber❌ NoMinutes between alerts (default: 5)

Example Request​

curl -X POST "https://api.dakkio.io/api/alerts" \
  -H "X-API-Key: dakkio_w_your_write_key..." \
  -H "Content-Type: application/json" \
  -d '{
    "bucketId": "507f1f77bcf86cd799439011",
    "dataSourceId": "507f1f77bcf86cd799439015",
    "name": "High Temperature Alert",
    "condition": "temperature is greater than 30",
    "webhookUrl": "https://hooks.slack.com/services/T00/B00/XXX",
    "cooldownMinutes": 5
  }'

Response​

Success Response (201 Created)​

{
  "message": "Alert rule created successfully",
  "alertRule": {
    "_id": "507f1f77bcf86cd799439017",
    "bucketId": "507f1f77bcf86cd799439011",
    "dataSourceId": "507f1f77bcf86cd799439015",
    "name": "High Temperature Alert",
    "condition": "temperature is greater than 30",
    "parsedCondition": {
      "field": "temperature",
      "operator": "gt",
      "value": 30
    },
    "webhookUrl": "https://hooks.slack.com/services/T00/B00/XXX",
    "status": "active",
    "cooldownMinutes": 5,
    "createdAt": "2024-01-15T10:35:00Z"
  }
}

Error Responses​

400 Bad Request - Invalid Condition​

{
  "error": "Validation Error",
  "message": "Could not parse condition. Please use natural language like 'temperature is greater than 30'"
}

400 Bad Request - Invalid Webhook URL​

{
  "error": "Validation Error",
  "message": "Invalid webhook URL"
}

401 Unauthorized​

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden​

{
  "error": "Forbidden",
  "message": "Read keys cannot create alert rules"
}

404 Not Found - Data Source​

{
  "error": "Not Found",
  "message": "Data source not found"
}

Code Examples​

JavaScript/Node.js​

const axios = require('axios');

async function createAlertRule(bucketId, dataSourceId, name, condition, webhookUrl, cooldownMinutes = 5) {
  const response = await axios.post(
    'https://api.dakkio.io/api/alerts',
    {
      bucketId,
      dataSourceId,
      name,
      condition,
      webhookUrl,
      cooldownMinutes
    },
    {
      headers: {
        'X-API-Key': process.env.DAKKIO_WRITE_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  return response.data.alertRule;
}

// Create a high temperature alert
const alert = await createAlertRule(
  '507f1f77bcf86cd799439011',
  '507f1f77bcf86cd799439015',
  'High Temperature Alert',
  'temperature is greater than 30',
  'https://hooks.slack.com/services/T00/B00/XXX',
  5
);

console.log(`Created alert: ${alert._id}`);

Python​

import requests
import os

def create_alert_rule(bucket_id, data_source_id, name, condition, webhook_url, cooldown_minutes=5):
    response = requests.post(
        'https://api.dakkio.io/api/alerts',
        headers={
            'X-API-Key': os.environ['DAKKIO_WRITE_KEY'],
            'Content-Type': 'application/json'
        },
        json={
            'bucketId': bucket_id,
            'dataSourceId': data_source_id,
            'name': name,
            'condition': condition,
            'webhookUrl': webhook_url,
            'cooldownMinutes': cooldown_minutes
        }
    )

    if response.status_code == 201:
        return response.json()['alertRule']
    else:
        print('Error:', response.json())
        return None

# Create a high temperature alert
alert = create_alert_rule(
    '507f1f77bcf86cd799439011',
    '507f1f77bcf86cd799439015',
    'High Temperature Alert',
    'temperature is greater than 30',
    'https://hooks.slack.com/services/T00/B00/XXX',
    5
)

if alert:
    print(f"Created alert: {alert['_id']}")

Condition Examples​

Comparison Operators​

temperature is greater than 30
humidity is less than 40
pressure is equal to 1013
cpu is not equal to 0

Percentage Conditions​

cpu usage exceeds 80 percent
memory usage is above 90%
disk usage is over 95 percent

Range Conditions​

temperature is between 20 and 25
humidity is outside 40 to 60

Drop/Rise Detection​

temperature drops below 10
pressure rises above 1020
value decreases by more than 5

Webhook Payload​

When an alert triggers, dakkio sends a POST request to your webhook URL:

{
  "alertId": "507f1f77bcf86cd799439017",
  "alertName": "High Temperature Alert",
  "condition": "temperature is greater than 30",
  "triggeredAt": "2024-01-15T14:30:00Z",
  "dataPoint": {
    "timestamp": "2024-01-15T14:30:00Z",
    "values": {
      "temperature": 32.5,
      "humidity": 55
    },
    "metadata": {
      "deviceId": "ESP32-001"
    }
  },
  "bucket": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "Home Sensors"
  },
  "dataSource": {
    "_id": "507f1f77bcf86cd799439015",
    "name": "Temperature Sensor"
  }
}

Best Practices​

1. Use Cooldown to Avoid Spam​

Set an appropriate cooldown to prevent alert fatigue:

// ✅ Good - 5 minute cooldown
"cooldownMinutes": 5

// ❌ Bad - no cooldown (may spam your webhook)
"cooldownMinutes": 0

2. Be Specific with Conditions​

// ✅ Good - clear threshold
"condition": "temperature is greater than 30"

// ❌ Vague
"condition": "temperature is high"  // What is "high"?

3. Name Alerts Descriptively​

// ✅ Good - clear purpose
"name": "Server Room High Temperature Alert"
"name": "Production Database CPU Warning"

// ❌ Bad - unclear
"name": "Alert 1"
"name": "Warning"

4. Test Your Webhook​

Before deploying, test your webhook URL works:

curl -X POST "https://your-webhook-url.com" \
  -H "Content-Type: application/json" \
  -d '{"test": true}'