Skip to main content
The Agent Management endpoints handle the full lifecycle of Guard agents: registration, heartbeat monitoring, querying, and deregistration.

​
POST /api/agents/register

Registers a new agent with the Manager. Typically called automatically when panguard guard start runs.
​
hostname
string
required
The machine hostname.
​
os
string
required
Operating system identifier (e.g., linux, darwin, win32).
​
version
string
required
Panguard Guard version running on the agent.
​
ip
string
The agent’s IP address. Auto-detected from the request if not provided.
​
org_id
string
Organization ID for multi-tenant deployments.
​
tags
string[]
Optional tags for grouping and filtering (e.g., ["production", "web-tier"]).
curl -X POST https://localhost:8443/api/agents/register \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "web-server-1",
    "os": "linux",
    "version": "1.2.0",
    "tags": ["production", "web-tier"]
  }'

{
  "ok": true,
  "data": {
    "id": "agent-a1b2c3d4",
    "hostname": "web-server-1",
    "os": "linux",
    "version": "1.2.0",
    "ip": "203.0.113.10",
    "tags": ["production", "web-tier"],
    "status": "online",
    "registeredAt": "2026-03-07T12:00:00.000Z"
  }
}

​
POST /api/agents/:id/heartbeat

Sends a heartbeat to confirm the agent is alive. Agents that miss heartbeats beyond the configured timeout are marked as stale.
​
id
string
required
The agent ID returned from registration.
​
uptime
number
Agent uptime in seconds.
​
cpu
number
Current CPU usage percentage (0—100).
​
memory
number
Current memory usage percentage (0—100).
​
version
string
Current Panguard Guard version (for tracking upgrades).
curl -X POST https://localhost:8443/api/agents/agent-a1b2c3d4/heartbeat \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "uptime": 86400,
    "cpu": 12.5,
    "memory": 45.2,
    "version": "1.2.0"
  }'

{
  "ok": true,
  "data": {
    "id": "agent-a1b2c3d4",
    "status": "online",
    "lastHeartbeat": "2026-03-07T12:05:00.000Z",
    "pendingPolicies": 1
  }
}
The response includes a pendingPolicies count, allowing the agent to know when to fetch new policy rules. The heartbeat interval defaults to 60 seconds and is configurable via MANAGER_HEARTBEAT_TIMEOUT_MS.

​
DELETE /api/agents/:id

Deregisters an agent and removes it from the fleet. Historical threat data is retained.
​
id
string
required
The agent ID to deregister.
curl -X DELETE https://localhost:8443/api/agents/agent-a1b2c3d4 \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "ok": true,
  "data": {
    "message": "Agent agent-a1b2c3d4 deregistered successfully"
  }
}

​
GET /api/agents

Lists all registered agents with their current status.
​
status
string
Filter by status: online, stale, or offline.
​
org_id
string
Filter by organization ID.
​
tag
string
Filter by tag. Can be specified multiple times.
curl -X GET "https://localhost:8443/api/agents?status=online" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "ok": true,
  "data": [
    {
      "id": "agent-a1b2c3d4",
      "hostname": "web-server-1",
      "os": "linux",
      "version": "1.2.0",
      "ip": "203.0.113.10",
      "status": "online",
      "tags": ["production", "web-tier"],
      "lastHeartbeat": "2026-03-07T12:05:00.000Z",
      "registeredAt": "2026-03-01T08:00:00.000Z"
    },
    {
      "id": "agent-e5f6g7h8",
      "hostname": "db-server-1",
      "os": "linux",
      "version": "1.2.0",
      "ip": "203.0.113.11",
      "status": "online",
      "tags": ["production", "database"],
      "lastHeartbeat": "2026-03-07T12:04:30.000Z",
      "registeredAt": "2026-03-01T08:05:00.000Z"
    }
  ]
}

​
GET /api/agents/:id

Returns detailed information about a specific agent.
​
id
string
required
The agent ID.
curl -X GET https://localhost:8443/api/agents/agent-a1b2c3d4 \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "ok": true,
  "data": {
    "id": "agent-a1b2c3d4",
    "hostname": "web-server-1",
    "os": "linux",
    "version": "1.2.0",
    "ip": "203.0.113.10",
    "status": "online",
    "tags": ["production", "web-tier"],
    "cpu": 12.5,
    "memory": 45.2,
    "uptime": 86400,
    "lastHeartbeat": "2026-03-07T12:05:00.000Z",
    "registeredAt": "2026-03-01T08:00:00.000Z",
    "recentThreats": 3,
    "activePolicyVersion": "v2"
  }
}