Skip to main content

​
Hosts API

​
List Hosts

GET /api/v1/hosts
Query Parameters:
  • status - Filter by status: healthy, warning, critical, offline
  • group - Filter by host group
Response: 
{
  "hosts": [
    {
      "id": "host_abc123",
      "name": "web-1",
      "hostname": "web-1.example.com",
      "status": "healthy",
      "os": "Ubuntu 22.04",
      "arch": "amd64",
      "cpu_cores": 4,
      "memory_total_gb": 16,
      "metrics": {
        "cpu_percent": 45,
        "memory_percent": 68,
        "disk_percent": 52,
        "load_average": 1.2
      },
      "containers": 3,
      "last_seen": "2024-01-15T10:30:00Z",
      "agent_version": "1.2.3"
    }
  ]
}

​
Get Host Details

GET /api/v1/hosts/:id
Response: 
{
  "id": "host_abc123",
  "name": "web-1",
  "hostname": "web-1.example.com",
  "status": "healthy",
  "os": "Ubuntu 22.04",
  "kernel": "5.15.0-91-generic",
  "arch": "amd64",
  "cpu": {
    "cores": 4,
    "model": "Intel Xeon E5-2686 v4",
    "usage_percent": 45,
    "user_percent": 35,
    "system_percent": 10,
    "load_1m": 1.2,
    "load_5m": 1.1,
    "load_15m": 0.9
  },
  "memory": {
    "total_gb": 16,
    "used_gb": 10.88,
    "available_gb": 5.12,
    "used_percent": 68,
    "swap_total_gb": 4,
    "swap_used_gb": 0.5,
    "cached_gb": 3.2
  },
  "disks": [
    {
      "mount": "/",
      "device": "/dev/sda1",
      "fs_type": "ext4",
      "total_gb": 100,
      "used_gb": 52,
      "available_gb": 48,
      "used_percent": 52
    }
  ],
  "network": {
    "interfaces": [
      {
        "name": "eth0",
        "ip": "10.0.0.5",
        "bytes_in_per_sec": 1024000,
        "bytes_out_per_sec": 512000
      }
    ]
  },
  "containers": 3,
  "uptime_seconds": 864000,
  "last_seen": "2024-01-15T10:30:00Z",
  "agent_version": "1.2.3",
  "tags": {
    "environment": "production",
    "role": "web"
  }
}

​
Get Host Metrics History

GET /api/v1/hosts/:id/metrics
Query Parameters:
  • period - Time period: hour, day, week
  • resolution - Data resolution: minute, 5min, hour
  • metrics - Comma-separated metrics: cpu,memory,disk,network
Response: 
{
  "host": "web-1",
  "period": "day",
  "resolution": "hour",
  "metrics": [
    {
      "timestamp": "2024-01-15T10:00:00Z",
      "cpu_percent": 45,
      "memory_percent": 68,
      "disk_percent": 52,
      "network_in_mb": 125,
      "network_out_mb": 45
    }
  ]
}

​
Get Host Processes

GET /api/v1/hosts/:id/processes
Query Parameters:
  • sort - Sort by: cpu, memory (default: cpu)
  • limit - Max results (default: 20)
Response: 
{
  "host": "web-1",
  "processes": [
    {
      "pid": 1234,
      "name": "ruby",
      "command": "puma -w 4 -t 8:8 -p 3000",
      "user": "deploy",
      "cpu_percent": 25.5,
      "memory_mb": 512,
      "memory_percent": 3.2,
      "started_at": "2024-01-10T08:00:00Z"
    }
  ]
}

​
Update Host

PUT /api/v1/hosts/:id
Request: 
{
  "name": "web-1-renamed",
  "tags": {
    "environment": "production",
    "role": "api"
  }
}

​
Delete Host

DELETE /api/v1/hosts/:id
Removes the host from monitoring (agent must be stopped first).