These endpoints power the built-in dashboard. They return pre-aggregated, UI-ready data structures with humanized values — formatted numbers, relative timestamps, and percentages alongside the raw values. They all live under /api/ on the management API port (:8080), use the standard response envelope, and are gated by the readiness check.

The snapshot payloads contain many nested DTOs. This page documents the top-level shape of each response; for the full field-by-field schema of every nested type, see Data Models.

Poll, don't hammer

The server recomputes the snapshot internally every 5 seconds. Polling faster than that returns the same data — poll the snapshot endpoints every 5–10 seconds. For a push-based stream instead of polling, use the /api/connection WebSocket.

GET /api/snapshot

Returns the current single-node snapshot — everything needed to render the dashboard for one KubeMQ node: host info, topology, stat cards, per-channel detail, and per-client detail. The response data is a SnapshotDTO.

{
  "error": false,
  "error_string": "",
  "data": {
    "hostsInfo": [
      {
        "host": "kubemq-node-0",
        "version": "2.5.0",
        "status": "Running",
        "role": "Leader",
        "uptime": "24h0m0s",
        "activeClients": 8
      }
    ],
    "topologyNodes": {
      "clusterNodesList": ["kubemq-node-0", "kubemq-node-1"],
      "clientNodesList": ["order-service", "payment-service"],
      "clusterClientConnections": [
        { "clusterNode": 0, "clientNode": 0 },
        { "clusterNode": 0, "clientNode": 1 }
      ]
    },
    "trafficChannels": {
      "channels": {
        "queues/orders": [
          { "clientId": "order-service", "side": "send" },
          { "clientId": "payment-service", "side": "receive" }
        ]
      }
    },
    "statsCards": { "...": "StatCardDTOs" },
    "topChannels": [
      {
        "type": "Queue",
        "channel": "orders.process",
        "lastActivity": "2 seconds ago",
        "sent": "5,000/4.9 MB",
        "delivered": "4,800/4.7 MB",
        "clients": "3/5"
      }
    ],
    "lastActivity": 1709312400000,
    "lastActivityHuman": "2 seconds ago",
    "total": { "...": "BaseValuesDTO" },
    "incoming": { "...": "BaseValuesDTO" },
    "outgoing": { "...": "BaseValuesDTO" },
    "channels": 10,
    "clients": 8,
    "activeChannels": 5,
    "queues": { "...": "FamilyDTO" },
    "pubsub": { "...": "FamilyDTO" },
    "commandsQueries": { "...": "FamilyDTO" },
    "nodeType": "standalone",
    "node": "kubemq-node-0"
  }
}

Top-level fields

Field	Type	Description
`hostsInfo`	`HostInfoDTO[]`	System info for each node — memory, CPU, storage, uptime, role, active clients.
`topologyNodes`	`TopologyNodesDTO`	Cluster-to-client connection graph for the topology visualization.
`trafficChannels`	`TrafficChannelsDTO`	Per-channel client connections with the send/receive side.
`statsCards`	`StatCardDTOs`	Pre-computed overview cards (channels, clients, incoming, outgoing).
`topChannels`	`TopChannelDTO[]`	The 10 most recently active channels.
`lastActivity`	`int64`	Unix timestamp (ms) of the last activity across all channels.
`lastActivityHuman`	`string`	Human-readable relative time (e.g. `"2 seconds ago"`).
`total`	`BaseValuesDTO`	Combined incoming + outgoing totals.
`incoming`	`BaseValuesDTO`	Aggregate incoming metrics.
`outgoing`	`BaseValuesDTO`	Aggregate outgoing metrics.
`channels`	`int64`	Total channel count.
`clients`	`int64`	Total client count.
`activeChannels`	`int64`	Number of currently active channels.
`queues`	`FamilyDTO`	The Queues family — full per-channel and per-client detail.
`pubsub`	`FamilyDTO`	The Pub/Sub family (Events + Events Store combined).
`commandsQueries`	`FamilyDTO`	The CQRS family (Commands + Queries combined).
`nodeType`	`string`	Node type from configuration.
`node`	`string`	Node hostname.

Use statsCards for the overview cards, topChannels for the recent-activity table, hostsInfo for node health, topologyNodes for the cluster graph, and the three FamilyDTO objects (queues, pubsub, commandsQueries) for the detailed channel and client views. Each humanized value has a raw counterpart (e.g. lastActivity / lastActivityHuman); see Data Models for the complete nested schemas.

GET /api/cluster-snapshot

Returns the cluster-wide aggregated snapshot. In a multi-node cluster this merges data from every node; in standalone mode it is equivalent to /api/snapshot.

The response uses the same SnapshotDTO schema as /api/snapshot, with data aggregated across all cluster nodes:

hostsInfo contains one entry per node.
Channel and client entities are combined across nodes.
Queue waiting counts reflect the cluster total.

Use this endpoint for the cluster-wide dashboard view.

GET /api/last-diff

Returns time-bucketed channel activity — historical time-series data showing how each channel's metrics changed over a set of time windows. This is the data behind the dashboard's sparklines and activity charts.

The response data is a channel-first nested map:

map[channel]            → channel key, format "{type}/{name}"
  map[resolution]       → resolution key, e.g. "1h", "7d"
    TimeBucket
      resolution        → resolution identifier
      items[]           → data points (up to 30 per resolution)

{
  "error": false,
  "error_string": "",
  "data": {
    "queues/orders": {
      "1h": {
        "resolution": "1h",
        "items": [
          {
            "timestamp": "2024-03-01T11:00:00Z",
            "inMessages": 100,
            "inVolume": 20480,
            "outMessages": 95,
            "outVolume": 19456
          },
          {
            "timestamp": "2024-03-01T11:02:00Z",
            "inMessages": 50,
            "inVolume": 10240,
            "outMessages": 48,
            "outVolume": 9830
          }
        ]
      },
      "1d": {
        "resolution": "1d",
        "items": [
          {
            "timestamp": "2024-03-01T00:00:00Z",
            "inMessages": 5000,
            "inVolume": 1024000,
            "outMessages": 4800,
            "outVolume": 983040
          }
        ]
      }
    }
  }
}

TimeBucket

Field	Type	Description
`resolution`	`string`	Resolution identifier (see the table below).
`items`	`TimeBucketItem[]`	Up to 30 data points, zero-padded if fewer points exist.

TimeBucketItem

Field	Type	Description
`timestamp`	`string` (RFC3339)	Start of the time bucket.
`inMessages`	`int64`	Incoming message-count delta for the bucket.
`inVolume`	`int64`	Incoming volume delta (bytes).
`outMessages`	`int64`	Outgoing message-count delta.
`outVolume`	`int64`	Outgoing volume delta (bytes).

Resolutions

Every channel carries data at all eight resolutions; each resolution holds up to 30 data points covering its window.

Resolution	Time range	Point interval
`1h`	Last 1 hour	2 minutes
`2h`	Last 2 hours	4 minutes
`6h`	Last 6 hours	12 minutes
`12h`	Last 12 hours	24 minutes
`1d`	Last 24 hours	48 minutes
`7d`	Last 7 days	5.6 hours
`14d`	Last 14 days	11.2 hours
`30d`	Last 30 days	24 hours

To render a sparkline for a channel, look up its key (e.g. "queues/orders"), pick a resolution, and plot the items array.

GET /api/agents

Returns the registered AI agents as a paginated list. This is one of the AI-dashboard endpoints behind the dashboard's agents area; see the Prometheus metrics page for the agent-platform metric series.

Query parameters

Parameter	Type	Default	Description
`offset`	`int`	`0`	Zero-based index of the first agent to return.
`limit`	`int`	`50`	Maximum agents to return. Capped at 100 — larger values are clamped.

curl "http://localhost:8080/api/agents?offset=0&limit=50"

The response uses the standard envelope; data is the paginated list of registered agents with their presence and lifetime stats.

GET /api/agents/:id

Returns the detail for a single registered agent, identified by the :id path parameter. The response data carries the agent's record plus a stats snapshot — lifetime request, error, and latency totals along with per-method and per-outcome breakdowns.

curl "http://localhost:8080/api/agents/order-router"

Like the list endpoint, the agent detail uses the standard envelope.

Data Models

Full field-by-field schemas for SnapshotDTO and every nested dashboard DTO.

WebSocket Protocols

The 2-second cluster snapshot stream as a push alternative to polling.

Dashboard Endpoints