REST API

Programmatic access to subscriber management, configuration, and monitoring.

Overview

AthenaBNG includes a FastAPI-based REST API for automation and integration. The API communicates with abngd over a Unix domain socket — it never modifies system state directly, ensuring the same safety guarantees as the CLI.

Key Capabilities

Endpoint	Method	Description
/api/v1/subscribers	GET	List all active sessions
/api/v1/subscribers/{id}	GET	Get session details
/api/v1/subscribers/{id}	DELETE	Terminate a session
/api/v1/vlans	GET	List dynamic VLAN interfaces
/api/v1/config	GET	View running configuration
/api/v1/config	PUT	Apply configuration changes
/api/v1/system/status	GET	System health and uptime

Response Format

All responses follow a consistent envelope:

{
  "status": "ok",
  "data": {
    "subscribers": [
      {
        "id": 1,
        "username": "user@example.com",
        "ip_address": "203.0.113.10",
        "interface": "ppp0",
        "speed_down": "50 Mbps",
        "speed_up": "20 Mbps",
        "uptime": "2h 15m"
      }
    ]
  }
}

Authentication

Token-based authentication with configurable API keys:

curl -H "Authorization: Bearer <token>" \
  http://localhost:8080/api/v1/subscribers

Integration Examples

Provisioning System

Automate subscriber management from your BSS/OSS:

import httpx

client = httpx.Client(
    base_url="http://localhost:8080",
    headers={"Authorization": "Bearer <token>"},
)

# List subscribers
response = client.get("/api/v1/subscribers")
subscribers = response.json()["data"]["subscribers"]

# Disconnect a session
client.delete(f"/api/v1/subscribers/{session_id}")

Monitoring Dashboard

Pull real-time statistics into Grafana or your NMS:

# Get subscriber count
curl -s http://localhost:8080/api/v1/subscribers | jq '.data.subscribers | length'

Configuration

api:
  enabled: true
  listen_address: "127.0.0.1"
  listen_port: 8080
  auth_token: "your-api-token"

The API listens on localhost by default. For remote access, place it behind a reverse proxy with TLS.