Skip to main content

List Alerts

Retrieve a paginated list of security alerts with filtering and sorting.

Endpoint

GET /api/alerts
For API keys:
GET /api/external/alerts

Authentication

Requires JWT token or API key with read permissions.

Query Parameters

ParameterTypeDescriptionDefault
pageintegerPage number1
page_sizeintegerItems per page (max 100)20
statusstringFilter by status-
severitystringFilter by severity-
rule_idstringFilter by rule-
created_afterdatetimeAlerts after this time-
created_beforedatetimeAlerts before this time-
sort_bystringSort fieldcreated_at
sort_orderstringasc or descdesc

Status Values

  • new - Unreviewed
  • acknowledged - Under investigation
  • resolved - Investigation complete
  • false_positive - Tuned out

Severity Values

  • critical
  • high
  • medium
  • low
  • informational

Example Request

curl -H "Authorization: Bearer chad_ak_xxxxx..." \
  "https://chad.example.com/api/external/alerts?status=new&severity=high&page_size=50"

Response

{
  "items": [
    {
      "id": "alert-abc-123",
      "rule_id": "rule-def-456",
      "rule_title": "Failed Login Attempt",
      "severity": "high",
      "status": "new",
      "created_at": "2024-01-15T14:32:17Z",
      "source_ip": "192.168.1.50",
      "user": "admin",
      "host": "SERVER01",
      "enrichment": {
        "risk_level": "suspicious",
        "risk_score": 65
      }
    },
    {
      "id": "alert-ghi-789",
      "rule_id": "rule-jkl-012",
      "rule_title": "Suspicious PowerShell",
      "severity": "high",
      "status": "new",
      "created_at": "2024-01-15T14:30:00Z",
      "source_ip": "192.168.1.51",
      "user": "service_account",
      "host": "WORKSTATION05"
    }
  ],
  "total": 150,
  "page": 1,
  "page_size": 50,
  "pages": 3
}

Response Fields

FieldTypeDescription
idstringUnique alert identifier
rule_idstringSource rule ID
rule_titlestringRule name
severitystringAlert severity
statusstringCurrent status
created_atdatetimeDetection timestamp
source_ipstringSource IP (if available)
userstringUsername (if available)
hoststringHostname (if available)
enrichmentobjectTI enrichment results

Time Range Filtering

Filter by creation time:
# Last 24 hours
GET /api/alerts?created_after=2024-01-14T14:00:00Z

# Specific range
GET /api/alerts?created_after=2024-01-10T00:00:00Z&created_before=2024-01-15T23:59:59Z

Combined Filters

Multiple filters are ANDed:
# High severity, new status, from specific rule
GET /api/alerts?severity=high&status=new&rule_id=abc-123

Error Responses

401 Unauthorized

{
  "detail": "Could not validate credentials"
}

400 Bad Request

{
  "detail": "Invalid status value"
}

Code Examples

Python

import requests
from datetime import datetime, timedelta

API_KEY = "chad_ak_xxxxx..."
BASE_URL = "https://chad.example.com"

# Get new high-severity alerts from last 24 hours
yesterday = (datetime.utcnow() - timedelta(days=1)).isoformat() + "Z"

response = requests.get(
    f"{BASE_URL}/api/external/alerts",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={
        "status": "new",
        "severity": "high",
        "created_after": yesterday,
        "page_size": 100
    }
)

alerts = response.json()
print(f"Found {alerts['total']} new high-severity alerts")

for alert in alerts["items"]:
    print(f"  - {alert['rule_title']}: {alert.get('source_ip', 'unknown')}")

JavaScript

const yesterday = new Date(Date.now() - 86400000).toISOString();

const params = new URLSearchParams({
  status: 'new',
  severity: 'high',
  created_after: yesterday,
  page_size: '100'
});

const response = await fetch(
  `https://chad.example.com/api/external/alerts?${params}`,
  {
    headers: {
      'Authorization': 'Bearer chad_ak_xxxxx...'
    }
  }
);

const { items, total } = await response.json();
console.log(`Found ${total} alerts`);

cURL

# Get all new alerts
curl -H "Authorization: Bearer chad_ak_xxxxx..." \
  "https://chad.example.com/api/external/alerts?status=new"

# Get critical alerts
curl -H "Authorization: Bearer chad_ak_xxxxx..." \
  "https://chad.example.com/api/external/alerts?severity=critical"