LibreQoS Node API

Requirements

The lqos_api (Node API service) requires an active LibreQoS Insight subscription.

This is separate from base shaping limits:

  • ShapedDevices.csv can contain unlimited entries.

  • Without a valid Insight subscription/license, LibreQoS admits only the first 1000 valid mapped circuits into active shaping state.

  • Higher mapped-circuit counts depend on active Insight licensing.

Source of Truth and Testing

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

  • http://<node-ip>:9122/api-docs

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: your Insight license key

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.