Skip to content
IndraMQTT

API reference

API reference

The complete MQTT platform in one small binary: broker, SQL rules, data connectors and multi-tenancy in a single process.

Read and change broker state through HTTPS. Use it when a client or a script must operate the broker. You get JSON rows.

flowchart LR
    Op["operator"] -- "HTTPS plus INDRA_API_KEY" --> API["management API"]
    API -- "GET /api/v1/clients" --> S["sessions"]
    API -- "POST /api/v1/rules" --> R["rule engine"]
    API -- "POST /api/v1/auth/users" --> U["users"]
    API -- "GET /api/v1/metrics" --> M["router"]

Before you start

  • Start the broker from First start.
  • Set INDRA_API_KEY to an operator key. The examples read it.
  • Each page documents one tag of the served OpenAPI document. The drift test fails when a page differs from the served document.

Note: Calls except /healthz need an operator API key. Pass it as Authorization: Bearer $INDRA_API_KEY. /healthz answers OK with no key.

The pages document the served document. The served document lists the native routes of the router.

The served document lists http://localhost:8081 as its server URL. The kernel binds 127.0.0.1:18083 by default. The examples use the kernel default.

Tags

Check that it works

Start the broker with this file. The health endpoint returns OK.

[node]
id = "doc-ref"


[listeners.tcp]
bind = "0.0.0.0:1883"


[listeners.tls]
bind = "0.0.0.0:8883"


[listeners.ws]
bind = "0.0.0.0:8083"


[listeners.wss]
bind = "0.0.0.0:8084"


[listeners.api]
bind = "0.0.0.0:18083"


[logging]
level = "warn"
Terminal window
python3 - <<'PY'
import os, socket
port = int(os.environ.get("API_PORT", "18083"))
sock = socket.create_connection(("127.0.0.1", port), timeout=5)
sock.sendall(b"GET /healthz HTTP/1.0\r\nHost: docs\r\n\r\n")
print(sock.makefile().read().strip().splitlines()[-1])
PY
OK

Check one documented call. GET /api/v1/nodes answers 200 with its rows. It prints OK.

Terminal window
python3 - <<'PY'
import os, urllib.request
port = os.environ.get("API_PORT", "18083")
key = os.environ.get("API_KEY", "")
base = f"http://127.0.0.1:{port}"
req = urllib.request.Request(base + "/api/v1/nodes", method="GET")
req.add_header("Authorization", f"Bearer {key}")
with urllib.request.urlopen(req, timeout=5) as r:
    body = r.read().decode()
    assert r.status == 200, body
assert "running" in body or "node_id" in body, body
print("OK")
PY
OK

Next steps