Configuration#
Schema-driven appliance configuration: read, validate, commit, history, and rollback — the same candidate/commit pipeline as the CLI.
8 operations. Roles, error format and pagination are common to the whole API — see the REST API overview.
Authentication
Use a named bearer token. Every endpoint except POST /api/v1/auth/login,
POST /api/v1/auth/enrol and GET /api/v1/system/health requires one. A super-user creates a
token with POST /api/v1/auth/tokens; the plaintext (bngtok_…) is returned exactly once at
creation and only a SHA-256 hash is stored on the appliance, so a lost token is replaced rather
than recovered. Send it on every request:
Each token carries a fixed role (read-only, operator or super-user) and is exempt from CSRF
checks. This is the single credential you need for scripts, integrations and monitoring.
Accounts and tokens share one identity model with the appliance CLI (login.users). Repeated
authentication failures lock the account/source-IP pair out temporarily (HTTP 423 on login).
Session cookies (bundled web UI only)
The appliance also accepts an interactive session cookie, which is how the bundled web UI authenticates. It is documented for completeness — API clients should not use it. It is bound to a login session and obliges the caller to manage a CSRF token, neither of which suits automation.
POST /api/v1/auth/login with username + password (and a TOTP code when enrolled) sets the
bng_session cookie and returns a csrfToken (also available from GET /api/v1/auth/whoami).
Cookie-authenticated mutating requests (anything other than GET/HEAD/OPTIONS) must also send
that value in the X-CSRF-Token header or they are rejected with 403.
NetavoBNG Management API v1#
Contact: Netavo
Configuration#
GET /api/v1/config#
Current configuration values (secrets redacted).
Description
Every field of the active configuration keyed by its schema path. List-mode
fields join their elements with newlines; secret fields return the redaction placeholder
(write the placeholder back to mean "unchanged"). Keyed lists (e.g. RADIUS servers, login
users) return one item per key with the child values keyed by child path.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
{
"fields": {
"syslog enabled": "true",
"syslog server": "10.20.2.40"
},
"lists": {
"auth radius server": [
{
"key": "10.20.2.31",
"values": {
"auth radius server authPort": "1812",
"auth radius server secret": "********"
}
}
]
}
}
Schema of the response body
{
"required": [
"fields",
"lists"
],
"type": "object",
"properties": {
"fields": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Field values keyed by schema path (secrets redacted; list fields joined\n with newlines; null = unset)."
},
"lists": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ConfigListItem"
}
},
"description": "Keyed-list contents keyed by list path."
}
},
"description": "GET /api/v1/config response — the active configuration's values.",
"example": {
"fields": {
"syslog enabled": "true",
"syslog server": "10.20.2.40"
},
"lists": {
"auth radius server": [
{
"key": "10.20.2.31",
"values": {
"auth radius server authPort": "1812",
"auth radius server secret": "********"
}
}
]
}
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
PUT /api/v1/config#
Apply a change set (validate + commit).
Description
Runs the CLI's commit pipeline: exclusive candidate edit → validate → atomic
persist → hot-apply event. Hot-appliable sections take effect immediately; others (see
the schema's requiresRestart) need a restart. The previous version goes into the
rollback history. Super-user only; local appliance only.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Request body
{
"fields": {
"syslog enabled": "true",
"syslog server": "10.20.2.40"
},
"listOps": [
{
"listPath": "auth radius server",
"key": "10.20.2.31",
"delete": false,
"fields": {
"auth radius server authPort": "1812",
"auth radius server secret": "s3cr3t"
}
}
],
"comment": "point syslog at the new collector"
}
Other accepted types: application/*+json, text/json
Schema of the request body
{
"required": [
"fields",
"listOps",
"comment"
],
"type": "object",
"properties": {
"fields": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Field writes keyed by schema `path`. null clears a field; list-mode\n fields take newline/comma-separated elements with replace semantics; a secret field set to\n the redaction placeholder is left unchanged.",
"nullable": true
},
"listOps": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KeyedListOp"
},
"description": "Keyed-list operations (add/update/delete items such as RADIUS\n servers or login users).",
"nullable": true
},
"comment": {
"type": "string",
"description": "Commit comment recorded in the config history (apply only).",
"nullable": true
}
},
"description": "A batch of configuration changes (the body of validate and apply).",
"example": {
"fields": {
"syslog enabled": "true",
"syslog server": "10.20.2.40"
},
"listOps": [
{
"listPath": "auth radius server",
"key": "10.20.2.31",
"delete": false,
"fields": {
"auth radius server authPort": "1812",
"auth radius server secret": "s3cr3t"
}
}
],
"comment": "point syslog at the new collector"
}
}
Responses
Schema of the response body
{
"required": [
"status",
"committedUtc"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Always \"committed\"."
},
"committedUtc": {
"type": "string",
"description": "UTC timestamp the new configuration version became active.",
"format": "date-time",
"nullable": true
}
},
"description": "PUT /api/v1/config result.",
"example": {
"status": "committed",
"committedUtc": "2026-08-03T10:24:11Z"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
POST /api/v1/config/cache-refresh#
Refresh the subscriber cache from the auth database.
Description
Re-reads subscribers from the configured auth database into the in-memory cache
without a config commit (migrated from the retired X-API-Key surface). refreshed: false
means the refresh could not run (e.g. no database auth driver). Audited. Super-user only;
local appliance only.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
Schema of the response body
{
"required": [
"refreshed"
],
"type": "object",
"properties": {
"refreshed": {
"type": "boolean",
"description": "Whether the subscriber cache was actually refreshed from the auth\n database (false when no database auth driver is running)."
}
},
"description": "POST /api/v1/config/cache-refresh result.",
"example": {
"refreshed": true
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
GET /api/v1/config/history#
Configuration version history (rollback points).
Description
Newest first: version number, commit time, comment and committing identity. Any
version listed here can be restored with POST /api/v1/config/rollback.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
POST /api/v1/config/rollback#
Roll back to a historical configuration version.
Description
Stages the historical version as a candidate and commits it (CLI semantics), so the rollback itself becomes a new history entry and hot-appliable changes take effect immediately. Super-user only; local appliance only.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Request body
Other accepted types: application/*+json, text/json
Schema of the request body
Responses
Schema of the response body
{
"required": [
"status",
"version",
"committedUtc"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Always \"rolledBack\"."
},
"version": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "The restored version number.",
"format": "int32"
},
"committedUtc": {
"type": "string",
"description": "UTC timestamp the rollback commit became active.",
"format": "date-time",
"nullable": true
}
},
"description": "POST /api/v1/config/rollback result.",
"example": {
"status": "rolledBack",
"version": 41,
"committedUtc": "2026-08-03T10:26:02Z"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
GET /api/v1/config/schema#
Configuration schema: every editable field, grouped by section.
Description
Field-level schema for the whole appliance configuration, grouped by section
(first CLI-path token) — the same registry the CLI uses, so paths, types, enum values and
secret handling match the CLI exactly. Field path values are the keys for reads and
writes; secret: true fields read back as a redaction placeholder; visibleWhen
describes fields that only apply for a particular driver/mode selection; sections with
requiresRestart: true only take full effect after a restart. Super-user surface (reads
allowed for any role).
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
{
"sections": [
{
"section": "syslog",
"display": "Syslog",
"group": "Monitoring",
"groupOrder": 7,
"requiresRestart": false,
"fields": [
{
"path": "syslog server",
"label": "Server",
"description": "Collector the appliance exports RFC 5424 events to.",
"type": "IpAddress",
"list": false,
"allowedValues": null,
"allowedValueLabels": null,
"secret": false,
"visibleWhen": {
"field": "syslog enabled",
"equals": [
"true"
],
"contains": false
}
}
],
"keyedLists": []
}
]
}
Schema of the response body
{
"required": [
"sections"
],
"type": "object",
"properties": {
"sections": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SectionSchema"
},
"description": "Every configuration section, alphabetical by section key."
}
},
"description": "GET /api/v1/config/schema response.",
"example": {
"sections": [
{
"section": "syslog",
"display": "Syslog",
"group": "Monitoring",
"groupOrder": 7,
"requiresRestart": false,
"fields": [
{
"path": "syslog server",
"label": "Server",
"description": "Collector the appliance exports RFC 5424 events to.",
"type": "IpAddress",
"list": false,
"allowedValues": null,
"allowedValueLabels": null,
"secret": false,
"visibleWhen": {
"field": "syslog enabled",
"equals": [
"true"
],
"contains": false
}
}
],
"keyedLists": []
}
]
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
POST /api/v1/config/validate#
Validate a change set without persisting (dry-run).
Description
Applies the change set to a throwaway candidate and runs full validation; nothing
is persisted regardless of outcome. Validation problems are reported in the 200 body
(valid: false + error), not as an error status. Super-user only; local appliance only.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Request body
{
"fields": {
"syslog enabled": "true",
"syslog server": "10.20.2.40"
},
"listOps": [
{
"listPath": "auth radius server",
"key": "10.20.2.31",
"delete": false,
"fields": {
"auth radius server authPort": "1812",
"auth radius server secret": "s3cr3t"
}
}
],
"comment": "point syslog at the new collector"
}
Other accepted types: application/*+json, text/json
Schema of the request body
{
"required": [
"fields",
"listOps",
"comment"
],
"type": "object",
"properties": {
"fields": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Field writes keyed by schema `path`. null clears a field; list-mode\n fields take newline/comma-separated elements with replace semantics; a secret field set to\n the redaction placeholder is left unchanged.",
"nullable": true
},
"listOps": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KeyedListOp"
},
"description": "Keyed-list operations (add/update/delete items such as RADIUS\n servers or login users).",
"nullable": true
},
"comment": {
"type": "string",
"description": "Commit comment recorded in the config history (apply only).",
"nullable": true
}
},
"description": "A batch of configuration changes (the body of validate and apply).",
"example": {
"fields": {
"syslog enabled": "true",
"syslog server": "10.20.2.40"
},
"listOps": [
{
"listPath": "auth radius server",
"key": "10.20.2.31",
"delete": false,
"fields": {
"auth radius server authPort": "1812",
"auth radius server secret": "s3cr3t"
}
}
],
"comment": "point syslog at the new collector"
}
}
Responses
Schema of the response body
{
"required": [
"valid",
"error"
],
"type": "object",
"properties": {
"valid": {
"type": "boolean",
"description": "Whether the change set passes validation against the current config."
},
"error": {
"type": "string",
"description": "The validation error when Valid is false.",
"nullable": true
}
},
"description": "POST /api/v1/config/validate result. Validation problems are reported here with a\n 200 status — an error status means the request itself failed.",
"example": {
"valid": false,
"error": "syslog server: '10.20.2' is not a valid IP address"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
POST /api/v1/config/webui/certificate#
Upload a TLS certificate for the web listeners.
Description
Validates that the PEM pair loads as a usable server certificate before anything
is written, persists it atomically, switches webUi.tls.mode to "custom" via a config
commit, and hot-reloads the listeners — no restart, existing sessions undisturbed.
Super-user only; local appliance only.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Request body
{
"certPem": "-----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAwIBAgIJAK...\n-----END CERTIFICATE-----\n",
"keyPem": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0B...\n-----END PRIVATE KEY-----\n"
}
Other accepted types: application/*+json, text/json
Schema of the request body
{
"required": [
"certPem",
"keyPem"
],
"type": "object",
"properties": {
"certPem": {
"type": "string",
"description": "Server certificate in PEM format (leaf first, then any chain)."
},
"keyPem": {
"type": "string",
"description": "Matching private key in PEM format."
}
},
"description": "POST /api/v1/config/webui/certificate body.",
"example": {
"certPem": "-----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAwIBAgIJAK...\n-----END CERTIFICATE-----\n",
"keyPem": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0B...\n-----END PRIVATE KEY-----\n"
}
}
Responses
{
"status": "installed",
"subject": "CN=lns1.hul1.example.net",
"notAfter": "2027-08-03T10:24:00Z"
}
Schema of the response body
{
"required": [
"status",
"subject",
"notAfter"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Always \"installed\"."
},
"subject": {
"type": "string",
"description": "Subject DN of the installed certificate."
},
"notAfter": {
"type": "string",
"description": "Expiry of the installed certificate.",
"format": "date-time"
}
},
"description": "POST /api/v1/config/webui/certificate result.",
"example": {
"status": "installed",
"subject": "CN=lns1.hul1.example.net",
"notAfter": "2027-08-03T10:24:00Z"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
Schemas#
CacheRefreshResult#
| Name | Type | Description |
|---|---|---|
refreshed |
boolean | Whether the subscriber cache was actually refreshed from the auth database (false when no database auth driver is running). |
CertificateInstallResult#
| Name | Type | Description |
|---|---|---|
notAfter |
string(date-time) | Expiry of the installed certificate. |
status |
string | Always "installed". |
subject |
string | Subject DN of the installed certificate. |
CertificateUploadRequest#
| Name | Type | Description |
|---|---|---|
certPem |
string | Server certificate in PEM format (leaf first, then any chain). |
keyPem |
string | Matching private key in PEM format. |
ChangeSet#
| Name | Type | Description |
|---|---|---|
comment |
string | null | Commit comment recorded in the config history (apply only). |
fields |
Field writes keyed by schema `path`. null clears a field; list-mode fields take newline/comma-separated elements with replace semantics; a secret field set to the redaction placeholder is left unchanged. | |
listOps |
Array<KeyedListOp> | Keyed-list operations (add/update/delete items such as RADIUS servers or login users). |
ConfigCommitResult#
| Name | Type | Description |
|---|---|---|
committedUtc |
string(date-time) | null | UTC timestamp the new configuration version became active. |
status |
string | Always "committed". |
ConfigListItem#
| Name | Type | Description |
|---|---|---|
key |
string | The item's key (e.g. the RADIUS server host). |
values |
Child-field values keyed by child path (secrets redacted). |
ConfigRollbackResult#
| Name | Type | Description |
|---|---|---|
committedUtc |
string(date-time) | null | UTC timestamp the rollback commit became active. |
status |
string | Always "rolledBack". |
version |
The restored version number. |
ConfigSchema#
| Name | Type | Description |
|---|---|---|
sections |
Array<SectionSchema> | Every configuration section, alphabetical by section key. |
ConfigValidateResult#
| Name | Type | Description |
|---|---|---|
error |
string | null | The validation error when Valid is false. |
valid |
boolean | Whether the change set passes validation against the current config. |
ConfigValues#
| Name | Type | Description |
|---|---|---|
fields |
Field values keyed by schema path (secrets redacted; list fields joined with newlines; null = unset). | |
lists |
Keyed-list contents keyed by list path. |
ConfigVersion#
| Name | Type | Description |
|---|---|---|
comment |
string | null | The commit comment, or null. |
committedUtc |
string(date-time) | When this version was committed. |
username |
string | null | The committing identity, or null. |
version |
Version number for `POST /api/v1/config/rollback`. |
FieldSchema#
| Name | Type | Description |
|---|---|---|
allowedValueLabels |
Optional value→friendly-label map for the dropdown (driver name, humanized enum, …). | |
allowedValues |
Array<string> | Allowed values when the field is an enum/dropdown; null for free-form fields. |
description |
string | What the field does (from the config mapping registry). |
label |
string | Human-friendly field label. |
list |
boolean | True for multi-element fields (written as newline/comma-separated elements). |
path |
string | The field's full path — the key used in reads and change sets. |
secret |
boolean | True for secrets: reads return a placeholder, writing the placeholder means "unchanged". |
type |
string | Value type: String, Int, Bool, IpAddress, IpV4Address, IpV6Address, MacAddress… |
visibleWhen |
KeyedListOp#
| Name | Type | Description |
|---|---|---|
delete |
boolean | true deletes the item (Fields is then ignored). |
fields |
Child-field writes keyed by child path; same secret/list semantics as top-level field writes. | |
key |
string | The item key (e.g. the server host). Created if it doesn't exist. |
listPath |
string | The list's schema `path` (e.g. "auth radius server"). |
KeyedListSchema#
| Name | Type | Description |
|---|---|---|
children |
Array<FieldSchema> | Schema of each item's child fields. |
description |
string | What the list configures (from the config mapping registry). |
keyLabel |
string | Display form of string KeyedListSchema.KeyName for the key column header. Supplied by the server so every label in the editor comes from ONE acronym table — the client's own humaniser has none, which is how "Cpe GRE Circuit" and "Frr" reached the page. |
keyName |
string | What the item key is (e.g. "host", "name"). |
label |
string | Human-friendly list title (e.g. "RADIUS Server", "Login User"). |
path |
string | The list's full path — the `listPath` used in keyed-list operations. |
visibleWhen |
ProblemDetails#
| Name | Type | Description |
|---|---|---|
detail |
string | null | |
instance |
string | null | |
status |
||
title |
string | null | |
type |
string | null |
RollbackRequest#
| Name | Type | Description |
|---|---|---|
version |
The history version number to restore. |
SectionSchema#
| Name | Type | Description |
|---|---|---|
display |
string | Human-friendly card title (e.g. "DHCP", "PPPoE"). |
fields |
Array<FieldSchema> | The section's scalar/list fields. |
group |
string | Editor area this section belongs to — the tab an editing client files it under (e.g. "Routing", "Subscribers", "Monitoring"). Sections sharing a group share an int SectionSchema.GroupOrder; a section the server does not classify is "Advanced". |
groupOrder |
Display order of string SectionSchema.Group relative to the other groups (ascending; "Advanced" sorts last). Sections within a group keep the response's alphabetical order. | |
keyedLists |
Array<KeyedListSchema> | The section's keyed lists (e.g. RADIUS servers keyed by host). |
requiresRestart |
boolean | True when changes in this section only take full effect after a restart. |
section |
string | Section key (first CLI-path token(s), e.g. "syslog", "protocols dhcp"). |
VisibleWhenSchema#
| Name | Type | Description |
|---|---|---|
contains |
boolean | True when the discriminator is a multi-select list: the gate matches if the list CONTAINS any of string[] VisibleWhenSchema.Equals (e.g. show the SNMP sink fields while `alerting sinks` includes "snmp"), rather than equalling one value. Omitted from JSON when false so single-value gates (auth/accounting) serialize exactly as before. |
equals |
Array<string> | Values of the discriminator for which this field/list applies. |
field |
string | Path of the discriminator field. |
Security schemes#
| Name | Type | Scheme | Description |
|---|---|---|---|
| bearerToken | http | bearer | Named API token — the recommended credential for automation. See Authentication in the API overview. |
| sessionCookie | apiKey | Interactive session cookie used by the bundled web UI. Not the integration path for API clients — use a bearer token. See Authentication in the API overview. |
Tags#
| Name | Description |
|---|---|
| Configuration | Schema-driven appliance configuration: read, validate, commit, history, and rollback — the same candidate/commit pipeline as the CLI. |