Alerts API

The Alerts API lets you manage security alerts programmatically — list open alerts, acknowledge them, add comments, and resolve incidents.

Note

Alerts API endpoints require alerts:read for GET requests and alerts:write for acknowledge/resolve operations.

List Alerts

GET /v1/alerts

Retrieve a paginated list of alerts.

Parameter Type Required Description
status string Optional Filter by status: open, acknowledged, resolved
severity string Optional Filter by severity: critical, high, medium, low, info
rule_name string Optional Filter by rule name
source string Optional Filter by event source
from ISO 8601 Optional Start of time range
to ISO 8601 Optional End of time range
page integer Optional Page number (default: 1)
per_page integer Optional Results per page (default: 50)
Example Request 

curl -H "Authorization: Bearer snk_live_xxxx" \
      "https://api.sentinelnerd.com/v1/alerts?status=open&severity=critical,high"
Example Response 
{
  "data": [
    {
      "id": "alt_abc123",
      "rule_name": "net.ssh_brute_force",
      "title": "SSH Brute Force Detected",
      "description": "10 failed SSH logins from 203.0.113.42 in 5 minutes",
      "severity": "high",
      "status": "open",
      "source": "unifi_network",
      "event_count": 10,
      "first_event_at": "2025-01-15T14:27:01Z",
      "last_event_at": "2025-01-15T14:32:01Z",
      "created_at": "2025-01-15T14:32:01Z",
      "enrichment": {
        "geo": { "country": "CN", "city": "Beijing" },
        "abuse_ipdb": { "score": 87 }
      },
      "ai_analysis": {
        "summary": "Known malicious IP associated with SSH brute force campaigns...",
        "threat_score": 87
      }
    }
  ],
  "pagination": {
    "total": 12,
    "page": 1,
    "per_page": 50,
    "total_pages": 1
  }
}

Get Single Alert

GET /v1/alerts/:id

Retrieve a single alert with full details, related events, and timeline.

Acknowledge Alert

POST /v1/alerts/:id/acknowledge

Mark an alert as acknowledged, indicating someone is investigating.

Parameter Type Required Description
comment string Optional Optional comment explaining the acknowledgment
assignee string Optional Email of the person assigned to investigate
Acknowledge Alert 
curl -X POST https://api.sentinelnerd.com/v1/alerts/alt_abc123/acknowledge \
  -H "Authorization: Bearer snk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Investigating - appears to be from known scanner",
    "assignee": "security@example.com"
  }'

Resolve Alert

POST /v1/alerts/:id/resolve

Mark an alert as resolved, closing the incident.

Parameter Type Required Description
resolution string Required Resolution type: true_positive, false_positive, benign, duplicate
comment string Optional Resolution notes
actions_taken string[] Optional List of actions taken to resolve
Resolve Alert 
curl -X POST https://api.sentinelnerd.com/v1/alerts/alt_abc123/resolve \
  -H "Authorization: Bearer snk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "resolution": "true_positive",
    "comment": "Source IP blocked via active response. SSH hardening applied.",
    "actions_taken": [
      "Blocked IP 203.0.113.42 for 7 days",
      "Disabled password auth for SSH",
      "Enabled key-based auth only"
    ]
  }'

Add Comment

POST /v1/alerts/:id/comments

Add a comment to an alert's timeline.

Parameter Type Required Description
body string Required Comment text (supports Markdown)

Bulk Operations

POST /v1/alerts/bulk

Perform bulk operations on multiple alerts at once.

Parameter Type Required Description
alert_ids string[] Required Array of alert IDs to update
action string Required Action: acknowledge, resolve, reopen
resolution string Optional Required for resolve action
comment string Optional Optional comment for all alerts
Bulk Resolve 
curl -X POST https://api.sentinelnerd.com/v1/alerts/bulk \
  -H "Authorization: Bearer snk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "alert_ids": ["alt_abc123", "alt_def456", "alt_ghi789"],
    "action": "resolve",
    "resolution": "false_positive",
    "comment": "Scanner noise from security audit - safe to ignore"
  }'

Alert Statistics

GET /v1/alerts/stats

Get aggregate alert statistics for the specified time range.

Stats Response 
{
  "data": {
    "total": 156,
    "by_status": {
      "open": 12,
      "acknowledged": 8,
      "resolved": 136
    },
    "by_severity": {
      "critical": 3,
      "high": 24,
      "medium": 67,
      "low": 62
    },
    "mean_time_to_acknowledge": "12m",
    "mean_time_to_resolve": "2h 15m"
  }
}