Plans API

A plan is a named download/upload speed in Mbit/s. Clients and services refer to a plan by name; the router shapes their traffic to it, and every registered OLT keeps matching profiles and rate tables for it (see the OLT API).

Base URL, authentication (X-API-Key), error format and the action API are described in the API overview.

When a plan is created, changed or deleted, the router brings every registered OLT’s profiles in step in the background (one OLT at a time, the same work as POST /olt/sync). The answer does not wait for it; its olt field says how many OLTs are being updated, or is null when no OLT is registered.

Reading

GET /plans

Lists the plans, each with how many clients use it. Any method other than POST and DELETE on /plans answers the same list.

curl -H "X-API-Key: YOUR_API_KEY" "http://ROUTER-IP:8880/plans"

{
  "count": 2,
  "plans": [
    {
      "name": "plan_100_50",
      "down_mbps": 100,
      "up_mbps": 50,
      "comment": "Home 100",
      "created": "2026-09-01 10:00:00",
      "clients": 12
    },
    {
      "name": "plan_300_150",
      "down_mbps": 300,
      "up_mbps": 150,
      "comment": "",
      "created": "2026-09-01 10:05:00",
      "clients": 0
    }
  ]
}

The clients count covers the MAC-based clients only.

Changing

POST /plans

Changes the router

Creates a plan, or updates the rates and comment of an existing plan of the same name; the OLTs follow in the background.

Creates a new plan (201). If a plan with that name already exists, its down_mbps, up_mbps and comment are replaced (200) and every shaped client is reshaped to the new rates at once.

Name	In	Type	Notes
name	body	string	Required. Letters, digits, _ and -, 1–40 characters.
down_mbps	body	integer	Required. 1–100000.
up_mbps	body	integer	Required. 1–100000.
comment	body	string	Optional free text.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "plan_100_50", "down_mbps": 100, "up_mbps": 50, "comment": "Home 100"}' \
  "http://ROUTER-IP:8880/plans"

{
  "ok": true,
  "code": 201,
  "message": "Plan created",
  "plan": {
    "name": "plan_100_50",
    "down_mbps": 100,
    "up_mbps": 50,
    "comment": "Home 100",
    "created": "2026-09-28 12:00:00"
  },
  "olt": "profiles are being created on 1 OLT(s) in the background"
}

An update answers "code": 200, "message": "Plan updated" and "olt": "profiles are being updated on …". Errors: 400 for an invalid name or rates out of range.

DELETE /plans/{name}

Changes the router

Deletes a plan; its profiles on the OLTs are removed in the background unless an ONT still uses them.

Refused with 409 while any client still uses the plan. The name may also be given in the body as name (then DELETE /plans works too).

Name	In	Type	Notes
name	path	string	The plan to delete.
name	body	string	Alternative to the path; takes precedence when present.

curl -X DELETE -H "X-API-Key: YOUR_API_KEY" "http://ROUTER-IP:8880/plans/plan_300_150"

{
  "ok": true,
  "code": 200,
  "message": "Plan deleted",
  "olt": "profiles are being removed on 1 OLT(s) in the background"
}

Errors: 404 when no plan has that name; 409 when clients use it:

{
  "ok": false,
  "code": 409,
  "error": "Plan 'plan_100_50' is used by 12 client(s); reassign them first",
  "clients": ["AA:BB:CC:DD:EE:FF", "..."]
}

To give a client a plan, use POST /plan in the Clients API; to change a service’s plan, use the Services API.

Action API equivalents

Action	Query parameters	Same as
action=plan-list	—	GET /plans
action=plan-add	name, down_mbps, up_mbps, comment	POST /plans
action=plan-del	name	DELETE /plans/{name}