Agent API
infrality-agent uses three HTTP routes and the live channel. All take an organization’s API key in x-api-key.
POST /api/agents/register
Section titled “POST /api/agents/register”Called on every start. An upsert keyed by hostname within the organization.
| Field | Type | Notes |
|---|---|---|
name |
string | Display name |
hostname |
string | The machine’s hostname — the agent’s identity in the organization |
ipAddress |
string? | The machine’s address |
os |
string? | linux, darwin, windows |
version |
string? | Agent version |
projectId |
string? | The board it asks to draw on |
reportedConfig |
object? | Its effective settings: scanCidr, scanMask, scanInterface, scanIntervalSeconds, scanTimeoutSeconds, workerCount, topologyName, topologyOutput |
reportedInterfaces |
object[]? | Its IPv4 networks: name, mac, ipAddress, network, mask, gateway, primary, hosts |
The answer carries the agent’s id, the settings chosen for it on the dashboard (null where none were), and warnings — refusals in plain words, such as a board it may not draw on.
The first registration of a new hostname counts against the organization’s agents. A single-agent key registers only the agent that first claimed it (403 otherwise).
POST /api/agents/heartbeat
Section titled “POST /api/agents/heartbeat”{ "agentId": "…" }. Stamps the agent as seen. The live channel’s heartbeat does the same; this is the fallback for an agent that cannot hold a WebSocket.
POST /api/agents/ingest
Section titled “POST /api/agents/ingest”Files a sweep’s results over HTTP — what the agent does when its live connection dropped.
| Field | Type | Notes |
|---|---|---|
agentId |
string | A registered agent of the key’s organization |
projectId |
string | The board |
scanType |
string | icmp, tcp, dns, arp or enumerate |
scanRunId |
string? | Reconcile into this run instead of filing a new one |
results |
object[] | Up to 5000: { type, target, alive, data } |
Results of type enumerate are merged into the board as devices; data follows the device shape described in what the agent discovers. Everything an agent sends is bounded and re-checked on the server: unknown fields are dropped, lengths capped, wrong types discarded.
A trashed board records the sweep without drawing it, and the answer’s warnings says so.
The live channel
Section titled “The live channel”wss://api.infrality.io/api/ws. The first message authenticates — { "type": "auth", "role": "agent", … } with the API key and the agent id — within ten seconds, or the socket is closed. The agent then streams scan:started, scan:progress, scan:devices and scan:completed, heartbeats every 20 seconds, and receives command (scan, stop) and agent:config frames. Frames are limited to 64 KB, 400 per ten seconds.
Close codes: 4001 bad credentials (do not retry with them), 4003 forbidden, 4008 nothing said in time, 4029 too many frames, 4400 malformed frame, 1001 server restarting (reconnect).