Agents API

Agent administration endpoints require infrastructure-management permission.

Method & path	Purpose
`GET /api/deployments/agent-installer`	Read the authoritative Linux and Windows installer locations for this deployment.
`GET /api/agents`	List deployed hosts as paged deployment-status rows, including operational state, active packs, and series-count/drop accounting.
`GET /api/agents/{id}`	Read one host detail view with agent identity, latest host CPU/memory, and per-process CPU/memory/RSS samples.
`GET /api/agents/{id}/telemetry`	Read host-scoped CPU, memory, disk, and network history charts for a time range.
`GET /api/agents/{id}/processes/{executable}/telemetry`	Read lazy-loaded CPU, memory, and RSS history charts for one executable.
`GET /api/agents/{id}/process-inventory`	List deterministic executable inventory with last-seen and stale timestamps.
`PUT /api/agents/{id}`	Enable/disable an agent and assign its topology cluster and tags.
`GET /api/processes`	List service identities discovered across the agent fleet.
`PUT /api/processes/{identity}/monitor`	Enable or disable topology monitoring for one tenant-wide service identity.
`GET /api/agents/rule-packs`	List the built-in rule packs with enable state, interval override, and the process always-collect list.
`PUT /api/agents/rule-packs/{packId}`	Enable/disable a pack, override its collection interval, or set the process always-collect list.
`GET /api/agents/enrollment-profiles`	List bounded enrollment profiles.
`POST /api/agents/enrollment-profiles`	Create an enrollment profile and receive its token once.
`GET`, `POST /api/agents/host-clusters`	List or create topology clusters available for agent placement.
`GET`, `POST /api/agents/tags`	List or create tags.

Create an enrollment profile

{
  "name": "Production Linux hosts",
  "maxEnrollments": 100,
  "expiresInHours": 24,
  "requiredCollectorId": null
}

The response includes an enrollment token that is shown once. The profile stops accepting new agents when it expires or reaches its enrollment limit. The Deployment Status page combines this token with the current Lumetry endpoint in copyable Linux x64/arm64 and Windows x64 install commands. Isolated deployments return their own internal installer and package location; clients must not construct a public download URL.

Update an agent

{
  "enabled": false,
  "hostClusterNodeId": 12,
  "tagIds": [3, 8]
}

enabled=false stops collection and metric delivery. The agent continues its control heartbeat so a later update can enable it again. hostClusterNodeId assigns the agent's host to a topology Cluster, which also provides the host-group label used for fleet scopes.

List hosts

GET /api/agents returns a paged response:

{
  "items": [],
  "page": 1,
  "pageSize": 20,
  "totalCount": 0,
  "totalPages": 0,
  "hasPreviousPage": false,
  "hasNextPage": false
}

Supported query parameters are page, pageSize, q (hostname search), status, hostClusterNodeId, and tagId.

Discovered services and automatic topology

GET /api/processes?q=&monitored=&page=&pageSize= returns the paged registry of service identities discovered across the fleet. Each row includes identity, hostCount, monitored, firstSeen, and lastSeen. Discovery is an allowlist: a new identity is visible in this registry but is not drawn on the topology map until an operator enables it.

{
  "monitored": true
}

PUT /api/processes/{identity}/monitor applies this flag tenant-wide. Enabling an identity creates or reuses one Component and places it on every Host currently reporting that service. Stable outbound connections create dependency edges. Disabling it removes the agent-generated Component and its agent-generated topology relationships; process metrics remain available.

Service identity is based first on the owning systemd unit or Windows Service. Unmanaged generic runtimes use command-line application signals, and the executable name is the fallback. This keeps different managed services that share one binary separate while merging the same farm service across hosts.

Host detail

GET /api/agents/{id} returns the selected host's deployment identity plus recent host CPU, memory used, memory available, and process resource usage. Live metric values are returned only when a recent sample exists; otherwise they are null. Process rows come from the durable executable inventory, so a stopped process can remain visible with null usage until it is marked stale. A process row's lastSeenAt is the newest recent process metric sample timestamp, including the process running-count signal; the process-inventory endpoint exposes inventory liveness timestamps.

GET /api/agents/{id}/telemetry?from=...&to=... returns chart-ready host history for CPU, memory used, memory available, disk usage by mount, disk throughput by device, and network throughput by interface. Linux host telemetry suppresses synthetic disk devices and container or tunnel-only network interfaces. Network throughput is derived from receive/transmit byte counters and returned as bytes per second.

GET /api/agents/{id}/processes/{executable}/telemetry?from=...&to=... returns chart-ready CPU percent, memory percent, and RSS byte history for one executable. The Deployment Status host detail page uses this endpoint only after a process row is expanded.

Update a rule pack

{
  "enabled": true,
  "intervalOverrideSeconds": 120,
  "processInclude": ["nginx", "postgres"]
}

processInclude applies to the process pack: the listed executables are always collected and keep reporting a presence metric even while stopped, which powers the process-down default alert. Omit the field (or send null) to leave the list unchanged.

Agent process endpoints

POST /v1/agents/enroll
POST /v1/agents/heartbeat
POST /v1/metrics

POST /v1/agents/enroll accepts optional, mutually exclusive hostClusterName and hostClusterExternalId fields. The name matches one existing topology Cluster case-insensitively; the external ID matches exactly. Enrollment succeeds with no Cluster assignment when the hint is missing, invalid, non-Cluster, or ambiguous. It never creates a Cluster from the supplied value.

Agent processes use a dedicated machine credential. When traffic is relayed, Lumetry validates both the agent identity and the collector identity.

Heartbeats include locally active rule-pack IDs, series-limit accounting, and change-only inventories:

processInventory: selected executable names;
applicationInventory: Windows records shaped as { "kind": "iis-site" | "iis-app-pool", "name": "..." };
componentInventory: candidate service identities used by the Processes registry;
connectionInventory: stable outbound dependencies shaped as { "source": "...", "remoteIp": "...", "remotePort": 5432 };
localAddresses: non-loopback addresses used to resolve remote endpoints to Hosts.

Lumetry uses these inventories to maintain deterministic host/process/application identities. IIS applications also create application-to-host topology dependencies. A private remote address with no agent is represented temporarily as an endpoint Host. If one agent later claims that address uniquely, Lumetry moves agent-generated dependencies to the real reconciled Host and removes the temporary endpoint when nothing else references it. Ambiguous claims are left unchanged. GET /api/agents exposes active pack IDs in paged host-list rows; the process inventory endpoint exposes executable names without process IDs.

Create an enrollment profile​

Update an agent​

List hosts​

Discovered services and automatic topology​

Host detail​

Update a rule pack​

Agent process endpoints​