API: Event Stream (SSE)
A real-time Server-Sent Events feed of alerts, metrics, bans and server status.
SSE endpoint
Subscribe to a persistent Server-Sent Events stream.
Required scope: stream:read
# All events
curl -N \
-H "Authorization: Bearer YOUR_API_KEY" \
https://vigilhold.com/api/v1/stream
# Only alerts and bans, for two servers
curl -N \
-H "Authorization: Bearer YOUR_API_KEY" \
"https://vigilhold.com/api/v1/stream?events=alert,ban_event&servers=SERVER_ID_1,SERVER_ID_2"
events and servers are comma-separated lists. An unknown event name answers HTTP 400 with the list of valid ones.
Each message is a standard SSE frame; id counts the frames on this connection:
id: 42
event: alert
data: {"serverId":"4f2a9c1e8b7d6a50", ...}
retry: 3000
The first frame is connected, echoing your filters. A : ping comment line keeps idle connections open.
Changing filters
The stream is one-way: to change events or servers, close the connection and open a new one with the new parameters. There is no WebSocket endpoint for API keys.
Event types
- Type — Description
- alert — A new security alert
- metric — CPU / memory / disk / network sample from an agent
- metrics_delta — Only the metrics that changed noticeably since the last sample
- metric_spike — A metric well above its usual level for that server
- fleet_summary — Organization totals: online and offline servers, average and peak CPU and memory, unacknowledged alerts
- ban_event — An IP was banned or unbanned
- server_status — An agent came online or went offline
- scan_result — A vulnerability or malware scan finished with findings
- process_snapshot — A full process list from an agent
- network_connections — Listening ports and active connections
- service_list — A server's services
- baseline_update — Cortex recalculated a server's behaviour baseline
- io_metrics — Disk I/O throughput sample
- cortex_verdict — Cortex's verdict attached to an alert
- custom_event — An event pushed through the Event Ingest API
GET /api/v1/stream/events returns this list. A stream with no events filter also carries other dashboard events; those cannot be chosen with events.
Python example
import sseclient, requests, json
url = 'https://vigilhold.com/api/v1/stream'
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {'events': 'alert,ban_event'}
resp = requests.get(url, headers=headers,
params=params, stream=True)
for msg in sseclient.SSEClient(resp).events():
event = json.loads(msg.data)
print(msg.event, event.get('serverId'))
Tips
- Prefer the stream over polling /api/v1/servers for metrics.
- Filter to the event types you need: ?events=alert,ban_event drops metric frames from your stream.
- Use servers= to follow one server, for example in a single-server status view.