LibreQoS/docs/v2.0/api.md

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.

Recommended Production Workflow

1. Validate endpoint behavior and payload schema in Swagger.
2. Apply the smallest change needed.
3. Verify result with read-only checks (/health, /scheduler_status, circuit/throughput views).
4. Keep rollback snapshots for config/data-changing operations.

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.