Configuration#
Schema-driven appliance configuration: read, validate, commit, history, and rollback — the same candidate/commit pipeline as the CLI.
13 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.
One endpoint refuses the cookie outright: GET /api/v1/metrics, the Prometheus scrape, accepts a
bearer token only, so that a scraper can never keep a login session alive.
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. Where the key is
itself a secret — an SNMP read-only community — it is returned to the super-user, who
needs it to edit the entry, and as a numbered placeholder to every other role. A URL can
carry a credential in its userinfo, path or query: the super-user gets it whole, every
other role gets scheme://host[:port]/##SECRET-DATA##. The accounts and sign-in
configuration (system login …, web-ui auth …) are returned to the super-user only; for
other roles those paths are absent, as they are from the schema.
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
{
"status": "committed",
"committedUtc": "2026-08-03T10:24:11Z",
"confirmDeadlineUtc": null,
"confirmNotice": null
}
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
},
"confirmDeadlineUtc": {
"type": "string",
"description": "Deadline of an existing rollback, if still pending.",
"format": "date-time",
"nullable": true
},
"confirmNotice": {
"type": "string",
"description": "Operator notice when this commit confirms a pending rollback.",
"nullable": true
}
},
"description": "PUT /api/v1/config result.",
"example": {
"status": "committed",
"committedUtc": "2026-08-03T10:24:11Z",
"confirmDeadlineUtc": null,
"confirmNotice": null
}
}
{
"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 subscriber source now.
Description
Runs one pass of the subscriber refresh - the pass the timer runs every
auth.database.cacheRefreshIntervalSeconds - and returns what it did: rows loaded, whether
the load was believed, and the sessions re-policed, ended or held. refreshed: false
means nothing was applied (no source configured, the source could not be read, or the
load was not believed); detail says which. A session whose row has gone is still ended
only when two loads in a row say so. 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
{
"refreshed": true,
"detail": "Loaded 451 row(s) from SQL (bng.BroadbandSubscribers); applied.\nSessions: 1 re-policed, 0 ended, 0 adopted.",
"rows": 451,
"acceptedRows": 451,
"suspect": false,
"rePoliced": 1,
"ended": 0,
"adopted": 0,
"awaitingConfirmation": 0,
"deferredByLimit": 0,
"heldForUnreadableRows": 0,
"failedEnds": 0,
"guestsDeferred": 0,
"errors": 0
}
Schema of the response body
{
"required": [
"refreshed"
],
"type": "object",
"properties": {
"refreshed": {
"type": "boolean",
"description": "True when the source was read and the load applied. False when there\n is no source, it could not be read, or the load was read and not believed\n (Suspect); Detail says which."
},
"detail": {
"type": "string",
"description": "The outcome in words, as the CLI prints it.",
"nullable": true
},
"rows": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Rows the load returned.",
"format": "int32",
"default": 0
},
"acceptedRows": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Rows in the view now being served.",
"format": "int32",
"default": 0
},
"suspect": {
"type": "boolean",
"description": "True when the load was read and not applied: it was empty, or had lost\n more rows - or had more rows turn non-active - than a load plausibly does. Nobody is\n disconnected and new and changed subscribers are not applied either; accept it with\n `request subscribers source accept` if it is right.",
"default": false
},
"rePoliced": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Live sessions whose state or rates were changed.",
"format": "int32",
"default": 0
},
"ended": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Live sessions ended.",
"format": "int32",
"default": 0
},
"adopted": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Guest sessions adopted by a line.",
"format": "int32",
"default": 0
},
"awaitingConfirmation": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Sessions with no authority that are ended only if the next\n refresh agrees.",
"format": "int32",
"default": 0
},
"deferredByLimit": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Sessions not ended because the limit for one refresh was\n reached.",
"format": "int32",
"default": 0
},
"heldForUnreadableRows": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Sessions left alone because the source had a row for them\n that could not be read.",
"format": "int32",
"default": 0
},
"failedEnds": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Sessions whose disconnect failed; tried again at the next refresh.",
"format": "int32",
"default": 0
},
"guestsDeferred": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Guest sessions left for the next refresh: this one had adopted or\n ended as many guests as one refresh may.",
"format": "int32",
"default": 0
},
"errors": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Sessions that could not be reconciled because of a fault; the rest were.",
"format": "int32",
"default": 0
}
},
"description": "POST /api/v1/config/cache-refresh result: what one pass of the subscriber refresh\n did.",
"example": {
"refreshed": true,
"detail": "Loaded 451 row(s) from SQL (bng.BroadbandSubscribers); applied.\nSessions: 1 re-policed, 0 ended, 0 adopted.",
"rows": 451,
"acceptedRows": 451,
"suspect": false,
"rePoliced": 1,
"ended": 0,
"adopted": 0,
"awaitingConfirmation": 0,
"deferredByLimit": 0,
"heldForUnreadableRows": 0,
"failedEnds": 0,
"guestsDeferred": 0,
"errors": 0
}
}
{
"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/confirm#
Whether a confirmed commit is waiting to be confirmed.
Description
A commit made with a confirm window — an import with action: "commitConfirm",
or commit confirm at the CLI — rolls back at deadlineUtc unless any authorized
operator commits first (CLI, web UI, API, import or account changes). Internal token-use
and login bookkeeping never confirm it. The deadline survives control-plane restarts.
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": [
"pending",
"deadlineUtc"
],
"type": "object",
"properties": {
"pending": {
"type": "boolean",
"description": "True while a commit made with a confirm window awaits confirmation."
},
"deadlineUtc": {
"type": "string",
"description": "When it rolls back unless confirmed; null when none is pending.",
"format": "date-time",
"nullable": true
}
},
"description": "Whether a confirmed commit is pending.",
"example": {
"pending": true,
"deadlineUtc": "2026-10-01T12:10: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"
}
}
POST /api/v1/config/confirm#
Confirm a pending confirmed commit, cancelling its automatic rollback.
Description
Makes the configuration committed with a confirm window permanent. Super-user only; local appliance only. Any authorized operator may confirm, regardless of who started it.
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": [
"pending",
"deadlineUtc"
],
"type": "object",
"properties": {
"pending": {
"type": "boolean",
"description": "True while a commit made with a confirm window awaits confirmation."
},
"deadlineUtc": {
"type": "string",
"description": "When it rolls back unless confirmed; null when none is pending.",
"format": "date-time",
"nullable": true
}
},
"description": "Whether a confirmed commit is pending.",
"example": {
"pending": true,
"deadlineUtc": "2026-10-01T12:10: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"
}
}
GET /api/v1/config/export#
Export a redacted backup of the active configuration.
Description
The whole configuration with every secret replaced by a placeholder — safe to
hand to support, and what any signed-in role can already read through GET
/api/v1/config. It restores only onto a box that already holds the secrets: on import
each placeholder takes the value the target has at the same path. For a backup that can
rebuild a box, use the encrypted export. Audited.
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
{
"fileName": "lns1-config-encrypted-20261001T120000Z.json",
"kind": "encrypted",
"backup": "{ \"format\": \"netavo-config-backup\", \"formatVersion\": 1, \"kind\": \"encrypted\", … }"
}
Schema of the response body
{
"required": [
"fileName",
"kind",
"backup"
],
"type": "object",
"properties": {
"fileName": {
"type": "string",
"description": "A name to save it under: host, kind and time of export."
},
"kind": {
"type": "string",
"description": "\"redacted\" or \"encrypted\"."
},
"backup": {
"type": "string",
"description": "The backup itself — a JSON document, as text. Save it as it is; it is\n what `POST /api/v1/config/import` and the CLI's `load override` take."
}
},
"description": "A configuration backup, as an export returns it.",
"example": {
"fileName": "lns1-config-encrypted-20261001T120000Z.json",
"kind": "encrypted",
"backup": "{ \"format\": \"netavo-config-backup\", \"formatVersion\": 1, \"kind\": \"encrypted\", … }"
}
}
{
"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/export#
Export an encrypted backup of the active configuration.
Description
The whole configuration, secrets included, encrypted with AES-256-GCM under a key derived from the passphrase (PBKDF2-HMAC-SHA256); the envelope's header is authenticated with it. This is the backup that restores a replacement box. The passphrase travels in the request body, never the URL, and is neither stored nor logged — a backup whose passphrase is lost cannot be opened. Audited. Super-user 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
{
"required": [
"passphrase"
],
"type": "object",
"properties": {
"passphrase": {
"type": "string",
"description": "The passphrase the backup is encrypted under: at least 12\n characters. It is not stored and cannot be recovered.",
"nullable": true
}
},
"description": "POST /api/v1/config/export body.",
"example": {
"passphrase": "correct horse battery staple"
}
}
Responses
{
"fileName": "lns1-config-encrypted-20261001T120000Z.json",
"kind": "encrypted",
"backup": "{ \"format\": \"netavo-config-backup\", \"formatVersion\": 1, \"kind\": \"encrypted\", … }"
}
Schema of the response body
{
"required": [
"fileName",
"kind",
"backup"
],
"type": "object",
"properties": {
"fileName": {
"type": "string",
"description": "A name to save it under: host, kind and time of export."
},
"kind": {
"type": "string",
"description": "\"redacted\" or \"encrypted\"."
},
"backup": {
"type": "string",
"description": "The backup itself — a JSON document, as text. Save it as it is; it is\n what `POST /api/v1/config/import` and the CLI's `load override` take."
}
},
"description": "A configuration backup, as an export returns it.",
"example": {
"fileName": "lns1-config-encrypted-20261001T120000Z.json",
"kind": "encrypted",
"backup": "{ \"format\": \"netavo-config-backup\", \"formatVersion\": 1, \"kind\": \"encrypted\", … }"
}
}
{
"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/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/import#
Import a backup: preview it, or restore it.
Description
The backup is loaded into the candidate configuration and validated — never
written to the active configuration directly. The response reports what it would change
before anything is committed: the diff (secrets redacted), the secrets that differ, and
the box-specific values (hostname, router id, management addresses, data-plane ports…)
that differ from this box. With action: "preview" that is all; "commit" and
"commitConfirm" then commit it as any other change is committed.
A **redacted** backup holds no secrets: each placeholder takes the secret this box holds
at the same path (`secretsKept`). One with no counterpart is `secretsMissing`, and an
import with missing secrets can be previewed but not committed here.
A backup from another release is read as that release's `config.json` would be at
start-up; one holding a setting this release does not know is refused, naming it. A
wrong passphrase, or a file altered since it was exported, is refused; nothing is
loaded. Every attempt is 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. |
Request body
{
"backup": "{ \"format\": \"netavo-config-backup\", … }",
"passphrase": "correct horse battery staple",
"action": "preview",
"confirmMinutes": 10,
"comment": "restore after disk replacement"
}
Other accepted types: application/*+json, text/json
Schema of the request body
{
"required": [
"backup",
"passphrase",
"action",
"confirmMinutes",
"comment"
],
"type": "object",
"properties": {
"backup": {
"type": "string",
"description": "The backup, as text — the `backup` an export returned, or the\n contents of the file it was saved to.",
"nullable": true
},
"passphrase": {
"type": "string",
"description": "The passphrase of an encrypted backup. Ignored for a redacted\n one.",
"nullable": true
},
"action": {
"type": "string",
"description": "\"preview\" (the default): validate and report, change nothing.\n \"commit\": validate and commit. \"commitConfirm\": commit, and roll back automatically\n unless any authorized operator commits or calls `POST /api/v1/config/confirm` within `confirmMinutes`.",
"nullable": true
},
"confirmMinutes": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "The confirm window for \"commitConfirm\" (default 10).",
"format": "int32",
"nullable": true
},
"comment": {
"type": "string",
"description": "Commit comment recorded in the history; defaults to \"restore from\n backup of <hostname> (<exported>)\".",
"nullable": true
}
},
"description": "POST /api/v1/config/import body.",
"example": {
"backup": "{ \"format\": \"netavo-config-backup\", … }",
"passphrase": "correct horse battery staple",
"action": "preview",
"confirmMinutes": 10,
"comment": "restore after disk replacement"
}
}
Responses
{
"status": "previewed",
"origin": {
"kind": "encrypted",
"product": "netavo-bng",
"softwareVersion": "1.0.0 (192c4e68)",
"hostname": "lns1",
"exportedUtc": "2026-10-01T12:00:00.0000000Z",
"exportedBy": "noc-alice",
"committedUtc": "2026-09-30T08:15:00.0000000Z",
"commitComment": "point syslog at the new collector",
"commitUsername": "noc-bob"
},
"valid": true,
"validationError": null,
"noChanges": false,
"linesAdded": 2,
"linesRemoved": 1,
"diff": "[edit routing]\n- hostname replacement;\n+ hostname lns1;\n[edit syslog]\n+ port 6514;",
"secretsChanged": [
"auth radius server 10.20.2.31 secret"
],
"secretsKept": [],
"secretsMissing": [],
"boxSpecific": [
"- set routing hostname replacement",
"+ set routing hostname lns1"
],
"notes": [
"The backup was written by release 1.0.0 (192c4e68); this box runs 1.1.0 (5f1cc70a)."
],
"committedUtc": null,
"confirmDeadlineUtc": null
}
Schema of the response body
{
"required": [
"status",
"origin",
"valid",
"validationError",
"noChanges",
"linesAdded",
"linesRemoved",
"diff",
"secretsChanged",
"secretsKept",
"secretsMissing",
"boxSpecific",
"notes",
"committedUtc",
"confirmDeadlineUtc"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "\"previewed\" (nothing changed), \"unchanged\" (the backup is what is\n already running; nothing committed), \"committed\", or \"committedPendingConfirm\"."
},
"origin": {
"$ref": "#/components/schemas/ConfigBackupOrigin"
},
"valid": {
"type": "boolean",
"description": "Whether the configuration in it passes validation on this box."
},
"validationError": {
"type": "string",
"description": "The validation error when it does not.",
"nullable": true
},
"noChanges": {
"type": "boolean",
"description": "True when it is identical to the running configuration."
},
"linesAdded": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Set-format lines the restore adds.",
"format": "int32"
},
"linesRemoved": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Set-format lines the restore removes.",
"format": "int32"
},
"diff": {
"type": "string",
"description": "The change against the running configuration, as the CLI's `compare`\n prints it; secret values are redacted."
},
"secretsChanged": {
"type": "array",
"items": {
"type": "string"
},
"description": "Paths of secrets whose value differs — the diff cannot show\n these."
},
"secretsKept": {
"type": "array",
"items": {
"type": "string"
},
"description": "Redacted backup: paths of secrets taken from this box."
},
"secretsMissing": {
"type": "array",
"items": {
"type": "string"
},
"description": "Redacted backup: paths of secrets neither in the backup nor on\n this box. Non-empty means it cannot be committed here."
},
"boxSpecific": {
"type": "array",
"items": {
"type": "string"
},
"description": "Changes to values that describe a particular box — hostname,\n router id, management and interface addresses, data-plane ports — as \"+\"/\"-\" set lines.\n Expected when restoring a replacement; a warning anywhere else."
},
"notes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Anything else worth knowing, e.g. that another release wrote it."
},
"committedUtc": {
"type": "string",
"description": "When the restore was committed (commit actions only).",
"format": "date-time",
"nullable": true
},
"confirmDeadlineUtc": {
"type": "string",
"description": "When it rolls back unless confirmed (\"commitConfirm\").",
"format": "date-time",
"nullable": true
}
},
"description": "POST /api/v1/config/import result: what the backup is and what restoring it does\n (or did). It never contains a secret.",
"example": {
"status": "previewed",
"origin": {
"kind": "encrypted",
"product": "netavo-bng",
"softwareVersion": "1.0.0 (192c4e68)",
"hostname": "lns1",
"exportedUtc": "2026-10-01T12:00:00.0000000Z",
"exportedBy": "noc-alice",
"committedUtc": "2026-09-30T08:15:00.0000000Z",
"commitComment": "point syslog at the new collector",
"commitUsername": "noc-bob"
},
"valid": true,
"validationError": null,
"noChanges": false,
"linesAdded": 2,
"linesRemoved": 1,
"diff": "[edit routing]\n- hostname replacement;\n+ hostname lns1;\n[edit syslog]\n+ port 6514;",
"secretsChanged": [
"auth radius server 10.20.2.31 secret"
],
"secretsKept": [],
"secretsMissing": [],
"boxSpecific": [
"- set routing hostname replacement",
"+ set routing hostname lns1"
],
"notes": [
"The backup was written by release 1.0.0 (192c4e68); this box runs 1.1.0 (5f1cc70a)."
],
"committedUtc": null,
"confirmDeadlineUtc": null
}
}
{
"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/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
{
"status": "rolledBack",
"version": 41,
"committedUtc": "2026-08-03T10:26:02Z",
"confirmDeadlineUtc": null,
"confirmNotice": null
}
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
},
"confirmDeadlineUtc": {
"type": "string",
"description": "Deadline of an existing rollback, if still pending.",
"format": "date-time",
"nullable": true
},
"confirmNotice": {
"type": "string",
"description": "Operator notice when this commit confirms a pending rollback.",
"nullable": true
}
},
"description": "POST /api/v1/config/rollback result.",
"example": {
"status": "rolledBack",
"version": 41,
"committedUtc": "2026-08-03T10:26:02Z",
"confirmDeadlineUtc": null,
"confirmNotice": null
}
}
{
"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, without the accounts and sign-in sections — system login,
web-ui auth — which only a super-user is shown).
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 |
|---|---|---|
acceptedRows |
Rows in the view now being served. | |
adopted |
Guest sessions adopted by a line. | |
awaitingConfirmation |
Sessions with no authority that are ended only if the next refresh agrees. | |
deferredByLimit |
Sessions not ended because the limit for one refresh was reached. | |
detail |
string | null | The outcome in words, as the CLI prints it. |
ended |
Live sessions ended. | |
errors |
Sessions that could not be reconciled because of a fault; the rest were. | |
failedEnds |
Sessions whose disconnect failed; tried again at the next refresh. | |
guestsDeferred |
Guest sessions left for the next refresh: this one had adopted or ended as many guests as one refresh may. | |
heldForUnreadableRows |
Sessions left alone because the source had a row for them that could not be read. | |
refreshed |
boolean | True when the source was read and the load applied. False when there is no source, it could not be read, or the load was read and not believed (Suspect); Detail says which. |
rePoliced |
Live sessions whose state or rates were changed. | |
rows |
Rows the load returned. | |
suspect |
boolean | True when the load was read and not applied: it was empty, or had lost more rows - or had more rows turn non-active - than a load plausibly does. Nobody is disconnected and new and changed subscribers are not applied either; accept it with `request subscribers source accept` if it is right. |
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). |
ConfigBackupFile#
| Name | Type | Description |
|---|---|---|
backup |
string | The backup itself — a JSON document, as text. Save it as it is; it is what `POST /api/v1/config/import` and the CLI's `load override` take. |
fileName |
string | A name to save it under: host, kind and time of export. |
kind |
string | "redacted" or "encrypted". |
ConfigBackupOrigin#
| Name | Type | Description |
|---|---|---|
commitComment |
string | null | That commit's comment. |
committedUtc |
string | null | When the configuration in it was committed, if known. |
commitUsername |
string | null | Who made that commit. |
exportedBy |
string | Who exported it. |
exportedUtc |
string | When it was exported. |
hostname |
string | The box it was exported from. |
kind |
string | "redacted" or "encrypted". |
product |
string | The product it is a configuration of. |
softwareVersion |
string | The release that wrote it. |
ConfigCommitResult#
| Name | Type | Description |
|---|---|---|
committedUtc |
string(date-time) | null | UTC timestamp the new configuration version became active. |
confirmDeadlineUtc |
string(date-time) | null | Deadline of an existing rollback, if still pending. |
confirmNotice |
string | null | Operator notice when this commit confirms a pending rollback. |
status |
string | Always "committed". |
ConfigConfirmState#
| Name | Type | Description |
|---|---|---|
deadlineUtc |
string(date-time) | null | When it rolls back unless confirmed; null when none is pending. |
pending |
boolean | True while a commit made with a confirm window awaits confirmation. |
ConfigImportResult#
| Name | Type | Description |
|---|---|---|
boxSpecific |
Array<string> | Changes to values that describe a particular box — hostname, router id, management and interface addresses, data-plane ports — as "+"/"-" set lines. Expected when restoring a replacement; a warning anywhere else. |
committedUtc |
string(date-time) | null | When the restore was committed (commit actions only). |
confirmDeadlineUtc |
string(date-time) | null | When it rolls back unless confirmed ("commitConfirm"). |
diff |
string | The change against the running configuration, as the CLI's `compare` prints it; secret values are redacted. |
linesAdded |
Set-format lines the restore adds. | |
linesRemoved |
Set-format lines the restore removes. | |
noChanges |
boolean | True when it is identical to the running configuration. |
notes |
Array<string> | Anything else worth knowing, e.g. that another release wrote it. |
origin |
ConfigBackupOrigin | |
secretsChanged |
Array<string> | Paths of secrets whose value differs — the diff cannot show these. |
secretsKept |
Array<string> | Redacted backup: paths of secrets taken from this box. |
secretsMissing |
Array<string> | Redacted backup: paths of secrets neither in the backup nor on this box. Non-empty means it cannot be committed here. |
status |
string | "previewed" (nothing changed), "unchanged" (the backup is what is already running; nothing committed), "committed", or "committedPendingConfirm". |
valid |
boolean | Whether the configuration in it passes validation on this box. |
validationError |
string | null | The validation error when it does not. |
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. |
confirmDeadlineUtc |
string(date-time) | null | Deadline of an existing rollback, if still pending. |
confirmNotice |
string | null | Operator notice when this commit confirms a pending rollback. |
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`. |
ExportRequest#
| Name | Type | Description |
|---|---|---|
passphrase |
string | null | The passphrase the backup is encrypted under: at least 12 characters. It is not stored and cannot be recovered. |
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 |
ImportRequest#
| Name | Type | Description |
|---|---|---|
action |
string | null | "preview" (the default): validate and report, change nothing. "commit": validate and commit. "commitConfirm": commit, and roll back automatically unless any authorized operator commits or calls `POST /api/v1/config/confirm` within `confirmMinutes`. |
backup |
string | null | The backup, as text — the `backup` an export returned, or the contents of the file it was saved to. |
comment |
string | null | Commit comment recorded in the history; defaults to "restore from backup of <hostname> (<exported>)". |
confirmMinutes |
The confirm window for "commitConfirm" (default 10). | |
passphrase |
string | null | The passphrase of an encrypted backup. Ignored for a redacted one. |
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. |