Alerts API | SentinelNerd

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"
  }
}