Skip to content

REST API

MultiTuner exposes a REST API that provides programmatic access to all device functionality — channel status, signal measurements, alert history, streaming control, and system configuration. The same API is used internally by the web interface.

API version: 1.1.7
Base URL: http://{device_ip}/api

Authentication

The API uses Bearer token authentication (RFC 6750). All endpoints except POST /login and GET /system/alive require a valid token.

Obtaining a Token

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

{
  "role": "admin",
  "password": "admin",
  "keep_logged_in": false
}

Response:

{
  "role": "admin",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Using the Token

Include the token in the Authorization header of every subsequent request:

GET /api/status
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Roles

The API has two access levels:

Role Description
user Read access and basic control — monitoring, alert queries, stream toggling
admin Full access — all user operations plus configuration changes, password management, reboot, firmware upgrade, and factory reset

Endpoints that require admin are marked throughout this reference. Calling them with a user token returns 401 Unauthorized.

Token validity

Setting keep_logged_in: true issues a long-lived token. Tokens are validated on every request. Changing a role's password via POST /conf/password does not immediately invalidate existing tokens for that role — previously issued tokens remain valid until they expire.

Common Response Codes

Code Meaning
200 Success — response body contains the requested data or is empty
401 Unauthorized — token is missing, invalid, or the role lacks permission
503 Temporarily unavailable — retry after a short delay (used during band scan and tuner switching)
default Unexpected error — body contains an Error object

Error Object

All error responses return a JSON object with the following structure:

{
  "code": 42,
  "message": "tuner is busy"
}

Conventions

  • All request and response bodies are JSON unless otherwise noted
  • Tuner IDs are zero-based integers (0 = first tuner, 1 = second tuner, etc.)
  • Frequencies are expressed in kHz as integers (e.g. 104300 = 104.3 MHz)
  • Timestamps use ISO 8601 / RFC 3339 format where applicable
  • Unix timestamps (seconds since epoch) are used in query parameters
  • Setting a threshold value to 0 disables that alert (for RSSI and SNR); for multipath, use 100 to disable