Documentation › API Reference

API Reference

BunkerM exposes a set of internal REST APIs for broker management, monitoring, and configuration. All APIs require an X-API-Key header. The frontend communicates with them server-side so the API key is never exposed to the browser.

API key security: All requests to backend services must include the X-API-Key header matching the API_KEY environment variable set at container startup. Direct API access from outside the container should go through the Next.js proxy layer on port 2000.

Service Overview

  • dynsec-api (port 1000) - MQTT client, role, group, and ACL management
  • monitor-api (port 1001) - broker statistics via $SYS topics
  • clientlogs-api (port 1002) - real-time connection event tracking
  • config-api (port 1005) - Mosquitto config and DynSec JSON management
  • smart-anomaly-api (port 8100) - anomaly detection, alerts, metrics

All services run inside the container. From outside, access them via Nginx on port 2000 at their path prefixes.

dynsec-api - Client & ACL Management

Manages Mosquitto's dynamic security: clients, roles, groups, and ACL rules.

  • GET /dynsec/clients - list all MQTT clients
  • POST /dynsec/clients - create a client
  • GET /dynsec/clients/{id} - get a client by ID
  • PUT /dynsec/clients/{id} - update a client
  • DELETE /dynsec/clients/{id} - delete a client
  • POST /dynsec/clients/{id}/enable - enable a client
  • POST /dynsec/clients/{id}/disable - disable a client
  • GET /dynsec/roles - list all roles
  • POST /dynsec/roles - create a role
  • GET /dynsec/groups - list all groups
  • POST /dynsec/groups - create a group
  • POST /dynsec/clients/{id}/roles - assign a role to a client
  • POST /dynsec/groups/{id}/clients - add a client to a group

monitor-api - Broker Statistics

Reads broker metrics from Mosquitto's $SYS topics.

  • GET /monitor/stats - current broker statistics (connected clients, message rates, uptime)
  • GET /monitor/clients - currently connected client list
  • GET /monitor/history - time-series metric history

clientlogs-api - Connection Events

Tracks per-client connection, disconnection, subscribe, and publish events.

  • GET /clientlogs - list recent events (filter by client, event type, time range)
  • GET /clientlogs/{client_id} - events for a specific client

config-api - Broker Configuration

Manages Mosquitto configuration file and the dynamic security JSON.

  • GET /config/broker - get current broker configuration
  • PUT /config/broker - update broker configuration
  • POST /config/restart - trigger a broker restart
  • GET /config/dynsec - download dynamic security JSON
  • PUT /config/dynsec - replace dynamic security JSON

smart-anomaly-api - Anomaly Detection

The smart anomaly detection service.

  • GET /ai/alerts - list anomaly alerts
  • POST /ai/alerts/{id}/acknowledge - acknowledge an alert
  • GET /ai/anomalies - list detected anomalies
  • GET /ai/metrics - per-topic metrics used for anomaly detection
  • GET /ai/entities - tracked topic entities

Authentication

All endpoints require the X-API-Key header:

curl -H "X-API-Key: your-api-key" \
  http://localhost:2000/api/dynsec/clients

The API key is set via the API_KEY environment variable. You can view and regenerate it from Settings > Broker in the web UI.

Full API Documentation

The complete interactive API documentation (OpenAPI / Swagger UI) is available on GitHub:

View full API docs on GitHub
← TLS & SSL Community →