Host Management API
Complete host and agent management including registration, system operations, and data collection.
Overview
The Host Management API provides comprehensive control over registered hosts and their agents. This includes system information collection, remote operations, hardware updates, and fleet management capabilities.
Fleet Management
GET
/api/v1/fleet/status
Get overall fleet status and statistics.
🔒 Authentication Required
Response (200 OK)
{
"total_hosts": 150,
"online_hosts": 142,
"offline_hosts": 8,
"pending_approval": 3,
"agents_with_errors": 2,
"last_updated": "2024-01-01T12:00:00Z"
}
GET
/api/v1/fleet/agents
List all registered agents in the fleet.
🔒 Authentication Required
Response (200 OK)
{
"agents": [
{
"hostname": "web-server-01",
"id": "uuid",
"status": "online",
"last_seen": "2024-01-01T12:00:00Z",
"platform": "linux",
"version": "1.0.0",
"ip_address": "192.168.1.100"
}
]
}
GET
/api/v1/fleet/agent/{hostname}
Get detailed information about a specific agent.
🔒 Authentication Required
Path Parameters
hostname(string) - Hostname of the target agent
Response (200 OK)
{
"hostname": "web-server-01",
"id": "uuid",
"status": "online",
"last_seen": "2024-01-01T12:00:00Z",
"platform": "linux",
"os_version": "Ubuntu 22.04 LTS",
"agent_version": "1.0.0",
"ip_address": "192.168.1.100",
"cpu_count": 4,
"memory_total": "8 GB",
"disk_usage": {
"total": "100 GB",
"used": "45 GB",
"free": "55 GB"
},
"uptime": "15 days, 3 hours, 22 minutes"
}Host Operations
POST
/api/v1/fleet/agent/{hostname}/command
Execute a command on a specific host.
🔒 Authentication Required
Path Parameters
hostname(string) - Target hostname
Request Body
{
"command": "ls -la /var/log",
"timeout": 30
}Response (200 OK)
{
"execution_id": "uuid",
"status": "executed",
"stdout": "total 156\ndrwxr-xr-x 8 root root 4096 Jan 1 12:00 .\n...",
"stderr": "",
"exit_code": 0,
"execution_time": 0.245
}
POST
/api/v1/host/reboot/{host_id}
Reboot a specific host.
🔒 Authentication Required
Path Parameters
host_id(string) - UUID of the target host
Request Body
{
"force": false,
"delay_seconds": 60,
"message": "System maintenance reboot"
}Response (200 OK)
{
"message": "Reboot command sent successfully",
"scheduled_time": "2024-01-01T12:01:00Z",
"execution_id": "uuid"
}
POST
/api/v1/host/shutdown/{host_id}
Shutdown a specific host.
🔒 Authentication Required
Path Parameters
host_id(string) - UUID of the target host
Request Body
{
"force": false,
"delay_seconds": 60,
"message": "Scheduled maintenance shutdown"
}Response (200 OK)
{
"message": "Shutdown command sent successfully",
"scheduled_time": "2024-01-01T12:01:00Z",
"execution_id": "uuid"
}Hardware and System Information
POST
/api/v1/host/{host_id}/update-hardware
Request hardware information update from a host.
🔒 Authentication Required
Path Parameters
host_id(string) - UUID of the target host
Response (200 OK)
{
"message": "Hardware update request sent",
"request_id": "uuid",
"estimated_completion": "2024-01-01T12:02:00Z"
}
GET
/api/v1/host/{host_id}/storage
Get storage information for a specific host.
🔒 Authentication Required
Response (200 OK)
{
"storage_devices": [
{
"device": "/dev/sda1",
"mount_point": "/",
"filesystem": "ext4",
"total_size": "100 GB",
"used_space": "45 GB",
"free_space": "55 GB",
"usage_percentage": 45
}
],
"last_updated": "2024-01-01T12:00:00Z"
}
GET
/api/v1/host/{host_id}/network
Get network interface information for a specific host.
🔒 Authentication Required
Response (200 OK)
{
"network_interfaces": [
{
"interface": "eth0",
"ip_address": "192.168.1.100",
"netmask": "255.255.255.0",
"gateway": "192.168.1.1",
"mac_address": "00:11:22:33:44:55",
"status": "up",
"speed": "1000 Mbps"
}
],
"last_updated": "2024-01-01T12:00:00Z"
}
GET
/api/v1/host/{host_id}/users
Get user accounts on a specific host.
🔒 Authentication Required
Response (200 OK)
{
"users": [
{
"username": "admin",
"uid": 1000,
"gid": 1000,
"home_directory": "/home/admin",
"shell": "/bin/bash",
"last_login": "2024-01-01T08:30:00Z"
}
],
"last_updated": "2024-01-01T12:00:00Z"
}
GET
/api/v1/host/{host_id}/groups
Get user groups on a specific host.
🔒 Authentication Required
Response (200 OK)
{
"groups": [
{
"name": "sudo",
"gid": 27,
"members": ["admin", "user1"]
}
],
"last_updated": "2024-01-01T12:00:00Z"
}Software and Package Information
POST
/api/v1/host/refresh/software/{host_id}
Request software inventory refresh for a specific host.
🔒 Authentication Required
Path Parameters
host_id(string) - UUID of the target host
Response (200 OK)
{
"message": "Software refresh request sent",
"request_id": "uuid",
"estimated_completion": "2024-01-01T12:05:00Z"
}
GET
/api/v1/host/{host_id}/software
Get installed software packages on a specific host.
🔒 Authentication Required
Response (200 OK)
{
"packages": [
{
"name": "nginx",
"version": "1.18.0",
"architecture": "amd64",
"status": "installed",
"description": "High performance web server",
"install_date": "2024-01-01T10:00:00Z"
}
],
"total_packages": 1847,
"last_updated": "2024-01-01T12:00:00Z"
}Bulk Operations
POST
/api/v1/fleet/broadcast/command
Execute a command across multiple hosts simultaneously.
🔒 Authentication Required
Request Body
{
"command": "systemctl status nginx",
"hostnames": ["web-01", "web-02", "web-03"],
"timeout": 30,
"parallel": true
}Response (200 OK)
{
"batch_id": "uuid",
"total_hosts": 3,
"results": [
{
"hostname": "web-01",
"status": "completed",
"exit_code": 0,
"stdout": "● nginx.service - A high performance web server...",
"execution_time": 0.123
}
]
}
POST
/api/v1/hosts/request-hardware-update
Request hardware information update from multiple hosts.
🔒 Authentication Required
Request Body
{
"host_ids": ["uuid1", "uuid2", "uuid3"],
"include_storage": true,
"include_network": true,
"include_users": false
}Response (200 OK)
{
"batch_id": "uuid",
"total_hosts": 3,
"requests_sent": 3,
"estimated_completion": "2024-01-01T12:05:00Z"
}Important Notes
- All endpoints require valid JWT authentication
- Host operations may take time to complete - use execution IDs to track progress
- Bulk operations are rate-limited to prevent system overload
- Hardware information updates are cached and updated periodically
- Some operations require administrative privileges