ProvCollector.FleetServer — API v1

FleetServer API Reference

Complete technical reference for the ProvCollector.FleetServer backend service. Covers the Operator REST API (/api/v1/fleet), CI & Update distribution endpoints (/api/v1/updates), Server-Sent Events (SSE) streaming, the real-time SignalR Hub for Updaters (/api/v1/agent/connection), and shared data contracts.

🔒 Authentication & Security

ProvCollector.FleetServer secures agent connections using constant-time SHA-256 API key validation.

🛡️

Agent Hub Security Model:
Connecting agents present their plain-text API key via the X-Api-Key HTTP request header during the SignalR connection handshake. The server hashes the presented key using SHA-256 and validates it against the configured FleetServer:AgentApiKeyHashes array using constant-time comparison (CryptographicOperations.FixedTimeEquals). If no key matches or if the hash list is empty, the connection is immediately aborted.

AUTH Header: X-Api-Key

Required on all agent connections at /api/v1/agent/connection.

Backend Configuration (YAML / Docker Env)

# FleetServer accepted key hashes (lowercase-hex SHA-256)
FleetServer:
  AgentApiKeyHashes:
    - "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"

⚡ Fleet API — Agents & Telemetry

Operator endpoints mounted under /api/v1/fleet/agents for querying, naming, tagging, and managing registered agents.

GET /api/v1/fleet/agents

Retrieves all registered agents with active connection status, projected tags, uptime, and aggregated telemetry.

Response

200 OK — Array of AgentNode objects.

JSON Response

[
  {
    "id": "c4a1b2c3-d4e5-6789-abcd-ef0123456789",
    "hostname": "PROV-WORKER-01",
    "displayName": "Primary Ingestion Node",
    "ipAddress": "192.168.1.105",
    "osType": "Windows",
    "osVersion": "Microsoft Windows 11 Pro 10.0.26100",
    "status": "Online",
    "lastHeartbeat": "2026-08-24T16:45:00Z",
    "discoveredAt": "2026-08-10T09:12:00Z",
    "machineGuid": "a8f34b12-9c01-44de-9e23-289410ef9231",
    "uptimeSeconds": 86420.5,
    "cpuUsagePercent": 4.2,
    "memoryUsageMb": 142.8,
    "eventsPerSecond": 1240.0,
    "tags": ["Windows", "Production", "Core"],
    "pendingUpdateVersion": null,
    "applications": [
      {
        "name": "Agent",
        "status": "Running",
        "version": "v1.4.2",
        "cpuUsagePercent": 3.1,
        "memoryUsageMb": 98.4
      },
      {
        "name": "Updater",
        "status": "Running",
        "version": "v1.4.2",
        "cpuUsagePercent": 1.1,
        "memoryUsageMb": 44.4
      }
    ]
  }
]

GET /api/v1/fleet/agents/{guid}

Retrieves full agent node details by Agent ID, Machine GUID, or Hostname.

Path Parameters

Parameter	Type	Requirement	Description
guid	string	Required	Agent ID, Machine GUID, or Hostname identifier.

Response

200 OK — AgentNode object.

404 Not Found — RFC 9457 problem details (agent_not_found).

PATCH /api/v1/fleet/agents/{guid}

Updates an agent's custom friendly display name.

Request Body (PatchAgentRequest)

{
  "displayName": "Edge Node Alpha"
}

Response

200 OK — Updated AgentNode.

400 Bad Request — No writable fields supplied (no_writable_fields).

404 Not Found — RFC 9457 problem details (agent_not_found).

PUT /api/v1/fleet/agents/{guid}/tags

Replaces the agent's assigned tag list. Note: The derived OS tag (e.g. Windows) is automatically managed.

Request Body (PutTagsRequest)

{
  "tags": ["Production", "East-Coast", "High-Priority"]
}

Response

200 OK — Array of updated strings.

404 Not Found — RFC 9457 problem details (agent_not_found).

DELETE /api/v1/fleet/agents/{guid}?force=false

Removes an agent from the fleet registry and forgets associated log stores. Deletion is idempotent: if the agent is already absent, 204 is returned. If the agent is currently connected, returns 409 Conflict unless ?force=true is supplied.

Response

204 No Content — Agent deleted (or already absent).

409 Conflict — Agent is currently connected (agent_connected).

GET /api/v1/fleet/agents/{guid}/applications

Retrieves the managed application list (e.g. Agent, Updater) reported by the agent's heartbeat, including installed versions, service statuses, and process resource utilization.

Path Parameters

Parameter	Type	Requirement	Description
guid	string	Required	Agent ID, Machine GUID, or Hostname identifier.

Response

200 OK — Array of ManagedApplicationStatus objects.

404 Not Found — RFC 9457 problem details (agent_not_found).

JSON Response

[
  {
    "name": "Agent",
    "status": "Running",
    "version": "v1.4.2",
    "cpuUsagePercent": 3.1,
    "memoryUsageMb": 98.4
  },
  {
    "name": "Updater",
    "status": "Running",
    "version": "v1.4.2",
    "cpuUsagePercent": 1.1,
    "memoryUsageMb": 44.4
  }
]

GET /api/v1/fleet/agents/{guid}/telemetry

Retrieves a concise telemetry snapshot for the detail header, including CPU%, Memory MB, EPS, and staleness indicator.

Response

200 OK — AgentTelemetryDto object.

404 Not Found — RFC 9457 problem details (agent_not_found).

{
  "cpuUsagePercent": 3.5,
  "memoryUsageMb": 128.4,
  "eventsPerSecond": 850.0,
  "stale": false,
  "retrievedAt": "2026-08-24T16:50:00Z"
}

⚙️ Fleet API — Remote Configuration

Live configuration inspection, single-agent updates, and fleet-wide configuration synchronization pushed to remote agents over SignalR.

GET /api/v1/fleet/agents/{guid}/config

Fetches live configuration files from the agent via SignalR. If the agent is offline or fails to respond, returns 200 OK with cached configuration and "stale": true.

Response

200 OK — AgentConfigResponse object.

{
  "files": {
    "Agent": {
      "EventStream": { "BufferSize": 10000 },
      "Logging": { "LogLevel": "Information" }
    }
  },
  "stale": false,
  "retrievedAt": "2026-08-24T16:52:00Z"
}

PUT /api/v1/fleet/agents/{guid}/config

Pushes a new configuration tree to the remote agent over SignalR, writes it to disk, and restarts the affected services. Returns PushConfigResult reporting separate write and restart verification flags.

Path Parameters

Parameter	Type	Requirement	Description
guid	string	Required	Agent ID, Machine GUID, or Hostname identifier.

Request Body (JSON Document)

{
  "Agent": {
    "EventStream": { "BufferSize": 10000 },
    "Logging": { "LogLevel": "Information" }
  }
}

Response

200 OK — PushConfigResult object. Returns diagnostics even if the agent is disconnected (written: false, restarted: false, message: "Agent is not connected...").

400 Bad Request — Configuration document is empty (invalid_config).

404 Not Found — RFC 9457 problem details (agent_not_found).

Successful Push

{
  "written": true,
  "restarted": true,
  "message": "Updated remote agent configuration and restarted service."
}

Agent Disconnected (200 OK Diagnostics)

{
  "written": false,
  "restarted": false,
  "message": "Agent is not connected. Nothing was changed."
}

PUT /api/v1/fleet/agents/config

Synchronizes configuration fleet-wide by pushing the specified configuration tree to all registered agents over SignalR, writing it to disk, and restarting affected services. Returns an array of PushConfigResult diagnostics reporting per-agent write and restart verification outcomes.

Request Body (JSON Document)

{
  "Agent": {
    "EventStream": { "BufferSize": 10000 },
    "Logging": { "LogLevel": "Information" }
  }
}

Response

200 OK — Array of PushConfigResult objects (one per registered agent in the fleet). Disconnected agents return diagnostic entries with written: false, restarted: false.

400 Bad Request — Configuration document is empty (invalid_config).

Fleet Sync Response (200 OK)

[
  {
    "written": true,
    "restarted": true,
    "message": "Updated remote agent configuration and restarted service."
  },
  {
    "written": false,
    "restarted": false,
    "message": "Agent is not connected. Nothing was changed."
  }
]

Empty Configuration (400 Bad Request)

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "problem_code": "invalid_config",
  "detail": "The configuration document is empty."
}

📡 Fleet API — Commands, Logs & SSE

Asynchronous remote command dispatch, history paging, and real-time Server-Sent Events (SSE) log streaming.

POST /api/v1/fleet/agents/{guid}/commands

Dispatches an asynchronous remote command to an agent. Supported command types: Ping, FlushTelemetry, RestartService, TriggerUpdateCheck, GetConfig, PushConfig. Returns 202 Accepted with a Location header referencing the command log resource.

Path Parameters

Parameter	Type	Requirement	Description
guid	string	Required	Target Agent ID or identifier.

Request Body (CreateCommandRequest)

{
  "type": "TriggerUpdateCheck",
  "parameters": "Agent:v1.5.0-setup.msi"
}

Response

202 Accepted — CommandAccepted object with Location header set to /api/v1/fleet/agents/{guid}/commands/{id}.

400 Bad Request — Unrecognized command type (unknown_command_type).

404 Not Found — Agent is not registered (agent_not_found).

503 Service Unavailable — Agent is not currently connected (agent_offline).

{
  "id": "a1b2c3d4",
  "sequence": 1042,
  "status": "Pending"
}

GET /api/v1/fleet/agents/{guid}/commands/{id}

Polls the status and outcome message of a previously dispatched command for a specific agent.

Path Parameters

Parameter	Type	Requirement	Description
guid	string	Required	Agent ID or identifier.
id	string	Required	8-character command ID.

Response

200 OK — RemoteCommandLog object.

404 Not Found — Command or agent was not found (command_not_found).

JSON Response

{
  "id": "a1b2c3d4",
  "sequence": 1042,
  "agentId": "c4a1b2c3-d4e5-6789-abcd-ef0123456789",
  "agentHostname": "PROV-WORKER-01",
  "commandType": "TriggerUpdateCheck",
  "timestamp": "2026-08-24T16:52:00Z",
  "executedBy": "DashboardOperator",
  "status": "Success",
  "outputMessage": "Update check completed. Installed v1.5.0."
}

GET /api/v1/fleet/agents/{guid}/commands?since={seq}&limit={n}

Retrieves a paged history of remote command records for a specific agent. lastSequence can be passed to the SSE stream or subsequent requests to resume from that point.

Query Parameters

Parameter	Type	Requirement	Description
since	long	Optional	Return commands with `sequence > since` (default 0).
limit	int	Optional	Maximum entries to return (default 200, max 2000).

Response

200 OK — LogPage<RemoteCommandLog> object.

404 Not Found — Agent not found (agent_not_found).

{
  "items": [
    {
      "id": "a1b2c3d4",
      "sequence": 1042,
      "agentId": "c4a1b2c3-d4e5-6789-abcd-ef0123456789",
      "agentHostname": "PROV-WORKER-01",
      "commandType": "Ping",
      "timestamp": "2026-08-24T16:50:00Z",
      "executedBy": "System",
      "status": "Success",
      "outputMessage": "Pong"
    }
  ],
  "lastSequence": 1042
}

GET /api/v1/fleet/commands?agentId={id}&since={seq}&limit={n}&status={status}

Retrieves fleet-wide command logs with optional filtering by agent, sequence cutoff, page size, and execution status.

Query Parameters

Parameter	Type	Requirement	Description
agentId	string	Optional	Filter to records for a specific agent.
since	long	Optional	Return records with `sequence > since` (default 0).
limit	int	Optional	Maximum items returned (default 200, max 2000).
status	string	Optional	Filter by status: `Pending`, `Success`, `Warning`, or `Failed`.

Response

200 OK — LogPage<RemoteCommandLog> object.

SSE /api/v1/fleet/commands/stream?agentId={id}

Live Server-Sent Events stream for commands across all agents or a specific agent. Supports resuming via the Last-Event-ID header or ?since={sequence} query parameter.

Event Stream Format

event: command
id: 1042
data: {"id":"a1b2c3d4","sequence":1042,"agentId":"c4a1b2c3-d4e5-6789-abcd-ef0123456789","agentHostname":"PROV-WORKER-01","commandType":"RestartService","status":"Success","outputMessage":"Service restarted successfully."}

GET /api/v1/fleet/agents/{guid}/logs?since={seq}&limit={n}&level={level}

Retrieves a paged history of diagnostic logs forwarded from the agent Updater process.

Query Parameters

Parameter	Type	Requirement	Description
since	long	Optional	Return logs with `sequence > since` (default 0).
limit	int	Optional	Maximum logs returned (default 200, max 2000).
level	string	Optional	Filter by log level (e.g. `Information`, `Warning`, `Error`).

Response

200 OK — LogPage<UpdaterLogEntry> object.

404 Not Found — Agent not found (agent_not_found).

{
  "items": [
    {
      "id": "e7f8a9b0",
      "sequence": 4085,
      "agentId": "c4a1b2c3-d4e5-6789-abcd-ef0123456789",
      "timestamp": "2026-08-24T16:55:00Z",
      "level": "Information",
      "message": "Verified package checksum.",
      "exception": ""
    }
  ],
  "lastSequence": 4085
}

SSE /api/v1/fleet/agents/{guid}/logs/stream?level={level}

Live Server-Sent Events stream for agent Updater diagnostic logs. Supports log level filtering (e.g. Information, Warning, Error) and sequence resuming via Last-Event-ID header or ?since= query parameter.

Event Stream Format

event: log
id: 4085
data: {"id":"e7f8a9b0","sequence":4085,"agentId":"c4a1b2c3-d4e5-6789-abcd-ef0123456789","level":"Information","message":"Verified package checksum.","timestamp":"2026-08-24T16:55:00Z"}

📦 Fleet API — Package Storage

Installer storage management, version stamping, and package cleanup under the uploads root.

GET /api/v1/fleet/packages?platform={os}&app={name}

Queries available installer packages on disk, with optional filtering by platform (Windows or Linux) and application name (e.g. Agent, Updater).

Query Parameters

Parameter	Type	Requirement	Description
platform	string	Optional	Target operating system (`Windows` or `Linux`). Validated against `AgentOsType`.
app	string	Optional	Application target name (e.g. `Agent`, `Updater`).

Response

200 OK — Array of UpdatePackageInfo objects.

400 Bad Request — Unrecognised platform (unknown_platform).

[
  {
    "version": "v1.5.0",
    "artifactName": "ProvCollector.Agent.Windows.v1.5.0.msi",
    "packageType": "Agent",
    "platform": "Windows",
    "sizeMb": 24.5,
    "builtAt": "2026-08-24T12:00:00Z",
    "downloadUrl": "/api/v1/updates/download/Windows/Agent/v1.5.0",
    "sha256": "a3f5b7..."
  }
]

POST /api/v1/fleet/packages/{platform}/{app}

Uploads an installer package via multipart/form-data for a specific platform and application. The backend validates the dotted-numeric version tag, stamps it into the storage filename, and computes the SHA-256 digest.

Path Parameters

Parameter	Type	Requirement	Description
platform	string	Required	Operating system target (`Windows` or `Linux`).
app	string	Required	Application target name (e.g. `Agent`).

Form Data (multipart/form-data)

Field	Type	Requirement	Description
file	file	Required	Binary installer payload (e.g. `.msi`, `.tar.gz`).
version	string	Required	Dotted-numeric tag stampable into filename (e.g. `v1.5.0`).

Response

201 Created — UpdatePackageInfo object with Location header.

400 Bad Request — unknown_platform, no_file, or invalid_version_tag.

DELETE /api/v1/fleet/packages/{platform}

Deletes all uploaded installer packages across all applications for the specified platform.

Path Parameters

Parameter	Type	Requirement	Description
platform	string	Required	Platform name (`Windows` or `Linux`).

Response

204 No Content — Packages removed successfully.

400 Bad Request — Unrecognised platform (unknown_platform).

DELETE /api/v1/fleet/packages/{platform}/{app}

Deletes all uploaded installer packages for a specific platform and application.

Path Parameters

Parameter	Type	Requirement	Description
platform	string	Required	Platform name (`Windows` or `Linux`).
app	string	Required	Application target name (e.g. `Agent`).

Response

204 No Content — Packages removed successfully.

400 Bad Request — Unrecognised platform (unknown_platform).

🚀 Fleet API — Update Rollouts

Automated update orchestration across target agents or platform-wide nodes with progress tracking.

GET /api/v1/fleet/rollouts

Retrieves all active and completed update rollout jobs.

Response

200 OK — Array of AgentUpdateRollout objects.

POST /api/v1/fleet/rollouts

Triggers an update rollout across target agents or all platform nodes. Dispatches asynchronously with status reporting.

Request Body (CreateRolloutRequest)

{
  "platform": "Windows",
  "appName": "Agent",
  "targetVersion": "v1.5.0",
  "agentIds": [] // Empty list targets all matching platform nodes
}

Response

202 Accepted — AgentUpdateRollout object with Location header.

400 Bad Request — Package or version tag not found (package_not_found / invalid_rollout).

404 Not Found — No registered agents match the target platform (no_matching_agents).

GET /api/v1/fleet/rollouts/{id}

Queries the status and per-agent progress of an active or completed rollout job.

Path Parameters

Parameter	Type	Requirement	Description
id	string	Required	Unique 8-character rollout identifier.

Response

200 OK — AgentUpdateRollout object including results list.

404 Not Found — Rollout not found (rollout_not_found).

📈 Fleet API — Live Throughput Telemetry

Single-connection upstream throughput ingestion and SSE broadcast to connected operators.

GET /api/v1/fleet/throughput

Retrieves the latest aggregated throughput snapshot, resolved agent breakdown, and 60-second rolling averages.

Response

200 OK — ThroughputSnapshotDto object.

SSE /api/v1/fleet/throughput/stream

Continuous Server-Sent Events stream emitting live ThroughputSnapshotDto objects as metrics arrive from the upstream collector.

GET /api/v1/fleet/settings/throughput

Retrieves the current upstream ThroughputMonitor hub configuration and live connection status.

Response

200 OK — ThroughputSettingsDto object.

{
  "hubUrl": "http://provcollector.throughputmonitor:8080/hubs/throughput",
  "connectionState": "connected"
}

PUT /api/v1/fleet/settings/throughput

Configures the upstream Throughput Collector hub URL (e.g. http://provcollector.throughputmonitor:8080/hubs/throughput). Persists configuration to disk and initiates reconnection.

Request Body (ThroughputSettingsDto)

{
  "hubUrl": "http://provcollector.throughputmonitor:8080/hubs/throughput"
}

Response

200 OK — Updated ThroughputSettingsDto object.

📥 Updates & CI API (`/api/v1/updates`)

Endpoints depended upon by deployed agents and external CI build pipelines.

GET /api/v1/updates/packages?platform={platform}

Queries available installer packages across applications, optionally filtered by target platform (Windows or Linux).

Response

200 OK — Array of UpdatePackageInfo objects.

GET /api/v1/updates/download/{platform}/{appName}/{version}

Downloads a software installer package for the requested platform, application, and version tag. Path resolution is strictly contained to the designated uploads root.

POST /api/v1/updates/upload

CI multipart form endpoint for uploading compiled artifacts. Parses platform and application from packageType (e.g. "Linux Agent" or "Windows Agent").

Form Data (multipart/form-data)

Field	Type	Requirement	Description
file	file	Required	Binary installer payload.
version	string	Optional	Dotted version tag (default `v1.0.0`).
packageType	string	Optional	Package descriptor, e.g. `Agent`, `Linux Agent`, `Windows Agent` (default `Agent`).

Response

200 OK — Upload confirmation object.

400 Bad Request — No file uploaded.

{
  "status": "Uploaded",
  "artifactName": "ProvCollector.Agent.Linux.v1.5.0.tar.gz",
  "targetVersion": "v1.5.0",
  "sizeMb": 47.2,
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b955"
}

🔌 Agent SignalR Hub

Persistent bi-directional WebSocket connection at /api/v1/agent/connection?agentId={guid} coordinating real-time telemetry and remote command dispatch.

CONNECTION /api/v1/agent/connection?agentId={guid}

Handshake endpoint for remote Updaters. Requires the plain-text API key in the X-Api-Key request header and registers the connection mapping for agentId upon successful authentication.

HUB CALL Heartbeat(AgentHeartbeatPayload heartbeat)

Invoked by Updaters periodically (every 15s) to transmit uptime, CPU%, memory, and managed applications state.

HUB CALL SendLogEvent(JsonElement logEvent)

Streams structured Serilog log events from the Updater process into the server's ring-buffer log store.

CLIENT RESULT ExecuteCommand(RemoteCommandRequest request) → Task<RemoteCommandResponse>

Server-to-client invocation using SignalR Client Results. The backend invokes ExecuteCommand on the agent connection, which evaluates the command and returns the execution result asynchronously.

🧱 Data Models

Core models and data transfer contracts implemented in ProvCollector.Fleet.Contracts.

AgentNode

Fleet

Stateful projection of an agent node in the fleet registry.

Field	Type	Description
Id	string	Unique agent identifier (Machine GUID or formatted hostname).
Hostname	string	System machine hostname.
DisplayName	string	Operator-assigned display alias (defaults to Hostname or Id).
IpAddress	string	Remote connection IP address resolved from transport.
OsType	AgentOsType	`Windows` or `Linux`.
OsVersion	string	Full operating system build name.
Status	AgentStatusEnum	`Online`, `Warning`, `Offline`, `Updating`.
LastHeartbeat	DateTime	UTC timestamp of last received heartbeat.
DiscoveredAt	DateTime	UTC timestamp when this agent node was first discovered.
MachineGuid	string	Hardware machine GUID.
UptimeSeconds	double	Total system uptime in seconds (serialized from internal `TimeSpan Uptime`).
CpuUsagePercent	double	Aggregated CPU utilization percent across managed services.
MemoryUsageMb	double	Aggregated working set memory in MB across managed services.
EventsPerSecond	double	Live ingestion EPS from agent/throughput monitor.
Tags	List<string>	Assigned operator tags with derived OS tag projected in.
PendingUpdateVersion	string?	Target package version while an update rollout is actively dispatching.
Applications	List<ManagedApplicationStatus>	Per-service status list (e.g. Agent, Updater).

AgentHeartbeatPayload

Hub

Telemetry payload pushed by Updaters over the SignalR hub every 15 seconds.

Field	Type	Description
AgentId	string	Unique agent identifier.
Hostname	string	System machine hostname.
IpAddress	string	Resolved by the hub from the transport connection.
OsType	string	Operating system name (`Windows` or `Linux`).
OsVersion	string	Operating system kernel and build version.
Status	string	Current agent operational status string.
CpuUsagePercent	double	Total CPU percent summed across managed applications.
MemoryUsageMb	double	Total working set memory in MB summed across managed applications.
UptimeSeconds	double	Host system uptime in seconds.
EventsPerSecond	double	Agent provenance event ingestion rate.
Timestamp	DateTime	UTC timestamp of heartbeat generation.
Applications	List<ManagedApplicationStatus>?	Application statuses (installed versions, service state, and resource usage).

ManagedApplicationStatus

Fleet / Hub

State and resource consumption of an individual application managed by the Updater.

Field	Type	Description
Name	string	Managed service name (e.g. `Agent`, `Updater`).
Status	string	Current service status (e.g. `Running`, `Stopped`).
Version	string	Installed package version tag.
CpuUsagePercent	double	Process CPU usage percentage.
MemoryUsageMb	double	Process working set memory in MB.

AgentTelemetryDto

Telemetry

Concise telemetry summary for agent detail headers.

Field	Type	Description
CpuUsagePercent	double	Aggregated CPU utilization percent.
MemoryUsageMb	double	Aggregated working set memory in MB.
EventsPerSecond	double	Ingested events per second.
Stale	bool	`true` if the agent is currently disconnected or offline.
RetrievedAt	DateTime	Timestamp corresponding to the telemetry snapshot.

Config DTOs

Config

Contracts for remote configuration retrieval, single-agent updates, and fleet-wide synchronization.

AgentConfigResponse

Field	Type	Description
Files	Dictionary<string, object?>	Keyed configuration file documents (e.g. `Agent`, `Updater`).
Stale	bool	`true` if returned from backend cache because agent is offline.
RetrievedAt	DateTime	UTC timestamp of configuration retrieval.

PushConfigResult

Returned individually by PUT /api/v1/fleet/agents/{guid}/config and as an array across fleet nodes by PUT /api/v1/fleet/agents/config.

Field	Type	Description
Written	bool	`true` if the configuration file was written to disk by the remote agent.
Restarted	bool	`true` if the affected services restarted cleanly after writing.
Message	string	Diagnostic message or failure explanation.

RemoteCommandLog

Commands

Monotonically sequenced record of a remote command dispatch and outcome.

Field	Type	Description
Id	string	Unique 8-character random identifier.
Sequence	long	Monotonic sequence number for paging and SSE resumption.
AgentId	string	Target agent ID.
AgentHostname	string	Target agent machine hostname.
CommandType	string	Command type dispatched (e.g. `RestartService`, `TriggerUpdateCheck`).
Timestamp	DateTime	UTC execution timestamp.
ExecutedBy	string	Operator or system identity that initiated the command.
Status	string	`Pending` \| `Success` \| `Warning` \| `Failed`.
OutputMessage	string	Result message or exception output from the agent.

UpdaterLogEntry

Logs

Diagnostic log event forwarded from an agent Updater process.

Field	Type	Description
Id	string	Unique 8-character random identifier.
Sequence	long	Monotonic sequence number in the backend log store.
AgentId	string	Originating agent ID.
Timestamp	DateTime	UTC event timestamp.
Level	string	Serilog log level (`Verbose`, `Debug`, `Information`, `Warning`, `Error`, `Fatal`).
Message	string	Rendered log message text.
Exception	string	Captured exception message and stack trace, if any.

LogPage<T>

Pagination

Pagination envelope returned by command and log list endpoints.

Field	Type	Description
Items	List<T>	Page items array (`RemoteCommandLog` or `UpdaterLogEntry`).
LastSequence	long	Highest sequence number in the page (0 if empty). Pass as `?since=` or `Last-Event-ID` to continue streaming.

UpdatePackageInfo

Packages

Metadata describing an available installer package stored on disk.

Field	Type	Description
Version	string	Parsed version tag (e.g. `v1.5.0`).
ArtifactName	string	Filename on disk.
PackageType	string	Application target (e.g. `Agent`, `Updater`).
Platform	string	`Windows` or `Linux`.
SizeMb	double	Package file size in megabytes.
BuiltAt	DateTime	File last write time UTC.
DownloadUrl	string	Download URL path under `/api/v1/updates/download/{platform}/{appName}/{version}`.
Sha256	string	Lowercase hex-encoded SHA-256 package digest.

AgentUpdateRollout & RolloutAgentResult

Rollouts

Models capturing fleet-wide software rollouts and individual agent progress.

AgentUpdateRollout

Field	Type	Description
Id	string	Unique 8-character rollout identifier.
TargetVersion	string	Version tag being deployed (e.g. `v1.5.0`).
Platform	string	Target platform (`Windows` or `Linux`).
AppName	string	Target application name (e.g. `Agent`).
InitiatedAt	DateTime	UTC initiation timestamp.
CompletedAt	DateTime?	UTC completion timestamp (null while running).
TotalAgents	int	Total count of target agents.
CompletedAgents	int	Count of agents that updated successfully.
FailedAgents	int	Count of agents that failed the update.
Status	string	`InProgress` \| `Completed` \| `PartialSuccess` \| `Failed`.
Results	List<RolloutAgentResult>	Per-agent update status and diagnostics.

RolloutAgentResult

Field	Type	Description
AgentId	string	Target agent ID.
DisplayName	string	Agent friendly display name.
Status	string	`Pending` \| `Success` \| `Warning` \| `Failed`.
CommandId	string?	Remote command execution ID dispatched for the update.
Message	string	Diagnostic message or error text.

Throughput DTOs

Throughput

Contracts representing live topic throughput metrics, breakdowns, and settings.

ThroughputSnapshotDto

Field	Type	Description
Topic	string	Monitored pipeline topic name.
TotalEvents	long	Total lifetime events processed.
CurrentEps	double	Instantaneous events per second rate.
MovingAverage10s	double	10-second rolling EPS average.
MovingAverage60s	double	60-second rolling EPS average.
ActiveAgentCount	int	Number of active agents emitting telemetry.
EventTypeCounts	List<EventTypeCountDto>	Flattened event type counts.
AgentEventTypeBreakdown	List<AgentEventTypeBreakdownDto>	Per-agent event type counts with resolved agent names.
Agents	List<ThroughputAgentRowDto>	Per-agent status (`Active`, `Idle`, `Inactive`), total events, and EPS.
Timeline	List<ThroughputTimelinePointDto>	Historical timeline points for UI charts.
CapturedAt	DateTime	UTC capture timestamp.

ThroughputSettingsDto

Field	Type	Description
HubUrl	string	Configured upstream ThroughputMonitor hub URL.
ConnectionState	string	Connection state: `connected`, `connecting`, `reconnecting`, `disconnected`.

Hub Command DTOs

Hub

Payload contracts used for SignalR ExecuteCommand Client Result invocations.

RemoteCommandRequest

Field	Type	Description
CommandType	string	Command identifier (e.g. `Ping`, `PushConfig`, `TriggerUpdateCheck`).
RequestId	string?	Correlation ID generated by the backend.
Payload	object?	Command-specific arguments (e.g. normalized config tree).

RemoteCommandResponse

Field	Type	Description
Success	bool	`true` if execution succeeded on the agent host.
Message	string	Summary or error message.
RequestId	string	Echoed correlation ID.
Timestamp	DateTime	UTC execution timestamp.
Data	object?	Optional returned payload (e.g. config file dictionary).

🏷️ Enumerations & Problem Codes

Constants and RFC 9457 Problem Details error codes used across the FleetServer API.

AgentStatusEnum

Online — Connected and responding
Warning — Operating with warnings
Offline — Disconnected
Updating — Software update in progress

AgentOsType

Windows — Microsoft Windows
Linux — Linux distributions

CommandStatuses

Pending — Awaiting agent pickup/execution
Success — Executed cleanly
Warning — Completed with partial warnings
Failed — Execution or dispatch failed

Rollout Statuses

InProgress — Dispatching updates to fleet
Completed — All targeted agents updated
PartialSuccess — Some agents updated, some failed
Failed — All targeted updates failed

ProblemCodes (RFC 9457)

agent_offline — Agent exists but is not connected
agent_not_found — Identifier not recognized
agent_connected — Cannot delete connected node without force
command_not_found — Command ID does not exist for agent
unknown_command_type — Command type name is unrecognized
unknown_platform — Unrecognized OS platform identifier
package_not_found — Requested installer package absent
invalid_version_tag — Version tag not stampable into filename
invalid_config — Configuration document is empty or malformed
no_matching_agents — Target platform has zero registered agents
rollout_not_found — Rollout ID does not exist

FleetServer API Reference

🔒 Authentication & Security

⚡ Fleet API — Agents & Telemetry

⚙️ Fleet API — Remote Configuration

📡 Fleet API — Commands, Logs & SSE

📦 Fleet API — Package Storage

🚀 Fleet API — Update Rollouts

📈 Fleet API — Live Throughput Telemetry

📥 Updates & CI API (/api/v1/updates)

🔌 Agent SignalR Hub

🧱 Data Models

AgentNode

AgentHeartbeatPayload

ManagedApplicationStatus

AgentTelemetryDto

Config DTOs

AgentConfigResponse

PushConfigResult

RemoteCommandLog

UpdaterLogEntry

LogPage<T>

UpdatePackageInfo

AgentUpdateRollout & RolloutAgentResult

AgentUpdateRollout

RolloutAgentResult

Throughput DTOs

ThroughputSnapshotDto

ThroughputSettingsDto

Hub Command DTOs

RemoteCommandRequest

RemoteCommandResponse

🏷️ Enumerations & Problem Codes

AgentStatusEnum

AgentOsType

CommandStatuses

Rollout Statuses

ProblemCodes (RFC 9457)

📥 Updates & CI API (`/api/v1/updates`)