API Reference
WebSocket Events
Real-time change notifications via /api/v1/ws — connecting, what each message carries and what it deliberately doesn't — and the pod-terminal socket.
GET /api/v1/ws upgrades to a WebSocket that tells the UI something changed
so it can refetch. It is a notification feed, not a data feed: the payloads
name what changed, and the REST API serves the data.
Connecting
A browser cannot set an Authorization header on a WebSocket upgrade, so when
authentication is enabled the session access token goes in the query
string:
wss://kubebolt.example.com/api/v1/ws?token=<access-token>
- Only a session access token (from
POST /api/v1/auth/loginor/auth/refresh) is accepted here. API tokens are not. - A missing or invalid token gets
401 authentication required(plain text) before the upgrade. With authentication disabled, no token is needed. - The token is checked once, at the upgrade. An open socket stays open after the token expires; reconnect with a fresh one.
- Any role may connect.
- The server pings every 54 seconds and drops a connection that hasn’t answered within 60. Frames the client sends are read and ignored (up to 4 KB each).
On KubeBolt Cloud, connect to
wss://api.kubebolt.io/api/v1/ws and add cluster=<context> — the context
from GET /api/v1/clusters. The socket then receives that cluster’s resource
and insight events and nothing from any other organization. Without
cluster, or naming a cluster your teams don’t own, the socket stays open but
only receives the install-wide events (cluster:connected, cluster.switched,
clusters.changed). To follow another cluster, reconnect with its context.
Message shape
Every message is a JSON envelope:
{ "type": "resource:updated", "data": { … }, "cluster": "prod-eu-west", "tenant": "…" }
cluster (the context that produced the event) and tenant are present on
resource and insight events and absent on install-wide ones.
For resource events, data is a notification, not the object:
{
"type": "resource:updated",
"data": {
"kind": "Deployment",
"metadata": { "namespace": "shop", "name": "checkout", "uid": "…" }
},
"cluster": "prod-eu-west"
}
To see what changed, fetch it through the REST API (for example
GET /api/v1/resources/deployments/shop/checkout), which applies the same
redaction and role checks as the rest of the product.
The socket never carries object bodies. It used to send the full informer
object, which meant every Secret change reached every connected browser;
since 2.0.3 it sends only {kind, namespace, name, uid}.
There is no per-kind subscription: a client receives every notification for the clusters it is viewing and decides what to refetch.
Event types
| Type | data | When |
|---|---|---|
resource:updated | {kind, metadata: {namespace, name, uid}} | A watched object was added or changed — Kubernetes Events included |
resource:deleted | {kind, metadata: {namespace, name, uid}} | A watched object was removed |
insight:new | The insight, as in GET /api/v1/insights | A new insight fired |
insight:resolved | The insight | An insight resolved |
cluster:connected | {context, clusterId} or {context} | A previously-failed agent-connected cluster recovered, or KubeBolt selected a cluster on its own — the UI refreshes cluster state immediately |
cluster.switched | {context} | The active cluster changed |
clusters.changed | null | The cluster registry changed (added, removed, renamed) |
Only the cluster you are viewing emits resource and insight events. Clusters
parked in the background keep their informers and insights engine running, but
stay quiet on the socket. In the open-source edition every socket receives the
events of the active cluster; use the cluster field if you watch more than
one.
Delivery
Delivery is best-effort. The hub queues up to 4096 messages and drops new ones when that queue is full or no client is connected; each client has its own buffer of 256, and a client that can’t keep up is disconnected. The UI reconnects with backoff (1 second, doubling up to 30) and its periodic refetch covers anything missed — do the same in your own client and treat the REST API as the source of truth.
Pod terminal
The Terminal tab uses a second socket, mounted at the root rather than
under /api/v1:
wss://kubebolt.example.com/ws/exec/<namespace>/<pod>?token=<access-token>&container=<name>&shell=/bin/sh
- It needs the Editor role:
401without a valid session access token,403below Editor, both before the upgrade. containerdefaults to the pod’s first container.shelldefaults to/bin/bashwhen the container has it, otherwise/bin/sh.- It takes no cluster header and opens on the cluster currently selected in KubeBolt.
- KubeBolt’s own credentials need
createonpods/exec— see RBAC.
Frames are JSON in both directions:
| Direction | Message |
|---|---|
| Client → server | {"type": "stdin", "data": "ls -la\n"} |
| Client → server | {"type": "resize", "cols": 120, "rows": 40} |
| Server → client | {"type": "stdout", "data": "…"} and {"type": "stderr", "data": "…"} |
| Server → client | {"type": "exit", "code": 0} when the shell ends |
| Server → client | {"type": "error", "message": "…"}, for example when RBAC refuses pods/exec |
Opening and closing a terminal is recorded in the audit trail as an access session, with the pod, container, shell and exit code. What is typed and printed is never recorded.