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

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

All Vigilhold docs · Start a 14-day free trial