freeQoS API guide

Overview

freeQoS exposes three APIs. They share the same keys and the same server.

Authentication

Create a key

In the interface, open the API tab, give the key a name (for example Billing) and a scope, then Create. The secret is shown once: copy it right away. A key can be disabled or revoked from the same tab.

For safety, a key can never manage keys, user accounts or passwords: those stay in the interface, behind a person's login.

Send the key

Three equivalent forms are accepted on every API. Use the one your tool supports.

# 1. Bearer token (recommended)
curl -H 'Authorization: Bearer <key>' <your-freeqos-url>/api/v1/plans

# 2. X-API-Key header
curl -H 'X-API-Key: <key>' <your-freeqos-url>/api/v1/plans

# 3. HTTP Basic, the key as user name and an empty password (Preseem form)
curl -u '<key>:' <your-freeqos-url>/model/v1

Check a key in one call: GET /model/v1 returns the collections, the key prefix and its scopes.

Conventions

• JSON in and out. Send Content-Type: application/json with a body.
• Units. /api/v1 takes rates in Mbit/s (down_mbps, up_mbps); some endpoints also accept _kbps and _gbps variants. /model/v1 takes kbit/s (down_speed, up_speed), like Preseem. /usage/v1 returns bytes. Down is toward the client, up from the client.
• Times are ISO 8601 in UTC (2026-10-07T08:00:00Z).
• Identifiers. A PPPoE client is identified by its login; a static-IP client by the reference you gave it; a model record by the id you choose in the URL.
• Idempotence. PUT creates or replaces: replaying your whole inventory is harmless. The id in the URL is authoritative.
• Immediate effect. Plan and limit changes are written to the router in the same call; the response says what was actually written (see enforcement report).

Quick start

From nothing to a throttled client in five calls. Replace <key> with a read + write key.

1. Check the key.

   curl -H 'Authorization: Bearer <key>' <your-freeqos-url>/model/v1

2. Add a router. freeQoS connects to it and sets it up by itself.

   curl -X POST <your-freeqos-url>/api/v1/pops/routers \
     -H 'Authorization: Bearer <key>' -H 'Content-Type: application/json' \
     -d '{"name":"nas-north","host":"10.0.0.2","username":"freeqos",
          "password":"<router password>","role":"pop","pop_name":"North"}'

3. Wait for the setup (usually under a minute): finished_at is set when done.

   curl -H 'Authorization: Bearer <key>' <your-freeqos-url>/api/v1/pops/provisioning/nas-north

4. Find the clients freeQoS discovered on it (PPPoE sessions, VLAN clients):

   curl -H 'Authorization: Bearer <key>' <your-freeqos-url>/api/v1/plans

5. Push a plan. The queue is written to the router at once.

   curl -X PUT <your-freeqos-url>/api/v1/plans/john.doe \
     -H 'Authorization: Bearer <key>' -H 'Content-Type: application/json' \
     -d '{"down_mbps":100,"up_mbps":20}'

Add a router

POST/api/v1/pops/routers

Saves a MikroTik router (RouterOS API, port 8728, or 8729 with TLS). Right after, freeQoS runs its automatic setup: CAKE queue types, NetFlow export toward freeQoS, discovery of its clients and links. Nothing else has to be configured by hand.

Writing reaches a router only when the global switch is on (GET /api/v1/shaping/enforcement), its write_enabled is true, and its RouterOS account has the write policy.

Related calls

Client plans

The plan is the rate sold to a client. It is the normal way to throttle: freeQoS writes a CAKE queue for the client on the router that carries it.

GET/api/v1/plans

Every known client (detected on a router or declared), its plan and where the plan comes from (api, ui, default). Use it to find the logins to push plans for. pending lists the plans received for logins never seen connected yet.

PUT/api/v1/plans/{login}

curl -X PUT <your-freeqos-url>/api/v1/plans/john.doe \
  -H 'Authorization: Bearer <key>' -H 'Content-Type: application/json' \
  -d '{"down_mbps":100,"up_mbps":20}'

• The client does not need to have connected yet. Your management interface (the one that feeds your RADIUS) can push the plan as soon as it creates the subscriber, and an initial sync can push every subscriber, online or not. The plan of a login never seen connected is kept, answered with "pending": true and the state en-attente-de-connexion, and applied by itself at the subscriber's first PPPoE session (at the latest at the next reconciliation pass, 2 minutes by default). Use the PPPoE login, which is the RADIUS username. A login with leading or trailing spaces or control characters is refused (422). When plans are read from RADIUS (PLAN_PROVIDER=freeradius_sql), a new subscriber's plan comes from RADIUS at its first connection: a pending plan is then refused (409) rather than silently ignored.
• Setting a plan lifts a forced limit on that client: the plan becomes the rule.

Enforcement report. The response returns the client record and an enforcement object telling what really happened on the router:

DELETE/api/v1/plans/{login}

Removes the plan: the client's queue is removed and it is no longer throttled (it stays observed). For a login still waiting for its first connection, the pending plan is simply forgotten. A login with neither a session nor a plan returns 404.

POST/api/v1/plans/refresh

Re-reads every plan and re-writes the queues right away, instead of waiting for the next cycle.

Forced limits and boosts

Force a limit

PUT/api/v1/shaping/policies

A forced limit takes precedence over the plan: suspension for unpaid bills, fair-use cap, or a cap on a link (a radio backhaul, a whole sector).

curl -X PUT <your-freeqos-url>/api/v1/shaping/policies \
  -H 'Authorization: Bearer <key>' -H 'Content-Type: application/json' \
  -d '{"scope":"subscriber","target_key":"john.doe","max_down_mbps":5,"max_up_mbps":1,
       "note":"unpaid invoice"}'

Lift it with DELETE /api/v1/shaping/policies/{scope}/{target_key}; the client goes back to its plan. GET /api/v1/shaping/policies lists the limits in force.

Temporary boost

POST/api/v1/shaping/boosts

Raises a client's rate for a limited time; it expires by itself.

curl -X POST <your-freeqos-url>/api/v1/shaping/boosts \
  -H 'Authorization: Bearer <key>' -H 'Content-Type: application/json' \
  -d '{"login":"john.doe","duration_minutes":60,"multiplier":2,"reason":"speed test"}'

Give either multiplier or absolute rates (down_mbps, up_mbps). GET /api/v1/shaping/boosts lists the running boosts; DELETE /api/v1/shaping/boosts/{login} ends one early.

Static-IP clients

A client without a PPPoE session (business line, VLAN, fixed IP or subnet) is declared with its address. freeQoS finds the router that serves the address and shapes it like any other client.

POST/api/v1/static-clients

curl -X POST <your-freeqos-url>/api/v1/static-clients \
  -H 'Authorization: Bearer <key>' -H 'Content-Type: application/json' \
  -d '{"reference":"acme-hq","pop_name":"North","address":"203.0.113.16/29",
       "label":"ACME head office","vlan":2060,"plan_down_mbps":50,"plan_up_mbps":50}'

Edit with PATCH /api/v1/static-clients/{client_id}, remove with DELETE. GET /api/v1/static-clients/enforcement tells, for each declared client, whether its queue is in place and what is missing.

Billing integration (Preseem-compatible)

The model API receives your commercial inventory. It follows the Preseem model API: a billing system that already pushes to Preseem (Splynx, UISP/UCRM, Powercode, in-house scripts) only changes the base URL and the key.

Push a service

curl -u '<key>:' -X PUT <your-freeqos-url>/model/v1/services/svc-42 \
  -H 'Content-Type: application/json' \
  -d '{"id":"svc-42","account":"cust-7","package":"fibre-100",
       "down_speed":100000,"up_speed":20000,
       "attachments":[{"cpe_mac":"00:10:0b:6e:4c:ff","network_prefixes":["10.20.0.10"]}]}'

• Rates of the service, in kbit/s, take precedence over those of its package. Without rates, the package's apply.
• Address. network_prefixes places the service on the router that serves that address. A service with only a cpe_mac is accepted and kept aside; it becomes a client as soon as the MAC shows up on a router.
• Rules. A body whose id differs from the URL returns 400; a negative speed returns 400; a service id already used by a client entered by hand returns 409 (the API never takes over a human decision). Invalid JSON returns 400, as with Preseem.

Consumption (usage)

Bytes consumed by each service, measured from NetFlow (counted once, at a single point of the network). Answers "how much did this line use last month?".

curl -u '<key>:' '<your-freeqos-url>/usage/v1/services/svc-42?bucket=month&days=90'

Reading measurements

All read calls work with a read key.

A client's subscriber_id is returned by /api/v1/subscribers/latest and /api/v1/search.

Operations and diagnostics

Errors

Errors return a JSON body {"detail": "..."} with a readable message.

Every endpoint

Generated live from this server, so it always matches the version installed. Click an endpoint to see its parameters and body.