LibreQoS Node API

Requirements

Starting with LibreQoS 2.2, the lqos_api Node API follows the same mapped-circuit policy as base LibreQoS:

  • Networks with 1,000 or fewer valid mapped circuits can use the API without an Insight subscription.

  • Networks with more than 1,000 valid mapped circuits require a valid API or Insight entitlement.

  • The count is based on unique configured circuit mappings, not recent traffic. Multiple devices in one circuit count once, and rows without an IP mapping do not count.

  • A valid live license or locally cached signed grant can authorize API access above the free limit.

This is the same population used for the base shaping limit:

  • ShapedDevices.csv can contain unlimited entries.

  • Without a valid entitled license/grant, LibreQoS admits only the first 1,000 valid mapped circuits into active shaping state.

  • Higher mapped-circuit counts depend on an entitled API or Insight license.

API-only access is available through the Try Insight link in the WebUI at half the price of full Insight.

Source of Truth and Testing

Use Swagger on your node as the complete reference and test surface for your installed build:

  • Direct local API port: http://<node-ip>:9122/api-docs

  • If optional HTTPS with Caddy is enabled for the WebUI: https://<hostname-or-node-ip>/api/v1/api-docs

On systems using managed Caddy HTTPS, leave the API listener on loopback and access it through /api/v1/. LQOS_API_LISTEN is an advanced override for deployments that intentionally expose the API listener directly; do not set it on managed Caddy systems unless direct API exposure, firewalling, TLS, and operator access controls have been planned together.

Use this page as a capability map. Use Swagger for full endpoint inventory, request/response schemas, and live testing.

Need definitions for persistence and runtime-impact terms? See the Glossary.

Install and Enable

If installed via .deb (recommended), lqos_api is included at:

  • /opt/libreqos/src/bin/lqos_api

Enable service:

sudo cp /opt/libreqos/src/bin/lqos_api.service.example /etc/systemd/system/lqos_api.service
sudo systemctl daemon-reload
sudo systemctl enable lqos_api
sudo systemctl start lqos_api

The shipped lqos_api.service.example waits for network-online.target, so the API does not start before DNS and the default route are ready.

Update only the API binary:

cd /opt/libreqos/src
./update_api.sh

Verify service state:

sudo systemctl status lqos_api

Authentication

Most endpoints require:

  • Header: x-bearer

  • Value: a named local API key from License & Services, the legacy local bearer token, or your Insight/API-only license key

Local API keys authenticate callers; they do not bypass the mapped-circuit licensing limit. Administrators can create up to 16 named keys in License & Services. LibreQoS displays each generated key once, stores only its SHA-256 digest and non-secret metadata in /etc/lqos.conf, and cannot recover it later. Copy the complete lqos_api_... value into the client immediately and treat it like a password.

Named keys do not expire automatically. Revoke keys that are no longer needed; creation and revocation may take up to 30 seconds to reach lqos_api. Existing license keys and the older single local_api.bearer_token remain compatible. The UI labels the older value as Legacy local API key and lets an administrator remove it after clients have moved to named keys.

What ISPs Can Do with the API

1) Subscriber/Circuit Lifecycle

Provision, update, and remove subscriber/device records.

  • Add or replace:

    • POST /overrides/persistent_devices

    • POST /shaped_devices/update

  • Adjust speeds:

    • POST /overrides/adjustments/circuit_speed

    • POST /overrides/adjustments/device_speed

  • Remove:

    • DELETE /overrides/persistent_devices/by_circuit/{circuit_id}

    • DELETE /overrides/persistent_devices/by_device/{device_id}

    • POST /overrides/adjustments/remove_circuit

    • POST /overrides/adjustments/remove_device

2) Override and Policy Management

Maintain persistent override policies for circuits, devices, sites, and UISP-specific overrides.

  • GET/POST/DELETE /overrides/adjustments*

  • GET/POST/DELETE /overrides/network_adjustments*

  • GET/POST/DELETE /overrides/uisp/bandwidth*

  • GET/POST/DELETE /overrides/uisp/routes*

3) Topology and Shaping Input Files

Inspect and update shaping/topology files used by runtime workflows.

  • GET /network_json/json

  • GET /network_json/text

  • POST /network_json/update

  • POST /network_json/set_site_speed

  • POST /network_json/set_site_speed_batch

  • GET /shaped_devices

  • POST /shaped_devices/update

4) Monitoring and Diagnostics

Read health, scheduler, throughput, flow, queue, and circuit status.

Representative endpoints:

  • GET /health

  • GET /status_snapshot

  • GET /scheduler_status

  • GET /circuit/{circuit_id}

  • GET /search

  • GET /current_throughput

  • GET /queue_stats_total

  • GET /warnings

  • GET /urgent, GET /urgent/status

5) Control and Reload Operations

Trigger operational control actions when needed.

  • POST /reload_libreqos

  • POST /clear_hot_cache

Treat these as higher-risk actions in production.

Persistence Model (Important)

Not all writes persist the same way:

  • overrides/*: persistent policy state.

  • network_json/set_site_speed*: transient edits.

  • network_json/update and shaped_devices/update: direct file replacement, often integration-overwritable.

If integrations are enabled, integration refresh cycles may overwrite direct file edits.

Deployment Hardening

  • Keep API access limited to trusted management networks.

  • Do not expose the API directly to the public Internet.

  • If remote access is needed, use a reverse proxy with TLS and authentication.

  • Restrict inbound access with firewall allowlists.

If you want the WebUI and API docs on one HTTPS origin, see Optional HTTPS With Caddy.