Skip to content

Creating Alerts

Create alert configurations to monitor for security events and policy violations.

Endpoint

POST /api/alerts

Creates a new alert with conditions, thresholds, and notification settings.

Authentication

Requires API Key with Policy Definition permission.

Request Body

Field Type Required Description
name string Yes Alert name (1-64 chars)
description string No Description (0-128 chars)
enable boolean Yes Whether alert is active
thresholdTime string Yes Time interval value (e.g., "5", "15", "30") or full CRON expression when type is "CRON"
thresholdType string Yes Time unit: "minutes", "hours", "days", or "CRON"
notificationTypes string[] Yes ["email"], ["slack"], ["teams"], ["webhook"]
emailRecipients string[] Conditional Email addresses (required if email in notificationTypes)
slackChannels string[] Conditional Slack channel UUIDs (required if slack in notificationTypes)
conditions array Yes Array of condition objects

Condition Object

Field Type Description
type string Condition type (see Condition Types)
values string[] Values to match
isNot boolean Negate the condition

Response

Returns the created alert object with an id field:

Response Format 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "High-Volume PII Detection",
  "description": "Alert when >10 PII detections in 5 minutes",
  "enable": true,
  "thresholdTime": "5",
  "thresholdType": "minutes",
  "notificationTypes": ["email", "slack"],
  "emailRecipients": ["security@company.com"],
  "slackChannels": ["channel-uuid"],
  "conditions": [
    {
      "type": "detected",
      "values": ["true"],
      "isNot": false
    }
  ],
  "createdAt": 1704067200,
  "updatedAt": 1704067200
}

Examples

Alert on Blocked Requests

Trigger alert when Shield blocks requests (5 or more blocks in 15 minutes).

curl -X POST "https://your-shield-host:8080/api/alerts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Blocked Request Alert",
    "description": "Alert when requests are blocked by Shield",
    "enable": true,
    "notificationTypes": ["email"],
    "emailRecipients": ["security@company.com"],
    "thresholdTime": "15",
    "thresholdType": "minutes",
    "conditions": [
      {
        "type": "blocked",
        "values": ["true"],
        "isNot": false
      }
    ]
  }'

import requests

BASE_URL = "https://your-shield-host:8080"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

alert = {
    "name": "Blocked Request Alert",
    "description": "Alert when requests are blocked by Shield",
    "enable": True,
    "notificationTypes": ["email"],
    "emailRecipients": ["security@company.com"],
    "thresholdTime": "15",
    "thresholdType": "minutes",
    "conditions": [
        {
            "type": "blocked",
            "values": ["true"],
            "isNot": False
        }
    ]
}

response = requests.post(f"{BASE_URL}/api/alerts", headers=HEADERS, json=alert)
print(f"Created alert: {response.json()['id']}")

const axios = require('axios');

const BASE_URL = 'https://your-shield-host:8080';
const HEADERS = { 'Authorization': 'Bearer YOUR_API_KEY' };

const alert = {
  name: 'Blocked Request Alert',
  description: 'Alert when requests are blocked by Shield',
  enable: true,
  notificationTypes: ['email'],
  emailRecipients: ['security@company.com'],
  conditions: [
    {
      type: 'blocked',
      values: ['true'],
      isNot: false
    }
  ]
};

const response = await axios.post(`${BASE_URL}/api/alerts`, alert, { headers: HEADERS });
console.log(`Created alert: ${response.data.id}`);
Alert on Specific Data Types

Alert immediately when SSN or credit card is detected.

# Get data type IDs
DATATYPES=$(curl -s -X GET "https://your-shield-host:8080/api/datatypes" \
  -H "Authorization: Bearer YOUR_API_KEY")

SSN_ID=$(echo $DATATYPES | jq -r '.items[] | select(.type=="ssn") | .id')
CC_ID=$(echo $DATATYPES | jq -r '.items[] | select(.type=="credit_card") | .id')

# Create alert
curl -X POST "https://your-shield-host:8080/api/alerts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Financial PII Detection\",
    \"description\": \"Alert on SSN or credit card detection\",
    \"enable\": true,
    \"notificationTypes\": [\"slack\"],
    \"slackChannels\": [\"channel-uuid\"],
    \"thresholdTime\": \"1\",
    \"thresholdType\": \"minutes\",
    \"conditions\": [
      {
        \"type\": \"datatypes_detected\",
        \"values\": [\"$SSN_ID\", \"$CC_ID\"],
        \"isNot\": false
      }
    ]
  }"

import requests

BASE_URL = "https://your-shield-host:8080"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# Get data type IDs
datatypes = requests.get(f"{BASE_URL}/api/datatypes", headers=HEADERS).json()
ssn_id = next(d["id"] for d in datatypes["items"] if d["type"] == "ssn")
cc_id = next(d["id"] for d in datatypes["items"] if d["type"] == "credit_card")

alert = {
    "name": "Financial PII Detection",
    "description": "Alert on SSN or credit card detection",
    "enable": True,
    "notificationTypes": ["slack"],
    "slackChannels": ["channel-uuid"],
    "thresholdTime": "1",
    "thresholdType": "minutes",
    "conditions": [
        {
            "type": "datatypes_detected",
            "values": [ssn_id, cc_id],
            "isNot": False
        }
    ]
}

response = requests.post(f"{BASE_URL}/api/alerts", headers=HEADERS, json=alert)
print(f"Created alert: {response.json()['id']}")

const axios = require('axios');

const BASE_URL = 'https://your-shield-host:8080';
const HEADERS = { 'Authorization': 'Bearer YOUR_API_KEY' };

// Get data type IDs
const datatypesResponse = await axios.get(`${BASE_URL}/api/datatypes`, { headers: HEADERS });
const ssnId = datatypesResponse.data.items.find(d => d.type === 'ssn').id;
const ccId = datatypesResponse.data.items.find(d => d.type === 'credit_card').id;

const alert = {
  name: 'Financial PII Detection',
  description: 'Alert on SSN or credit card detection',
  enable: true,
  notificationTypes: ['slack'],
  slackChannels: ['channel-uuid'],
  conditions: [
    {
      type: 'datatypes_detected',
      values: [ssnId, ccId],
      isNot: false
    }
  ]
};

const response = await axios.post(`${BASE_URL}/api/alerts`, alert, { headers: HEADERS });
console.log(`Created alert: ${response.data.id}`);
Alert on High-Volume Activity

Alert when a single user triggers more than 50 detections in 1 hour.

```bash curl -X POST "https://your-shield-host:8080/api/alerts" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Suspicious User Activity", "description": "Alert when single user triggers >50 detections in 1 hour", "enable": true, "notificationTypes": ["email", "teams"], "emailRecipients": ["soc@company.com"],

"thresholdTime": "1", "thresholdType": "hours", "conditions": [ { "type": "detected", "values": ["true"], "isNot": false } ] }' ```

=== "Python"

    ```python
    import requests

    BASE_URL = "https://your-shield-host:8080"
    HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

    alert = {
        "name": "Suspicious User Activity",
        "description": "Alert when single user triggers >50 detections in 1 hour",
        "enable": True,
        "notificationTypes": ["email", "teams"],
        "emailRecipients": ["soc@company.com"],

"thresholdTime": "1", "thresholdType": "hours", "conditions": [ { "type": "detected", "values": ["true"], "isNot": False } ] }

    response = requests.post(f"{BASE_URL}/api/alerts", headers=HEADERS, json=alert)
    print(f"Created alert: {response.json()['id']}")
    ```

=== "Node.js"

    ```javascript
    const axios = require('axios');

    const BASE_URL = 'https://your-shield-host:8080';
    const HEADERS = { 'Authorization': 'Bearer YOUR_API_KEY' };

    const alert = {
      name: 'Suspicious User Activity',
      description: 'Alert when single user triggers >50 detections in 1 hour',
      enable: true,
      notificationTypes: ['email', 'teams'],
      emailRecipients: ['soc@company.com'],
      thresholdTime: '1',
      thresholdType: 'hours',
      conditions: [
        {
          type: 'detected',
          values: ['true'],
          isNot: false
        }
      ]
    };

    const response = await axios.post(`${BASE_URL}/api/alerts`, alert, { headers: HEADERS });
    console.log(`Created alert: ${response.data.id}`);
    ```

Error Responses

Status Code Description Solution
400 Invalid request body Check field validation requirements
401 Invalid or expired API key Verify authentication
403 Insufficient permissions Key needs Policy Definition permission
409 Alert name already exists Use a unique name or update the existing alert