REST API

OmniBus exposes an HTTP API for synchronous control and automation. Everything the UI does goes through it.

Authentication

All /api/* routes (and the /ws WebSocket upgrade) require an Authorization: Bearer <token> header. Obtain a token by logging in:

POST /api/login
Content-Type: application/json

{ "username": "admin", "password": "<password>" }

The response contains a token. Tokens have a 12-hour sliding TTL and are held in memory only (cleared on restart). When there's exactly one user, the legacy { "password": "..." } body (no username) still works.

:::note Roles apply to the API too Read endpoints require any authenticated user. Mutating endpoints (POST/PUT/DELETE/PATCH) require an admin token. See Users & Roles. :::

Per-protocol control endpoints

:path is the URL-encoded device path (e.g. %2Fdev%2FttyUSB0).

Protocol	Endpoint	Body
raw	POST /api/ports/:path/rest/tx	{"data":"<base64>"} or {"hex":"01 02 03"}
modbus-rtu	POST /api/ports/:path/rest/request	{"unitId":1,"fc":3,"address":0,"quantity":10} — returns the parsed response, or 504 on bus timeout
bacnet-mstp	POST /api/ports/:path/rest/send	{"frameType":"BACNET_DATA_EXPECTING_REPLY","destination":5,"source":1,"dataHex":"01020304"} or {"frameHex":"55ff..."}

Other adapters expose their own actions (e.g. M-Bus read/init/scan, DNP3 outstation set-point/set-iin, Jandy equipment). See each protocol page.

Useful system endpoints

Endpoint	Auth	Purpose
GET /api/status	none	Liveness + whether an admin is configured.
GET /api/me	token	The current user (for role-aware tooling).
GET /api/system	token	System info + product/branding strings.
GET /api/system/ca-cert	none	Download the internal Root CA (public credential).
GET /api/templates/modbus	token	Available Modbus starter templates.
GET/POST/PUT/DELETE /api/ports/:path/webhooks	admin	Manage webhooks.

Example

TOKEN=$(curl -s -X POST http://omnibus.local/api/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"secret"}' | jq -r .token)

curl -s -X POST "http://omnibus.local/api/ports/%2Fdev%2FttyUSB0/rest/request" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"unitId":1,"fc":3,"address":0,"quantity":10}'