KubeBolt docs
ENES GitHub

API Reference

REST API Reference

Every user-facing route under /api/v1 — base URLs, authentication, cluster selection, roles, errors, dry runs, and the endpoint tables.

On this page
  1. Base URL
  2. Authentication
  3. Selecting a cluster
  4. Roles
  5. Errors
  6. Lists and pagination
  7. Dry runs
  8. Examples
  9. Clusters
  10. Resources
  11. Actions
  12. Insights
  13. Security
  14. Metrics & network
  15. Port-forward
  16. Helm
  17. Kobi and MCP
  18. Account
  19. Integrations and agents
  20. Auth, users and teams
  21. Administration
  22. Cloud only
  23. Real-time

Everything the UI does goes through this API, so anything you can do in KubeBolt you can script. All routes live under /api/v1, with a few exceptions mounted at the root: the pod-terminal WebSocket at /ws/exec/{namespace}/{name}, the port-forward reverse proxy at /pf/{id}/, the /health probe and the API’s own /metrics.

Base URL

InstallBase URL
Helm chart or Docker Compose, through the UI URLhttps://<your-kubebolt>/api/v1 — the bundled nginx proxies /api/ to the API
Helm chart, from inside the clusterhttp://<release>-api.<namespace>.svc:8080/api/v1
Single binary / single containerThe port it serves on (8080 for the binary, 3000 in the container image), plus /api/v1
KubeBolt Cloudhttps://api.kubebolt.io/api/v1

Authentication

Send Authorization: Bearer <token> on every request. The token is either a session access token from POST /auth/login (15 minutes by default — see Authentication) or an API token (kbk_ / kbs_), which is what scripts, CI and MCP hosts should use. An API token’s role, scopes and cluster list all apply.

API tokens and the public edge. kbs_ service tokens are rejected when the request arrives through the bundled nginx or the chart’s Gateway API route, which force-set X-KubeBolt-Edge: public. Use a kbk_ API key from outside; reach the API Service directly for machine-to-machine calls — see API tokens.

When authentication is enabled, everything requires a token except these public routes:

RouteWhy it is public
GET /auth/configThe login page needs to know whether auth and signup are on (enabled, signupEnabled)
POST /auth/login · POST /auth/refreshEstablishing and rotating the session
POST /auth/signupSelf-service organization signup. Returns 409 with "code": "requires_ee" in the open-source build
GET /copilot/configThe login page decides whether to render the chat panel. Best-effort auth: a valid token resolves your organization, an invalid one is ignored rather than rejected
GET /config/uiDisplay name and default refresh interval — chrome, no secrets
POST /prom/writeRemote-write ingest. Gated by KUBEBOLT_REMOTE_WRITE_ENABLED (default off) and its own ingest-token mode, not by a session
POST /ingest/falcoFalco runtime events. Authenticated inside the handler with a cluster-scoped ingest token — strict, no permissive fallback

At the root, GET /health answers ok without auth, and a self-hosted API serves Prometheus metrics about itself at GET /metrics on its own port — also unauthenticated, so keep that port off the public edge. KubeBolt Cloud adds public routes for social sign-in, email verification, password reset and invitations; they back the sign-in pages and are not meant for scripts.

Selecting a cluster

Routes that read or change a cluster act on the cluster named in the X-KubeBolt-Cluster header — its context from GET /clusters, for example prod-eu-west, or agent: followed by the cluster id for an agent-connected cluster. Without the header they act on the cluster currently selected in KubeBolt. POST /clusters/switch changes that selection for everyone on the install (on Cloud, for the whole organization), so automation should send the header instead of switching.

The Live column below marks routes that need that cluster connected right now. When it isn’t, they answer 503 with the reason: cluster not connected (or the connection error), no cluster selected — choose a cluster to continue, no agent connected yet for this cluster — waiting for agent to register, or, for a monitored-only cluster, cluster is monitored-only — …. After a failed connect, the reason ends with (next attempt in …): requests wait 30 seconds, then 1, 2 and 4 minutes, at most 5, instead of each starting a new connect; an agent reconnecting or POST /clusters/switch tries at once. Routes without the mark read stored data — history, findings, the metrics store — and keep answering for clusters that are down or gone.

In resource paths, {ns} is the namespace; use _ for cluster-scoped resources such as nodes. URL-encode {context} and the header value — EKS contexts are ARNs with : and / in them.

Roles

Reads need any authenticated role, except the pod file browser: it runs commands inside the container, so it needs Editor, like the terminal. Writes need Editor; destructive actions (DELETE on a resource, node drain) and every admin surface need Admin. Some handlers raise the bar further — revealing a Secret in a production-pattern namespace needs Admin. On KubeBolt Cloud, Editors and Viewers only reach clusters owned by their teams. Whatever the role, the cluster’s own RBAC has the last word: see RBAC.

Errors

Errors carry a JSON body with an error message, and sometimes a machine-readable code:

{ "error": "insufficient permissions" }
{ "error": "self-service signup requires the multi-org edition", "code": "requires_ee" }
StatusMeaning
400Malformed body or parameters
401Missing token, or one that is malformed, expired or revoked (authentication required, invalid or expired token)
403The role is too low (insufficient permissions); an API token is outside its scopes or on a path no token may reach; the cluster isn’t one the caller may read (you do not have access to this cluster); Kubernetes RBAC denied the read (insufficient permissions to access <type>); on Cloud, "code": "email_unverified" until the email is verified
404No such resource or route. On Cloud, install-wide administration answers 404 to organization users
409Conflict, such as a username that already exists; "code": "requires_ee" for Cloud-only features on the open-source edition
429Sign-in throttled (with Retry-After); an eviction blocked by a PodDisruptionBudget
502An upstream KubeBolt depends on is unreachable — the metrics store, the AI provider, a notification channel
503The cluster is not live (see above), or the feature’s backing store is off (for example with authentication disabled)

There is no general request rate limit on the REST API. Sign-in is throttled per username (on Cloud, the sign-in routes also per client IP), and remote-write ingest per tenant.

Lists and pagination

GET /resources/{type} filters and paginates on the server and returns {kind, items, total}:

ParameterMeaning
namespaceOne namespace; omit for all
searchSubstring of the name or namespace
statusExact status, or degraded for everything not healthy (pending, crash-looping, not ready)
nodePods on one node
sort · orderColumn and asc / desc; the default is by name, so pages are stable
page · limitFrom page 1, 50 per page by default

It accepts pods, deployments, statefulsets, daemonsets, replicasets, jobs, cronjobs, services, endpoints, ingresses, networkpolicies, gateways, httproutes, pdbs, hpas, configmaps, secrets, serviceaccounts, pvcs, pvs, storageclasses, nodes, namespaces, events, roles, clusterroles, rolebindings, clusterrolebindings, and the optional CRDs certificates, argocdapps, vpas, ciliumnetworkpolicies and ciliumclusterwidenetworkpolicies. An unknown type returns an empty list.

Elsewhere: /findings pages with page and pageSize (25 by default, at most 200), /insights/episodes with page and limit (at most 200), /events and /admin/actions take a limit, and GET /insights returns the whole list.

Dry runs

Restart, scale, rollback, set-image, set-resources, set-env, set-bounds, debug and delete accept ?dryRun=true. The request goes through full server-side admission (dryRun=All) — validation, quotas, LimitRanges, webhooks — and nothing is persisted. The answer is always 200, with the verdict in the body:

{ "ok": false, "message": "ResourceQuota \"team-quota\" exceeded", "quota": { … } }

See Actions & Governance.

Examples

With an API key whose scopes cover the paths used:

KB=https://kubebolt.example.com/api/v1
AUTH="Authorization: Bearer $KUBEBOLT_TOKEN"

# Clusters the token may read (scope /api/v1/clusters)
curl -s -H "$AUTH" "$KB/clusters" | jq -r '.[] | "\(.context)\t\(.status)"'

# Unhealthy pods in one namespace of one cluster (scope /api/v1/resources)
curl -s -H "$AUTH" -H "X-KubeBolt-Cluster: prod-eu-west" \
  "$KB/resources/pods?namespace=shop&status=degraded&limit=100"

# The last 200 lines of a container's log
curl -s -H "$AUTH" -H "X-KubeBolt-Cluster: prod-eu-west" \
  "$KB/resources/pods/shop/checkout-7d9f8c6b5-x2x4q/logs?container=app&tailLines=200"

# Critical insights (scope /api/v1/insights)
curl -s -H "$AUTH" -H "X-KubeBolt-Cluster: prod-eu-west" "$KB/insights?severity=critical"

# Scale a Deployment: preview first, then apply (Editor role)
curl -s -X POST -H "$AUTH" -H "X-KubeBolt-Cluster: prod-eu-west" \
  -H 'Content-Type: application/json' -d '{"replicas": 3}' \
  "$KB/resources/deployments/shop/checkout/scale?dryRun=true"

# Memory working set per namespace (scope /api/v1/metrics)
curl -s -G -H "$AUTH" -H "X-KubeBolt-Cluster: prod-eu-west" "$KB/metrics/query" \
  --data-urlencode 'query=sum by (namespace) (container_memory_working_set_bytes)'

The form’s scope presets don’t include /api/v1/clusters; add it when you create the key over the API, or pick Everything, if the script needs to list clusters.

Clusters

MethodEndpointRoleLiveDescription
GET/clustersAny—Registered clusters (kubeconfig contexts, in-cluster, agent-connected) with context, clusterId, status, mode and display name, and agentUpdate when the cluster’s live agents are behind the newest release: level (current, available, recommended), version (or before for an agent that does not report its own), latest, reasons and the upgrade command
GET/clusters/namesAny—Display names for every cluster, including decommissioned ones
POST/clusters/switchAny—Select the active cluster — {"context": "…"}. Shared by everyone on the install
GET/clusters/progressAny—How far the request’s cluster’s connect has gone: its state, the resource types synced, the bytes received and, after a failure, the error and when the next attempt is. Never starts or waits for a connect
POST/clustersAdmin—Register clusters from a kubeconfig — {"kubeconfig": "<yaml>"}, or the raw YAML with Content-Type: application/yaml
PUT/clusters/{context}/renameAdmin—{"displayName": "…"}; an empty name clears it
DELETE/clusters/{context}Admin—Remove an uploaded kubeconfig context
DELETE/clusters/by-id/{clusterId}Admin—Remove an agent-connected cluster. It reappears if its agent is still connected
GET/cluster/overviewAnyyesCluster summary: counts, CPU/memory, health, events, workloads. Monitored-only clusters get a metrics-based overview
GET/cluster/healthAnyyesHealth score detail
GET/cluster/permissionsAnyyesProbed RBAC per resource type — see RBAC
GET/coverageAny—Which data sources are shipping samples for the cluster
GET/update-checkAny—Latest stable KubeBolt release on GitHub. {"enabled": false} when the check is off

Resources

MethodEndpointRoleLiveDescription
GET/resources/{type}AnyyesList, filtered and paginated — see Lists and pagination
GET/resources/{type}/{ns}/{name}AnyyesDetail; pods and nodes include live CPU and memory
GET/resources/{type}/{ns}/{name}/yamlAnyyesYAML (text/yaml) — Secret values redacted, sensitive-looking ConfigMap values redacted, an Argo CD Application’s Helm values, parameters and plugin environment hidden, managedFields stripped
GET/resources/{type}/{ns}/{name}/describeAnyyeskubectl-describe style output, with the same values hidden as the YAML
GET/resources/pods/{ns}/{name}/logsAnyyesPlain-text logs: container, tailLines (100 when no time bound is given), since (a duration), sinceTime / endTime (RFC 3339), previous, timestamps
GET/resources/pods/{ns}/{name}/files · /files/content · /files/downloadEditoryesPod file browser (container, path). Editor since 2.6.4, like the terminal. Reads and downloads are audited
GET/resources/{workload}/{ns}/{name}/podsAnyyesPods of a Deployment, StatefulSet, DaemonSet or Job
GET/resources/{type}/{ns}/{name}/historyAnyyesRevision history (Deployments via ReplicaSets; StatefulSets/DaemonSets via ControllerRevisions)
GET/resources/cronjobs/{ns}/{name}/jobsAnyyesJob children of a CronJob
GET/topologyAnyyesThe cluster’s relationship graph — see Cluster Map
GET/eventsAnyyesKubernetes events: type, namespace, involvedKind, involvedName, limit (default 100). 403 when KubeBolt’s credentials may not list events
GET/searchAnyyesName search across resource types (q, up to 50 results). scope=fleet searches every cluster you may read and doesn’t need the selected one live, so ⌘K still works when one cluster is down

Actions

Every action is audited. Most bodies are small; the common ones are below the table, and Actions & Governance maps each action to Kobi’s proposals.

MethodEndpointRoleLiveDescription
PUT/resources/{type}/{ns}/{name}/yamlEditoryesApply edited YAML (raw YAML body)
POST/resources/{type}/{ns}EditoryesCreate a resource from a single YAML or JSON manifest
POST/resources/{type}/{ns}/{name}/restartEditoryesRolling restart
POST/resources/{type}/{ns}/{name}/scaleEditoryesScale a Deployment or StatefulSet
POST/resources/{type}/{ns}/{name}/rollbackEditoryesRoll back to a revision
POST/resources/{type}/{ns}/{name}/set-imageEditoryesSet container images
POST/resources/{type}/{ns}/{name}/set-resourcesEditoryesSet requests/limits
POST/resources/{type}/{ns}/{name}/set-envEditoryesSet or remove environment variables
POST/resources/hpas/{ns}/{name}/set-boundsEditoryesHorizontalPodAutoscaler min/max replicas (server-side cap at 1000)
POST/resources/{type}/{ns}/{name}/edit-metadataEditoryesLabels and annotations — the kubectl label / kubectl annotate equivalents, on any kind
POST/resources/secrets/{ns}/{name}/revealEditoryesDecode Secret values. Admin in production-pattern namespaces; requires a written reason; doubly audited — see below
POST/resources/{type}/{ns}/{name}/debugEditoryesAttach an ephemeral debug container to a running pod
POST/resources/{type}/{ns}/{name}/cordon · /uncordonEditoryesNode scheduling toggle
POST/resources/{type}/{ns}/{name}/evictEditoryesEvict a pod through the policy/v1 Eviction API — 429 when a PDB blocks it
POST/resources/{type}/{ns}/{name}/rollout-pause · /rollout-resumeEditoryesPause/resume a Deployment rollout
POST/resources/{type}/{ns}/{name}/suspend · /resume · /triggerEditoryesCronJob controls
DELETE/resources/{type}/{ns}/{name}AdminyesDelete. force=true sets a zero grace period; orphan=true keeps dependents
POST · GET · DELETE/resources/{type}/{ns}/{name}/drainAdminyesStart a node drain (an SSE stream), re-attach to the one in flight, cancel it

Common bodies:

POST …/scale        { "replicas": 3 }
POST …/rollback     { "toRevision": 0 }        // 0 or absent = the previous revision
POST …/set-image    { "images": [ { "container": "app", "image": "ghcr.io/acme/app:1.4.2" } ] }

Secret reveal

POST /resources/secrets/{ns}/{name}/reveal is the audited replacement for kubectl get secret -o yaml | base64 -d. It reads from the apiserver rather than the informer cache so a rotation check sees the current value, takes a body of {"keys": ["…"], "reason": "…"} with a reason between 10 and 500 characters, and emits two audit records — one on the general action log, one on a dedicated secret-reveal channel — neither of which ever contains a value or a hash of one. Full behavior in Resource Views.

Insights

Everything except GET /insights is served without a connected cluster: history has to answer for clusters that are gone. GET /insights reads the live engine, so it needs the cluster. See Insights Engine.

MethodEndpointRoleLiveDescription
GET/insightsAnyyesActive insights for the cluster: severity (critical, warning, info), resolved, includeMuted. Returns items, total, hiddenByProfile, profile. history=true reads persisted records instead (status, since, until)
GET/insights/summaryAny—Per-cluster insight state for the fleet view
GET/insights/episodesAny—Episode history — status, severity, rule, cluster, since, until, limit, page
GET/insights/episodes/{id}Any—One episode with its transitions and recurrence
GET/insights/operational-episodesAny—Deterministically clustered bursts over a window
GET/insights/operational-episodes/{id}/episodesAny—The episodes inside one burst
GET/insights/shift-reportAny—“While you were away”, scoped to your presence anchor
POST/account/dashboard-seenAny—The presence beacon Home fires after rendering
GET/insights/mutesAny—List silences (cluster, since, until)
POST/insights/mutesEditor—Create a silence (audited)
DELETE/insights/mutes/{id}Editor—Lift a silence (audited)
GET/admin/insight-policiesAdmin—Per-rule policy layer (category)
PUT · DELETE/admin/insight-policies/{rule}Admin—Set or reset one rule’s policy (audited)

Security

The security surface is persisted by the sweep, so it also answers with no live connector — and it spans the whole fleet, so one dead cluster does not 503 the dashboard.

MethodEndpointRoleLiveDescription
GET/findingsAny—Vulnerability, misconfiguration and compliance findings. Scope: cluster, status; facets: source, kind, severity, resourceName, resourceNamespace, group; page, pageSize
GET/findings/workloadsAny—The same findings aggregated workload-first
GET/findings/{fingerprint}Any—One finding, including for a cluster that no longer exists (live: false)
GET/runtime-eventsAny—Falco runtime events, newest first (since=24h or RFC 3339, limit, cluster, source, priority)
POST/ingest/falcoPublic—Falco webhook ingest, cluster-scoped ingest-token auth inside the handler — see Falco

Metrics & network

MethodEndpointRoleLiveDescription
GET/metrics/queryAny—PromQL instant query (query, time) against the metrics store, pinned to the selected cluster. scope=fleet widens it to every cluster you may read
GET/metrics/query_rangeAny—PromQL range query (query, start, end, step), same scoping
GET/metrics/{type}/{ns}/{name}AnyyesCurrent CPU and memory of a pod (type = pods) or node (nodes) from Metrics Server. History is in /metrics/query_range
GET/flows/edgesAny—Network flow edges from Hubble, when the agent ships flows (namespace, window)
GET/deploysAnyyesRollouts detected in a window (windowMinutes)
GET/right-sizingAnyyesRight-sizing recommendations for the cluster’s workloads — the ones the Capacity and Cost screens show
POST/prom/writePublic—Prometheus remote-write ingest. Off unless KUBEBOLT_REMOTE_WRITE_ENABLED=true; bearer ingest token per KUBEBOLT_REMOTE_WRITE_AUTH_MODE (default disabled) — see Metrics

Port-forward

MethodEndpointRoleLiveDescription
POST/portforwardEditoryesOpen a forward — body fields namespace, pod, container (optional), remotePort
GET/portforwardAnyyesList active forwards
DELETE/portforward/{id}EditoryesStop a forward
ANY/pf/{id}/*——HTTP reverse proxy into the forwarded port — mounted at the root, not under /api/v1. Authorized by the kb_pf cookie set when the forward was opened

POST /portforward binds a real TCP listener on the backend host through client-go, capped at 20 concurrent forwards. What the browser can reach is the HTTP reverse proxy at /pf/{id}/, which is the surface the dashboard uses; a raw TCP client (psql, mysql) would have to reach the backend’s own network. See Remote Clusters for the tunnelled case and its limitations.

Helm

MethodEndpointRoleLiveDescription
GET/helm/releasesAnyyesAll releases in the cluster
GET/helm/releases/{ns}/{name}AnyyesRelease detail (values, manifest, history, dependencies), with values and manifest redacted the way the YAML view is — see Helm

Kobi and MCP

MethodEndpointRoleLiveDescription
POST/mcpAny—MCP server — Kobi’s read-only tools over Streamable HTTP, for API keys. Works with the cluster down; a tool call then reports it
POST/copilot/chatAny—Kobi chat as a Server-Sent Events stream — the UI’s chat. Answers even with no cluster connected
POST/copilot/compactAny—Summarize a long conversation
GET/copilot/conversationsAny—Your conversations (q, cluster, archived, limit)
GET · PATCH · DELETE/copilot/conversations/{id}Any—Read, rename or archive, delete one of your conversations
GET/copilot/conversations/{id}/feedbackAny—Your ratings in a conversation
POST/copilot/feedbackAny—Rate one of Kobi’s answers (up, down, or empty to withdraw)

Account

MethodEndpointRoleLiveDescription
GET/account/planAny—Your organization, its plan and limits
GET/account/usageAny—Metered usage (empty in the open-source edition)
GET/account/capabilitiesAny—Capability states behind the truncation banner (the active-series cap)

Integrations and agents

MethodEndpointRoleLiveDescription
GET/integrations · /integrations/{id}Any—Detected integrations (OpenCost, Hubble, …); metadata only when no cluster is connected, so the catalog still renders
POST/integrations/{id}/installAdminyesInstall via the wizard (audited)
GET · PUT/integrations/{id}/configAdminyesIntegration configuration
DELETE/integrations/{id}AdminyesUninstall
GET/integrations/agent/install-defaultsAdmin—Values the Add cluster wizard bakes into the helm command
GET/integrations/agent/auth-infoAdmin—Which channel auth mode the backend expects
POST/integrations/agent/issue-tokenAdmin—Mint an ingest token for a new cluster
GET/admin/agentsAdmin—Agents connected right now

Auth, users and teams

MethodEndpointRoleLiveDescription
POST/auth/logoutAny—Revoke the refresh token and clear the cookie
GET/auth/meAny—Current user
PUT/auth/me/passwordAny—{"currentPassword": "…", "newPassword": "…"} (at least 8 characters); revokes your other sessions
GET · POST/usersAdmin—List users; create one — body fields username, email, name, password, role
GET · PUT · DELETE/users/{id}Admin—Read, update (username, email, name, role), delete
PUT/users/{id}/passwordAdmin—{"password": "…"}; revokes that user’s sessions
GET/teams · /teams/{id}Any—Teams. The open-source edition has a single default team; POST /teams answers 409 requires_ee
GET/teams/{id}/membersAdmin—A team’s members

Administration

MethodEndpointRoleLiveDescription
GET · POST/admin/api-tokensAdmin—List and create API tokens. No API token can call these
DELETE/admin/api-tokens/{id}Admin—Revoke a token
PATCH/admin/api-tokens/{id}/clustersAdmin—Replace an API key’s cluster list — {"clusters": ["<cluster id>"]}
GET · POST · PUT · DELETE/admin/tenants[/{id}], /admin/tenants/{id}/tokens[/{tokenID}], POST …/tokens/{tokenID}/rotate, /admin/tenants/{id}/limitsAdmin—Agent (ingest) tokens and per-tenant remote-write limits — the Agent Tokens tab
GET/admin/actionsAdmin—The audit trail, newest first — class=mutation|access|all, limit (default 100, max 1000). There is no audit page in the UI; see Audit trail
GET · PUT, POST …/reset/admin/settings/{copilot,notifications,auth,general,ingest-channel}Admin—UI-editable settings that override the environment (audited)
GET · PUT/admin/settings/blocked-operationsAdmin—Cloud connector operations no call may run — {"connectors": {"aws": ["s3.getobject"]}}; see Cloud connectors. Audited
GET/admin/settings/booted-withAdmin—The KUBEBOLT_* environment the API booted with, secrets redacted
GET · POST/admin/setup/status · /admin/setup/completeAdmin—First-login Setup Wizard state
POST/admin/system/restartAdmin—Exit cleanly so Kubernetes restarts the API with saved settings applied (202)
GET/admin/copilot/usage/{summary,timeseries,sessions}Admin—Kobi usage analytics
GET/admin/metrics/query · /admin/metrics/query_rangeAdmin—PromQL over the install’s own ingest metrics, not pinned to a cluster
GET · PUT · DELETE, POST …/test/admin/mcp-connectors[/{id}]Admin—Cloud connectors for Kobi. 404 when the feature is off
GET · POST/notifications/config · /notifications/test/{channel}Admin—Notification channel status and a test send

On KubeBolt Cloud, /admin/settings/auth, /admin/settings/ingest-channel, /admin/setup and /admin/system are run by KubeBolt and answer 404 to organization Admins.

Cloud only

KubeBolt Cloud adds organization and team management. The routes a script is likely to need:

MethodEndpointRoleDescription
GET/auth/me/teamsAnyYour teams and your role in each
POST/teamsAdminCreate a team
PUT · DELETE/teams/{id}Admin (rename: also the team’s admin)Rename or delete a team
POST · DELETE/teams/{id}/members[/{userId}]Admin or the team’s adminAdd a member (body fields userId, optional role) or remove one
PUT/clusters/{clusterId}/teamAdminAssign a cluster to a team — {"teamId": "…"}, empty to unassign
PUT/clusters/{clusterId}/environmentAdmin{"environment": "production"} — production, staging, testing, development, or empty
GET · PUT/account/notificationsAnyYour own notification opt-out

Real-time

MethodEndpointDescription
WS/api/v1/wsChange notifications — see WebSocket Events
WS/ws/exec/{ns}/{name}Pod terminal (Editor) — mounted at the root, not under /api/v1; see WebSocket Events