Alarms#

3 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:

Authorization: Bearer bngtok_…

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

Alarms#

GET /api/v1/alarms#

Current active alarms (most-severe first), with a per-severity summary.

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

200 OK401 Unauthorized403 Forbidden

application/json

{
    "active": [
        {
            "id": "cgn.pool.high",
            "instance": "cgn-public-a",
            "severity": "major",
            "firstRaisedUtc": "2026-08-03T10:24:00Z",
            "ageSeconds": 1847,
            "text": "CGN group cgn-public-a is 91% allocated (8192 of 9000 port blocks in use)",
            "context": {
                "group": "cgn-public-a",
                "usedChunks": "8192",
                "totalChunks": "9000"
            }
        }
    ],
    "count": 1,
    "countBySeverity": {
        "major": 1
    },
    "stats": {
        "raised": 37,
        "cleared": 34,
        "events": 71,
        "eventsDropped": 0
    }
}

Schema of the response body

{
    "required": [
        "active",
        "count",
        "countBySeverity",
        "stats"
    ],
    "type": "object",
    "properties": {
        "active": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Alarm"
            }
        },
        "count": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "format": "int32"
        },
        "countBySeverity": {
            "type": "object",
            "additionalProperties": {
                "pattern": "^-?(?:0|[1-9]\\d*)$",
                "format": "int32"
            }
        },
        "stats": {
            "$ref": "#/components/schemas/AlarmStats"
        }
    },
    "description": "The active-alarm snapshot.",
    "example": {
        "active": [
            {
                "id": "cgn.pool.high",
                "instance": "cgn-public-a",
                "severity": "major",
                "firstRaisedUtc": "2026-08-03T10:24:00Z",
                "ageSeconds": 1847,
                "text": "CGN group cgn-public-a is 91% allocated (8192 of 9000 port blocks in use)",
                "context": {
                    "group": "cgn-public-a",
                    "usedChunks": "8192",
                    "totalChunks": "9000"
                }
            }
        ],
        "count": 1,
        "countBySeverity": {
            "major": 1
        },
        "stats": {
            "raised": 37,
            "cleared": 34,
            "events": 71,
            "eventsDropped": 0
        }
    }
}

application/problem+json

{
    "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"
    }
}

application/problem+json

{
    "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/alarms/clear#

Clear (dismiss) an active alarm by id + optional instance. Admin-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

application/json

{
    "id": "cgn.pool.high",
    "instance": "cgn-public-a"
}

Other accepted types: application/*+json, text/json

Schema of the request body

{
    "required": [
        "id",
        "instance"
    ],
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "description": "The alarm's catalog ID (e.g. `cgn.pool.high`)."
        },
        "instance": {
            "type": "string",
            "description": "The instance discriminator (e.g. a pool/peer name), or null for a singleton.",
            "nullable": true
        }
    },
    "description": "Body for `POST /api/v1/alarms/clear`.",
    "example": {
        "id": "cgn.pool.high",
        "instance": "cgn-public-a"
    }
}

Responses

200 OK404 Not Found401 Unauthorized403 Forbidden

application/json

{
    "cleared": true,
    "id": "cgn.pool.high",
    "instance": "cgn-public-a"
}

Schema of the response body

{
    "required": [
        "cleared",
        "id",
        "instance"
    ],
    "type": "object",
    "properties": {
        "cleared": {
            "type": "boolean"
        },
        "id": {
            "type": "string"
        },
        "instance": {
            "type": "string",
            "nullable": true
        }
    },
    "description": "Result of a manual alarm clear.",
    "example": {
        "cleared": true,
        "id": "cgn.pool.high",
        "instance": "cgn-public-a"
    }
}

application/json

{
    "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"
    }
}

application/problem+json

{
    "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"
    }
}

application/problem+json

{
    "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/alarms/test#

Inject a synthetic alert through the real fan-out to verify sink delivery end-to-end (a "test alerting" action). Returns the exact AlertNotification payload that push sinks receive — the same contract the webhook posts and the message-bus sink will publish.

Description

Admin-only (mutating). Set severity at/above a sink's floor to exercise it — e.g. major reaches a default webhook sink, critical reaches SMTP.

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

application/json

Other accepted types: application/*+json, text/json

Schema of the request body

{
    "oneOf": [
        {
            "nullable": true
        },
        {
            "$ref": "#/components/schemas/AlertTestRequest"
        }
    ]
}

Responses

200 OK409 Conflict401 Unauthorized403 Forbidden

application/json

{
    "source": "bng1.example.net",
    "id": "CGN_POOL_EXHAUSTION",
    "kind": "alarm",
    "severity": "major",
    "state": "raised",
    "raised": true,
    "instance": "public-a",
    "text": "CG-NAT IP group 'public-a' is 94% allocated (7712 of 8192 port blocks).",
    "timestampUtc": "2026-08-03T10:24:00Z",
    "context": {
        "group": "public-a",
        "utilisationPercent": 94
    }
}

Schema of the response body

{
    "required": [
        "source",
        "id",
        "kind",
        "severity",
        "state",
        "raised",
        "instance",
        "text",
        "timestampUtc",
        "context"
    ],
    "type": "object",
    "properties": {
        "source": {
            "type": "string"
        },
        "id": {
            "type": "string"
        },
        "kind": {
            "type": "string"
        },
        "severity": {
            "type": "string"
        },
        "state": {
            "type": "string"
        },
        "raised": {
            "type": "boolean"
        },
        "instance": {
            "type": "string",
            "nullable": true
        },
        "text": {
            "type": "string"
        },
        "timestampUtc": {
            "type": "string",
            "format": "date-time"
        },
        "context": {
            "type": "object",
            "additionalProperties": {
                "type": "string"
            }
        }
    },
    "description": "The canonical serialized alert payload delivered to <b>push</b> sinks. One contract for\n            every transport: the HTTP webhook sink posts this as its JSON body today, and the message-bus\n            sink (fast-follow) will publish this same shape — an integrator writes one parser. Documented in\n            the OpenAPI spec via `POST /api/v1/alarms/test`. Distinct from `AlarmDto` (the active\n            -table query shape): this is the per-event notification, carrying raise/clear and kind.",
    "example": {
        "source": "bng1.example.net",
        "id": "CGN_POOL_EXHAUSTION",
        "kind": "alarm",
        "severity": "major",
        "state": "raised",
        "raised": true,
        "instance": "public-a",
        "text": "CG-NAT IP group 'public-a' is 94% allocated (7712 of 8192 port blocks).",
        "timestampUtc": "2026-08-03T10:24:00Z",
        "context": {
            "group": "public-a",
            "utilisationPercent": 94
        }
    }
}

application/json

{
    "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"
    }
}

application/problem+json

{
    "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"
    }
}

application/problem+json

{
    "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#

Alarm#

Name	Type	Description
`ageSeconds`
`context`
`firstRaisedUtc`	string(date-time)
`id`	string
`instance`	string \| null
`severity`	string
`text`	string

AlarmClearRequest#

Name	Type	Description
`id`	string	The alarm's catalog ID (e.g. `cgn.pool.high`).
`instance`	string \| null	The instance discriminator (e.g. a pool/peer name), or null for a singleton.

AlarmClearResult#

Name	Type	Description
`cleared`	boolean
`id`	string
`instance`	string \| null

AlarmsResponse#

Name	Type	Description
`active`	Array<Alarm>
`count`
`countBySeverity`
`stats`	AlarmStats

AlarmStats#

Name	Type	Description
`cleared`
`events`
`eventsDropped`
`raised`

AlertNotification#

Name	Type	Description
`context`
`id`	string
`instance`	string \| null
`kind`	string
`raised`	boolean
`severity`	string
`source`	string
`state`	string
`text`	string
`timestampUtc`	string(date-time)

AlertTestRequest#

Name	Type	Description
`severity`	string \| null	critical\|major\|minor\|warning\|info (default major).
`text`	string \| null	Optional custom alert text.

ProblemDetails#

Name	Type	Description
`detail`	string \| null
`instance`	string \| null
`status`
`title`	string \| null
`type`	string \| null

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
Alarms