# Management API (/operate/observability/api-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.

<Callout type="info" title="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.
</Callout>

## Base URL [#base-url]

All endpoints are served on the management API port (`:8080`), configurable via `api.port`:

```text
http://<host>:8080
```

## Response envelope [#response-envelope]

Most HTTP endpoints wrap their response in a standard envelope:

```json
{
  "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 [#endpoints-that-dont-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 [#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 [#not-ready-guard]

Most endpoints under `/api/*` are gated by a readiness check. If the API service has not
finished initialization, those endpoints return:

```json
{
  "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 monitor
* `GET /v1/stats/attach` — the same handler, mounted under the stats group

## Access control [#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](/configure/reference/observability) for the
related configuration keys.

## Server configuration [#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 [#reference]

<Cards>
  <Card title="Health & System Endpoints" href="/operate/observability/api-reference/health-system" description="Liveness and readiness probes, billing, and the metrics endpoint, with a Kubernetes probe example." />

  <Card title="Stats Endpoints" href="/operate/observability/api-reference/stats" description="Read-only statistics for queues, channels, clients, and events stores." />

  <Card title="Dashboard Endpoints" href="/operate/observability/api-reference/dashboard-endpoints" description="Pre-aggregated snapshot endpoints that power the dashboard — single-node and cluster snapshots plus time-bucketed activity." />

  <Card title="Action Endpoint" href="/operate/observability/api-reference/actions" description="The unified POST /api/request endpoint for channel management and sending or receiving messages." />

  <Card title="WebSocket Protocols" href="/operate/observability/api-reference/websockets" description="Real-time management WebSockets — the cluster snapshot stream and the live message monitor." />

  <Card title="Data Models" href="/operate/observability/api-reference/data-models" description="JSON schemas for the shared DTOs returned by the management API." />
</Cards>