API: Alerts
List, filter, and acknowledge threat alerts programmatically.
GET /api/v1/alerts
Returns alerts, newest first.
Required scope: alerts:read
Query parameters: - severity — critical | warning | info - serverId — one server - type — one alert type, e.g. ssh_brute_force - unacked — true for unacknowledged alerts only - since, until — milliseconds since the epoch - search — text in the message - limit — default 200, max 1000; offset for the next page
# Unacknowledged critical alerts only
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://vigilhold.com/api/v1/alerts?severity=critical&unacked=true"
Response shape
An array of alerts:
[
{
"id": 18342,
"server_id": "4f2a9c1e8b7d6a50",
"type": "ssh_brute_force",
"severity": "critical",
"message": "47 failed SSH logins from 185.220.101.45",
"ts": 1792548912456,
"acknowledged": 0,
"severity_reason": "Repeated failed logins from one address"
}
]
ts is milliseconds since the epoch. Critical and warning alerts also carry an explanation of what happened and what to do next.
POST /api/v1/alerts/:id/ack
Acknowledges one alert and records it in the audit log.
Required scope: alerts:write
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
https://vigilhold.com/api/v1/alerts/18342/ack
Response: { "ok": true }. Another organization's alert is a 404.
Acknowledging many alerts at once
Bulk acknowledgement is dashboard-only and needs an org admin: one call can silence every alert, so no API key can make it. From a script, acknowledge alerts one at a time with the call above.
Tips
- Subscribe to the alert SSE event type instead of polling this endpoint for real-time delivery.
- Disruptive actions Cortex took (isolating, locking down, stopping a process, a temporary ban) appear as alerts of type cortex_action, with action_taken and action_target saying what it did.