API: Servers
List and inspect servers, read live metrics, filter by status or region.
GET /api/v1/servers
Returns all servers in your fleet with current health metrics.
Required scope: servers:read
Query parameters: - status — online | offline - limit — max results (default 50, max 500) - offset — skip this many (for the next page)
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://vigilhold.com/api/v1/servers?status=offline"
Response shape
{
"servers": [
{
"id": "4f2a9c1e8b7d6a50",
"hostname": "db-primary",
"ip_address": "10.0.0.12",
"status": "online",
"os": "Debian 12",
"arch": "x64",
"cpu_cores": 8,
"mem_total_gb": null,
"role_classification": "database",
"last_seen": 1792548912456,
"latestMetrics": { "cpu_pct": 44, "mem_pct": 78, "disk_pct": 52, "ts": 1792548910000 }
}
],
"total": 1,
"limit": 50,
"offset": 0
}
total counts the servers on this page. Times are milliseconds since the epoch.
GET /api/v1/servers/:id
Returns a single server by its ID.
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://vigilhold.com/api/v1/servers/4f2a9c1e8b7d6a50
The response has the same fields as an item from the list endpoint, without latestMetrics, plus version (the agent's version), tags, nat_behind and last_known_ip.
Related endpoints for one server: - GET /api/v1/servers/:id/processes — running processes, up to 200 (scope processes:read) - GET /api/v1/servers/:id/alerts — its alerts from the last 24 hours, with severity, limit and offset (scope alerts:read)
GET /api/v1/servers/:id/metrics
Returns the server's recent metric samples.
Required scope: metrics:read
Query parameters: - minutes — how far back, 5 to 1440 (default 60)
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://vigilhold.com/api/v1/servers/4f2a9c1e8b7d6a50/metrics?minutes=360"
Response: { "serverId": "...", "minutesBack": 360, "since": <ms>, "datapoints": [...] }.
Tips
- Don't poll /api/v1/servers for live metrics — subscribe to the event stream instead.
- For real-time metrics, subscribe to the SSE stream filtered to metric events.