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"
}

GET /api/host/{host_id}/reboot/pre-check

Pre-check before rebooting a parent host. Returns running child host information so the user can make an informed decision.

🔒 Authentication Required

Path Parameters

host_id (string) - UUID of the parent host

Response (200 OK)

{
  "has_running_children": true,
  "running_children": [
    {
      "id": "uuid",
      "child_name": "web-container-01",
      "child_type": "lxd",
      "status": "running"
    }
  ],
  "running_count": 1,
  "total_children": 3,
  "has_container_engine": true
}

POST /api/host/{host_id}/reboot/orchestrated ⭐ PRO+

Initiate an orchestrated reboot sequence. Stops all running child hosts, reboots the parent, and automatically restarts children after agent reconnection. Requires Professional+ license.

🔒 Authentication Required

Path Parameters

host_id (string) - UUID of the parent host

Response (200 OK)

{
  "orchestration_id": "uuid",
  "status": "shutting_down",
  "child_count": 2
}

Error Responses

402 Payment Required - Professional+ license required
400 Bad Request - Host is not active, or no running child hosts found

GET /api/host/{host_id}/reboot/orchestration/{orchestration_id}

Get the current status of a reboot orchestration, including per-child restart status and timestamps for each phase.

🔒 Authentication Required

Path Parameters

host_id (string) - UUID of the parent host
orchestration_id (string) - UUID of the orchestration record

Response (200 OK)

{
  "orchestration_id": "uuid",
  "parent_host_id": "uuid",
  "status": "completed",
  "child_hosts_snapshot": [
    {
      "id": "uuid",
      "child_name": "web-container-01",
      "child_type": "lxd",
      "pre_reboot_status": "running"
    }
  ],
  "child_hosts_restart_status": [
    {
      "id": "uuid",
      "child_name": "web-container-01",
      "restart_status": "running",
      "error": null
    }
  ],
  "shutdown_timeout_seconds": 120,
  "initiated_by": "admin",
  "initiated_at": "2025-01-15T10:30:00",
  "shutdown_completed_at": "2025-01-15T10:31:15",
  "reboot_issued_at": "2025-01-15T10:31:15",
  "agent_reconnected_at": "2025-01-15T10:33:45",
  "restart_completed_at": "2025-01-15T10:34:20",
  "error_message": null
}

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

Host Management API

Overview

Fleet Management

Response (200 OK)

Response (200 OK)

Path Parameters

Response (200 OK)

Host Operations

Path Parameters

Request Body

Response (200 OK)

Path Parameters

Request Body

Response (200 OK)

Path Parameters

Request Body

Response (200 OK)

Path Parameters

Response (200 OK)

Path Parameters

Response (200 OK)

Error Responses

Path Parameters

Response (200 OK)

Hardware and System Information

Path Parameters

Response (200 OK)

Response (200 OK)

Response (200 OK)

Response (200 OK)

Response (200 OK)

Software and Package Information

Path Parameters

Response (200 OK)

Response (200 OK)

Bulk Operations

Request Body

Response (200 OK)

Request Body

Response (200 OK)

Important Notes

Quick Navigation