Agents API

Endpoints for managing agents (monitored endpoints).

List Agents

Get a paginated list of all agents.

GET /api/v1/agents/
Authorization: Bearer YOUR_TOKEN

Query Parameters

Parameter	Type	Default	Description
page	int	1	Page number
per_page	int	50	Items per page (max 100)
status	string	-	Filter: online, offline, pending
search	string	-	Search hostname, IP, UUID
sort_by	string	hostname	Sort field
sort_order	string	asc	asc or desc
folder_id	uuid	-	Filter by folder
tag_ids	string	-	Comma-separated tag UUIDs

Response

{
  "items": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "hostname": "web-server-01",
      "ip_address": "192.168.1.100",
      "os": "linux",
      "os_version": "Ubuntu 22.04",
      "arch": "amd64",
      "status": "online",
      "agent_version": "1.0.0",
      "last_seen": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-01T00:00:00Z",
      "folder_id": null,
      "tags": [
        {"id": "...", "name": "Production", "color": "#22c55e"}
      ],
      "maintenance_mode": false
    }
  ],
  "total": 150,
  "page": 1,
  "per_page": 50,
  "pages": 3
}

Get Agent Details

Get detailed information about a specific agent.

GET /api/v1/agents/{uuid}
Authorization: Bearer YOUR_TOKEN

Response

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "hostname": "web-server-01",
  "ip_address": "192.168.1.100",
  "os": "linux",
  "os_version": "Ubuntu 22.04.3 LTS",
  "arch": "amd64",
  "status": "online",
  "agent_version": "1.0.0",
  "last_seen": "2024-01-15T10:30:00Z",
  "created_at": "2024-01-01T00:00:00Z",
  "approved_at": "2024-01-01T00:01:00Z",
  "approved_by": "admin",
  "folder_id": null,
  "tags": [],
  "maintenance_mode": false,
  "system_info": {
    "cpu": {
      "model": "Intel Core i7-10700",
      "cores": 8,
      "threads": 16,
      "usage": 25.5
    },
    "memory": {
      "total": 16384,
      "used": 8192,
      "percent": 50.0
    },
    "disk": [
      {
        "mount": "/",
        "total": 500000,
        "used": 250000,
        "percent": 50.0
      }
    ],
    "network": [
      {
        "interface": "eth0",
        "ip": "192.168.1.100",
        "mac": "00:11:22:33:44:55"
      }
    ]
  }
}

Register Agent

Register a new agent. Usually called by the agent itself.

POST /api/v1/agents/register
Content-Type: application/json

{
  "hostname": "web-server-01",
  "os": "linux",
  "os_version": "Ubuntu 22.04",
  "arch": "amd64",
  "agent_version": "1.0.0",
  "ip_address": "192.168.1.100",
  "enrollment_token": "optional_token"
}

Response (Approved)

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "approved",
  "certificate": "-----BEGIN CERTIFICATE-----...",
  "private_key": "-----BEGIN PRIVATE KEY-----...",
  "ca_certificate": "-----BEGIN CERTIFICATE-----...",
  "reregistration_secret": "secret"
}

Response (Pending)

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "Agent registration pending approval"
}

Approve Agent

Approve a pending agent registration.

POST /api/v1/agents/{uuid}/approve
Authorization: Bearer YOUR_TOKEN

Response

{
  "message": "Agent approved",
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Reject Agent

Reject a pending agent registration.

POST /api/v1/agents/{uuid}/reject
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "reason": "Unknown device"
}

Execute Action

Execute an action on an agent.

POST /api/v1/agents/{uuid}/action
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "action": "restart"
}

Available Actions

Action	Description
restart	Restart the agent
shutdown	Shutdown the system
reboot	Reboot the system
update	Update the agent
scan	Trigger inventory scan

Response

{
  "message": "Action queued",
  "action": "restart",
  "agent_uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Update Agent

Update agent metadata.

PUT /api/v1/agents/{uuid}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "folder_id": "folder-uuid",
  "tag_ids": ["tag-uuid-1", "tag-uuid-2"],
  "notes": "Primary web server"
}

Toggle Maintenance Mode

Enable or disable maintenance mode.

POST /api/v1/agents/{uuid}/maintenance
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "enabled": true,
  "reason": "Scheduled maintenance",
  "expires_at": "2024-01-15T18:00:00Z"
}

When in maintenance mode:

• Monitoring alerts are suppressed
• Patch policies are not executed
• Scripts are blocked

Delete Agent

Remove an agent from the system.

DELETE /api/v1/agents/{uuid}
Authorization: Bearer YOUR_TOKEN

Response

{
  "message": "Agent deleted",
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Get Agent Software

List software installed on an agent.

GET /api/v1/agents/{uuid}/software
Authorization: Bearer YOUR_TOKEN

Response

{
  "items": [
    {
      "name": "nginx",
      "version": "1.24.0",
      "vendor": "Nginx Inc.",
      "install_date": "2024-01-01",
      "vulnerabilities": []
    },
    {
      "name": "openssl",
      "version": "3.0.2",
      "vendor": "OpenSSL",
      "install_date": "2024-01-01",
      "vulnerabilities": [
        {
          "cve_id": "CVE-2024-0001",
          "severity": "high",
          "cvss_score": 7.5
        }
      ]
    }
  ],
  "total": 150,
  "vulnerable_count": 5
}

Get Agent Services

List services on an agent.

GET /api/v1/agents/{uuid}/services
Authorization: Bearer YOUR_TOKEN

Response

{
  "items": [
    {
      "name": "nginx",
      "display_name": "nginx - high performance web server",
      "status": "running",
      "start_type": "automatic"
    },
    {
      "name": "postgresql",
      "display_name": "PostgreSQL Database",
      "status": "running",
      "start_type": "automatic"
    }
  ]
}

Control Service

Start, stop, or restart a service.

POST /api/v1/agents/{uuid}/services/{service_name}/action
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "action": "restart"
}

Available Actions

• start
• stop
• restart

Get Agent Metrics

Get historical metrics for an agent.

GET /api/v1/agents/{uuid}/metrics
Authorization: Bearer YOUR_TOKEN

Query Parameters

Parameter	Type	Default	Description
metric	string	-	cpu, memory, disk, network
from	datetime	24h ago	Start time
to	datetime	now	End time
interval	string	5m	Aggregation interval

Response

{
  "metric": "cpu",
  "data": [
    {"timestamp": "2024-01-15T10:00:00Z", "value": 25.5},
    {"timestamp": "2024-01-15T10:05:00Z", "value": 30.2},
    {"timestamp": "2024-01-15T10:10:00Z", "value": 22.1}
  ]
}