🖥️ Server Agent API

Submit Server Metrics

Report server system metrics from an agent script.

Endpoint

POST /agent/report

Headers

Content-Type: application/json
Accept: application/json

Request Body

{
    "agent_key": "your-agent-key-here",
    "cpu_usage": 23.5,
    "cpu_iowait": 1.2,
    "memory_usage": 67.4,
    "memory_total_mb": 8192,
    "swap_usage": 5.0,
    "disk_usage": [
        {
            "mount": "/",
            "usage": 45,
            "size": "50G",
            "used": "22G",
            "avail": "28G"
        }
    ],
    "network_rx_bytes": 1234567890,
    "network_tx_bytes": 987654321,
    "load_1m": 0.5,
    "load_5m": 0.3,
    "load_15m": 0.2,
    "os": "Ubuntu 24.04 LTS",
    "hostname": "web-server-1",
    "kernel": "6.5.0-44-generic"
}

Fields

Field	Type	Required	Description
agent_key	string	✅	Unique agent authentication key
cpu_usage	float	✅	CPU usage percentage (0-100)
cpu_iowait	float	❌	CPU I/O wait percentage
memory_usage	float	✅	Memory usage percentage (0-100)
memory_total_mb	integer	✅	Total RAM in megabytes
swap_usage	float	❌	Swap usage percentage
disk_usage	array	✅	Array of disk mount points
disk_usage[].mount	string	✅	Mount point path
disk_usage[].usage	float	✅	Usage percentage
disk_usage[].size	string	❌	Total size (human-readable)
disk_usage[].used	string	❌	Used space
disk_usage[].avail	string	❌	Available space
network_rx_bytes	integer	❌	Network bytes received
network_tx_bytes	integer	❌	Network bytes transmitted
load_1m	float	❌	1-minute load average
load_5m	float	❌	5-minute load average
load_15m	float	❌	15-minute load average
os	string	❌	Operating system name
hostname	string	❌	Server hostname
kernel	string	❌	Kernel version

Response

{
    "status": "ok"
}

Error Responses

Status Code	Meaning
422	Invalid agent key or missing required fields
404	Agent key not found

---

🔑 Finding Your Agent Key

1. Create a Server Agent monitor in the dashboard
2. The agent key is generated automatically
3. View it in the monitor's detail page