Agent API Reference

This document describes the API endpoints used by Infracast Agents to communicate with the server.

Authentication

Agents authenticate using JWT tokens:

• Enrollment token: Used once during registration, generated from UI
• Agent token: Returned after registration, used for all subsequent requests

Include the agent token in all requests:

Authorization: Bearer <agent_token>

---

Agent Endpoints (Agent → Server)

Register Agent

POST /api/v1/agents/register

Registers a new agent with the server using an enrollment token.

Request:

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

Response:

{
  "agent_id": "agt_7f3d2a1b",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "server_time": "2026-03-30T22:00:00Z",
  "scan_interval_seconds": 300,
  "heartbeat_interval_seconds": 30
}

---

Heartbeat

POST /api/v1/agents/{agentID}/heartbeat

Periodic heartbeat to indicate agent is alive and report basic metrics.

Request:

{
  "uptime_seconds": 86400,
  "cpu_percent": 12.5,
  "memory_percent": 45.2,
  "agent_version": "1.0.0"
}

Response:

{
  "ack": true,
  "server_time": "2026-03-30T22:00:30Z"
}

---

Submit Report

POST /api/v1/agents/{agentID}/report

Submits a full discovery report from the agent.

Request:

{
  "collected_at": "2026-03-30T22:00:00Z",
  "processes": [
    {
      "pid": 1234,
      "name": "nginx",
      "user": "www-data",
      "command": "nginx: master process /usr/sbin/nginx",
      "cpu_percent": 0.5,
      "memory_mb": 128
    }
  ],
  "ports": [
    {
      "port": 443,
      "protocol": "tcp",
      "state": "listen",
      "process": "nginx",
      "pid": 1234,
      "address": "0.0.0.0"
    }
  ],
  "software": [
    {
      "name": "nginx",
      "version": "1.24.0",
      "source": "apt",
      "installed_at": "2026-01-15T10:00:00Z"
    },
    {
      "name": "openssl",
      "version": "3.0.2",
      "source": "apt"
    }
  ],
  "firewall_rules": [
    {
      "chain": "INPUT",
      "action": "ACCEPT",
      "protocol": "tcp",
      "port": "443",
      "source": "0.0.0.0/0"
    }
  ],
  "connections": [
    {
      "local_addr": "10.0.1.5:443",
      "remote_addr": "203.0.113.50:52341",
      "state": "ESTABLISHED",
      "protocol": "tcp",
      "pid": 1234,
      "process": "nginx"
    }
  ]
}

Response:

{
  "accepted": true,
  "findings_created": 2,
  "next_scan_at": "2026-03-30T22:05:00Z"
}

---

Poll Commands

GET /api/v1/agents/{agentID}/commands

Polls for pending commands from the server. Commands are consumed (deleted) when retrieved.

Response:

{
  "commands": [
    {
      "id": "cmd_abc123",
      "type": "scan",
      "issued_at": "2026-03-30T22:00:00Z"
    }
  ]
}

Command Types:

Type	Description
scan	Trigger immediate full discovery scan
update_config	Update agent configuration
shutdown	Gracefully stop the agent

---

Operator Endpoints (UI/API → Server)

List Agents

GET /api/v1/tenants/{tenantID}/agents

Returns all agents for a tenant.

Response:

{
  "agents": [
    {
      "id": "agt_7f3d2a1b",
      "hostname": "web-server-01",
      "os": "linux",
      "os_version": "Ubuntu 22.04",
      "agent_version": "1.0.0",
      "status": "online",
      "last_seen": "2026-03-30T22:00:30Z",
      "last_report": "2026-03-30T22:00:00Z",
      "created_at": "2026-03-01T10:00:00Z"
    }
  ]
}

Status Values:

Status	Condition
online	Last seen < 90 seconds ago
stale	Last seen < 10 minutes ago
offline	Last seen > 10 minutes ago

---

Get Agent

GET /api/v1/tenants/{tenantID}/agents/{agentID}

Returns details for a specific agent including last report summary.

---

Generate Enrollment Token

POST /api/v1/tenants/{tenantID}/agents/token

Generates an enrollment token for registering new agents in this tenant. The token is a JWT valid for 24 hours; the lifetime is fixed and not configurable per request.

Request: no body required.

Optionally set X-Server-URL to control the server address embedded in the returned install commands. It defaults to https://api.infracast.io.

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2026-03-31T22:00:00Z",
  "install_linux": "curl -fsSL https://api.infracast.io/agent/install.sh | INFRACAST_TOKEN=<token> bash",
  "install_windows": "Invoke-WebRequest -Uri 'https://api.infracast.io/agent/install.ps1' -OutFile install.ps1; $env:INFRACAST_TOKEN='<token>'; .\\install.ps1",
  "install_macos": "curl -fsSL https://api.infracast.io/agent/install.sh | INFRACAST_TOKEN=<token> bash"
}

The three install_* fields are ready-to-paste commands for the corresponding platform, which is what the UI shows after you click Generate Token.

---

Revoke an Agent

DELETE /api/v1/tenants/{tenantID}/agents/{agentID}

Revokes the agent, preventing further communication. Requires the tenant:update permission.

---

Force Re-Scan

POST /api/v1/tenants/{tenantID}/agents/{agentID}/scan

Queues a scan command for the agent. Agent will execute on next command poll.

Response:

{
  "command_id": "cmd_xyz789",
  "queued": true
}

---

Get Last Report

GET /api/v1/tenants/{tenantID}/agents/{agentID}/report

Returns the most recent discovery report from an agent.

---

Error Responses

All endpoints return standard error format:

{
  "error": "invalid_token",
  "message": "Agent token has been revoked",
  "code": 401
}

Code	Error	Description
400	bad_request	Invalid request format
401	unauthorized	Missing or invalid token
403	forbidden	Token revoked or tenant mismatch
404	not_found	Agent not found
429	rate_limited	Too many requests
500	internal_error	Server error