API Endpoints

Complete REST API endpoint reference. All paths are relative to https://<bng-host>:8443.

All authenticated endpoints require Authorization: Bearer <token> header. Admin-only endpoints require a user with the admin role.

Subscribers

List Subscribers

GET /api/v1/subscribers
GET /api/v1/subscribers?type=pppoe
GET /api/v1/subscribers?type=dhcp

Query Parameters:

Name	Type	Description
`type`	string	Filter by session type: `pppoe` or `dhcp` (optional)

Example:

curl -sk -H "Authorization: Bearer $TOKEN" \
  'https://localhost:8443/api/v1/subscribers?type=pppoe'

Response:

{
  "status": "ok",
  "data": {
    "sessions": [
      {
        "id": 1,
        "type": "PPPoE",
        "username": "user1@isp",
        "ip_address": "203.0.113.10",
        "interface": "ppp0",
        "rate_down": 100000000,
        "rate_up": 40000000,
        "state": "active",
        "started_at": 1710410400
      }
    ],
    "count": 1
  }
}

Subscriber Summary

GET /api/v1/subscribers/summary

Example:

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/subscribers/summary

Response:

{
  "status": "ok",
  "data": {
    "total": 150,
    "pppoe": 120,
    "dhcp": 30
  }
}

Get Subscriber Detail

GET /api/v1/subscribers/{id}

Example:

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/subscribers/1

Response:

{
  "status": "ok",
  "data": {
    "id": 1,
    "session_type": "PPPoE",
    "state": "active",
    "username": "user1@isp",
    "mac_address": "00:11:22:33:44:55",
    "ip_address": "203.0.113.10",
    "gateway": null,
    "access_interface": "trunk0.200.20",
    "ppp_interface": "ppp0",
    "rate_down_bps": 100000000,
    "rate_up_bps": 40000000,
    "overhead_profile": "pppoe_ethernet",
    "vrf_steered": false,
    "acct_session_id": "abng-1710410400-1",
    "started_at": 1710410400,
    "bytes_in": 1234567890,
    "bytes_out": 987654321,
    "packets_in": 1000000,
    "packets_out": 800000
  }
}

Errors: 404 if session ID does not exist.

Disconnect Subscriber

DELETE /api/v1/subscribers/{id}

Example:

curl -sk -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/subscribers/1

Response:

{
  "status": "ok",
  "data": {
    "message": "session 1 disconnected"
  }
}

Disconnect by Interface

POST /api/v1/subscribers/disconnect-by-interface

Disconnects all sessions on a given access interface.

Example:

curl -sk -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"interface": "trunk0.200.20"}' \
  https://localhost:8443/api/v1/subscribers/disconnect-by-interface

Request Body:

{
  "interface": "trunk0.200.20"
}

Response:

{
  "status": "ok",
  "data": {
    "message": "2 session(s) disconnected on trunk0.200.20"
  }
}

Change Subscriber Rate

PUT /api/v1/subscribers/{id}/rate

Updates CAKE QoS qdiscs on both egress and IFB ingress devices.

Example:

curl -sk -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rate_down": "50mbit", "rate_up": "20mbit"}' \
  https://localhost:8443/api/v1/subscribers/1/rate

Request Body:

{
  "rate_down": "50mbit",
  "rate_up": "20mbit"
}

Response:

{
  "status": "ok",
  "data": {
    "message": "rate change requested for session 1",
    "rate_down": "50mbit",
    "rate_up": "20mbit"
  }
}

Errors: 404 if session ID does not exist.

System

Version

GET /api/v1/system/version

Example:

curl -sk https://localhost:8443/api/v1/system/version

Response:

{
  "status": "ok",
  "data": {
    "product": "AthenaBNG",
    "version": "0.1.0",
    "component": "abngd"
  }
}

Health

GET /api/v1/system/health

Example:

curl -sk https://localhost:8443/api/v1/system/health

Response:

{
  "status": "ok",
  "data": {
    "uptime_seconds": 86400,
    "active_sessions": 150,
    "product": "AthenaBNG",
    "version": "0.1.0"
  }
}

Get Running Configuration

GET /api/v1/system/config

Returns the running config with sensitive fields (secrets, passwords) redacted.

Example:

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/system/config | jq '.data.cgnat'

Response:

{
  "status": "ok",
  "data": {
    "system": { "hostname": "bng1" },
    "interfaces": { "trunks": ["eth0"] },
    "radius": { "secret": "********" },
    "cgnat": {
      "enabled": true,
      "vrf_name": "cgnat",
      "vrf_table": 100,
      "handoff_interface": "eth3",
      "handoff_gateway": "10.99.0.1",
      "source_range": "100.64.0.0/10"
    }
  }
}

Configuration Management

All config management endpoints require admin role.

The workflow mirrors the CLI: stage changes in a candidate config, then commit.

Set Config Value

POST /api/v1/system/config/set

Example:

curl -sk -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "qos.default_down", "value": "200mbit"}' \
  https://localhost:8443/api/v1/system/config/set

Request Body:

{
  "path": "qos.default_down",
  "value": "200mbit"
}

Response:

{
  "status": "ok",
  "data": null
}

Delete Config Key

POST /api/v1/system/config/delete

Example:

curl -sk -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "cgnat.enabled"}' \
  https://localhost:8443/api/v1/system/config/delete

Request Body:

{
  "path": "cgnat.enabled"
}

Commit

POST /api/v1/system/config/commit

Validates candidate config, renders service templates, archives running config, and atomically replaces it.

Example:

curl -sk -X POST -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/system/config/commit

Rollback

POST /api/v1/system/config/rollback

Loads archived config revision as the candidate. Revision 1 is the most recent. You must still call commit to apply it.

Example:

curl -sk -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"revision": 1}' \
  https://localhost:8443/api/v1/system/config/rollback

Request Body:

{
  "revision": 1
}

Discard

POST /api/v1/system/config/discard

Discards the candidate config, reverting to running.

Example:

curl -sk -X POST -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/system/config/discard

Compare

GET /api/v1/system/config/compare

Example:

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/system/config/compare

Response:

{
  "status": "ok",
  "data": {
    "diff": "- qos:\n-   default_down: 100mbit\n+ qos:\n+   default_down: 200mbit"
  }
}

Interfaces

List All Interfaces

GET /api/v1/interfaces

Returns all network interfaces on the system (trunk, loopback, VLAN, ppp, IFB).

Example:

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/interfaces

List VLAN Interfaces

GET /api/v1/interfaces/vlans

Returns only dynamic VLAN sub-interfaces created by abng-demux.

Example:

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/interfaces/vlans

QoS

List QoS Sessions

GET /api/v1/qos

Returns per-session QoS state: shaped interface, rates, overhead profile, IFB device.

Example:

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/qos

List Overhead Profiles

GET /api/v1/qos/profiles

Example:

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/qos/profiles

Response:

{
  "status": "ok",
  "data": {
    "profiles": [
      { "name": "pppoe_ethernet", "overhead": 34, "mpu": 64, "description": "PPPoE over Ethernet" },
      { "name": "ipoe_qinq", "overhead": 30, "mpu": 64, "description": "IPoE over QinQ" }
    ]
  }
}

Routing

BGP Summary

GET /api/v1/routing/bgp/summary

Returns the FRRouting BGP neighbor summary (equivalent to show bgp summary json).

Example:

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/routing/bgp/summary

Kernel Routes

GET /api/v1/routing/routes

Returns the kernel routing table including subscriber /32 host routes.

Example:

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/routing/routes

CGNAT VRF Steering

VRF-Steered Sessions

GET /api/v1/cgnat/sessions

Returns only sessions assigned RFC 6598 shared-address (100.64.0.0/10) IPs that are being steered through the CGNAT VRF to an external CGNAT appliance.

Example:

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/cgnat/sessions

VRF Steering Statistics

GET /api/v1/cgnat/stats

Returns counts of sessions being VRF-steered to CGNAT appliance vs. public IP sessions.

Example:

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/cgnat/stats

Response:

{
  "status": "ok",
  "data": {
    "vrf_steered_sessions": 50,
    "public_ip_sessions": 100,
    "total_sessions": 150
  }
}

Demux

Demux Configuration

GET /api/v1/demux/config

Returns the demux section of the running config (trunk interfaces, VLAN profiles, rate limits).

Example:

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/demux/config

Demux State

GET /api/v1/demux/state

Returns the list of VLAN sub-interfaces currently managed by abng-demux.

Example:

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/demux/state

Events

Server-Sent Events Stream

GET /api/v1/events/subscribers

Opens a persistent SSE connection streaming subscriber session events in real-time.

Example:

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/events/subscribers

Event format:

event: session_up
data: {"id": 1, "type": "PPPoE", "username": "user1@isp", "ip_address": "203.0.113.10"}

event: session_down
data: {"id": 1, "username": "user1@isp", "reason": "user_request"}

Webhooks

List Webhooks

GET /api/v1/webhooks

Example:

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/webhooks

Register Webhook (admin)

POST /api/v1/webhooks

Example:

curl -sk -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/bng",
    "events": ["session.up", "session.down"]
  }' \
  https://localhost:8443/api/v1/webhooks

Request Body:

{
  "url": "https://your-server.com/webhooks/bng",
  "events": ["session.up", "session.down"]
}

Delete Webhook (admin)

DELETE /api/v1/webhooks/{id}

Example:

curl -sk -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/webhooks/a1b2c3d4

Prometheus Metrics

GET /metrics

No authentication required. Returns Prometheus text format metrics.

Example:

curl -sk https://localhost:8443/metrics

Response:

# HELP abng_active_sessions_total Total active subscriber sessions
# TYPE abng_active_sessions_total gauge
abng_active_sessions_total 150

# HELP abng_vrf_steered_sessions VRF-steered CGNAT sessions
# TYPE abng_vrf_steered_sessions gauge
abng_vrf_steered_sessions 50

# HELP abng_qos_sessions Sessions with CAKE QoS applied
# TYPE abng_qos_sessions gauge
abng_qos_sessions 145

Error Responses

Status	Meaning
`400`	Invalid request body or parameters
`401`	Missing or invalid JWT token
`403`	Insufficient role (admin required)
`404`	Resource not found (e.g. session ID)
`500`	Internal error (abngd communication failure)

All errors return the standard envelope:

{
  "status": "error",
  "message": "description of the error"
}

Next Steps

Authentication — JWT token details and user management
Webhooks — Webhook event types and delivery

Subscribers​

List Subscribers​

Subscriber Summary​

Get Subscriber Detail​

Disconnect Subscriber​

Disconnect by Interface​

Change Subscriber Rate​

System​

Version​

Health​

Get Running Configuration​

Configuration Management​

Set Config Value​

Delete Config Key​

Commit​

Rollback​

Discard​

Compare​

Interfaces​

List All Interfaces​

List VLAN Interfaces​

QoS​

List QoS Sessions​

List Overhead Profiles​

Routing​

BGP Summary​

Kernel Routes​

CGNAT VRF Steering​

VRF-Steered Sessions​

VRF Steering Statistics​

Demux​

Demux Configuration​

Demux State​

Events​

Server-Sent Events Stream​

Webhooks​

List Webhooks​

Register Webhook (admin)​

Delete Webhook (admin)​

Prometheus Metrics​

Error Responses​

Next Steps​

Subscribers

List Subscribers

Subscriber Summary

Get Subscriber Detail

Disconnect Subscriber

Disconnect by Interface

Change Subscriber Rate

System

Version

Health

Get Running Configuration

Configuration Management

Set Config Value

Delete Config Key

Commit

Rollback

Discard

Compare

Interfaces

List All Interfaces

List VLAN Interfaces

QoS

List QoS Sessions

List Overhead Profiles

Routing

BGP Summary

Kernel Routes

CGNAT VRF Steering

VRF-Steered Sessions

VRF Steering Statistics

Demux

Demux Configuration

Demux State

Events

Server-Sent Events Stream

Webhooks

List Webhooks

Register Webhook (admin)

Delete Webhook (admin)

Prometheus Metrics

Error Responses

Next Steps