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

All Vigilhold docs · Start a 14-day free trial