Management API
The HTTP and WebSocket management API on port 8080 — response envelope, status codes, access control, and the full endpoint and data-model reference.
KubeMQ serves an HTTP and WebSocket management API on port 8080. It powers the built-in
dashboard, exposes health and readiness probes, returns statistics and pre-aggregated
snapshots, queries the audit log, and accepts management actions such as creating channels
or sending and receiving messages from tooling. This reference documents the response
envelope, status-code rules, access control, and every endpoint and data model.
This is the management API, not the SDK
This API is for operators, dashboards, and tooling — health checks, statistics, snapshots, audit queries, and channel/message management from a console or script. To send and consume messages in application code, use the language SDKs, which speak KubeMQ's gRPC API with connection pooling, streaming, and reconnection built in. The management API is not the recommended path for production message flow.
Base URL
All endpoints are served on the management API port (:8080), configurable via api.port:
http://<host>:8080Response envelope
Most HTTP endpoints wrap their response in a standard envelope:
{
"error": false,
"error_string": "",
"data": { }
}| Field | Type | Description |
|---|---|---|
error | boolean | true if the request failed |
error_string | string | Error message when error is true; empty string on success |
data | object, array, or null | Response payload — the shape depends on the endpoint |
Endpoints that don't use the envelope
A handful of endpoints return raw responses instead of the envelope — they are meant for probes, scrapers, and real-time streams:
| Endpoint | Response format |
|---|---|
GET /health | Plain text (healthy or not healthy) |
GET /ready | Raw HealthState JSON (no envelope) |
GET /metrics | Prometheus text exposition format |
GET /kill | Disabled — plain-text HTTP 404 |
GET /api/monitor, GET /v1/stats/attach | WebSocket (no HTTP envelope) |
HTTP status codes
The API is not strictly "always 200". Most successes and business-logic errors return HTTP 200 with the envelope, but there are exceptions:
| Scenario | HTTP status | Response format |
|---|---|---|
| Successful request | 200 | Envelope with error: false |
| Business-logic error (validation, not found, etc.) | 200 | Envelope with error: true |
Not healthy (/health) | 500 | Plain text |
Not ready (/ready) | 500 | Raw HealthState JSON |
| WebSocket upgrade failure | 500 | Envelope with error: true |
/kill | 404 | Plain text |
| Unknown path | 404 | Plain text |
Check the HTTP status code first. On 200, parse the envelope and inspect the error
boolean. On a non-200 status, treat the response as a transport-level failure.
Not-ready guard
Most endpoints under /api/* are gated by a readiness check. If the API service has not
finished initialization, those endpoints return:
{
"error": true,
"error_string": "api service not ready",
"data": null
}Two endpoints are not gated by this guard and are available as soon as the HTTP server starts:
GET /api/monitor— the live message monitorGET /v1/stats/attach— the same handler, mounted under the stats group
Access control
When control-plane authentication is enabled, every management endpoint requires at least the ReadOnly role. Read-only roles can call the health, stats, snapshot, audit-query, and monitor endpoints; mutating actions (creating channels, sending messages) require a role with write permissions. See the Observability settings reference for the related configuration keys.
Server configuration
| Setting | Default | Description |
|---|---|---|
api.port | 8080 | HTTP server listen port |
| Read timeout | 180s | Maximum time to read a full request |
| Write timeout | 180s | Maximum time to write a full response |
Reference
Health & System Endpoints
Liveness and readiness probes, billing, and the metrics endpoint, with a Kubernetes probe example.
Stats Endpoints
Read-only statistics for queues, channels, clients, and events stores.
Dashboard Endpoints
Pre-aggregated snapshot endpoints that power the dashboard — single-node and cluster snapshots plus time-bucketed activity.
Action Endpoint
The unified POST /api/request endpoint for channel management and sending or receiving messages.
WebSocket Protocols
Real-time management WebSockets — the cluster snapshot stream and the live message monitor.
Data Models
JSON schemas for the shared DTOs returned by the management API.
Was this page helpful?
Audit Logging
KubeMQ's CloudEvents audit trail of auth, lifecycle, and data-plane events — the event catalog, retention settings, and the REST query API.
Health & System Endpoints
Liveness and readiness probes, billing, and the metrics endpoint on KubeMQ's management API, with a Kubernetes probe example.