CGN

Carrier-grade NAT (NAT44): status, IP groups (public pools), live bindings, and binding identity enrichment.

9 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

CGN

---

GET /api/v1/cgn/bindings

List live NAT bindings (filtered, paged).

Description

Filters combine with AND: group and vrf are exact (case-insensitive; "default" matches the default table), ip is a prefix match against both the inside and the public address. running: false means CGN isn't active — the list is then empty. Fleet-proxyable.

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.
group	query	string		No	Filter by CGN IP group name.
ip	query	string		No	Prefix match on the inside or public IPv4 address.
limit	query		100	No	Page size, clamped to 1–1000 (default 100).
offset	query		0	No	Rows to skip (default 0).
vrf	query	string		No	Filter by inside VRF name.

Responses

200 OK401 Unauthorized403 Forbidden

application/json

{
    "running": true,
    "total": 1842,
    "offset": 0,
    "limit": 50,
    "items": [
        {
            "bindingIndex": 10427,
            "group": "cgn-public-a",
            "insideVrf": "residential",
            "insideIp": "100.64.12.37",
            "publicIp": "45.84.200.113",
            "sessionId": 40213,
            "subscriberId": "alice@example.net",
            "autoLearned": false,
            "portBlocks": [
                "21504-22015",
                "22016-22527"
            ],
            "chunkSize": 512,
            "portCap": 4096,
            "createdUtc": "2026-08-03T10:24:00Z"
        }
    ]
}

Schema of the response body

{
    "required": [
        "running",
        "total",
        "offset",
        "limit",
        "items"
    ],
    "type": "object",
    "properties": {
        "running": {
            "type": "boolean",
            "description": "Whether CGN is active in this control-plane process."
        },
        "total": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Bindings matching the filters (before paging).",
            "format": "int32"
        },
        "offset": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "The offset this page was taken at.",
            "format": "int32"
        },
        "limit": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "The effective page size (after clamping).",
            "format": "int32"
        },
        "items": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/CgnBindingRow"
            },
            "description": "The page of binding rows."
        }
    },
    "description": "GET /api/v1/cgn/bindings page. Running=false means CGN isn't active (rows empty).",
    "example": {
        "running": true,
        "total": 1842,
        "offset": 0,
        "limit": 50,
        "items": [
            {
                "bindingIndex": 10427,
                "group": "cgn-public-a",
                "insideVrf": "residential",
                "insideIp": "100.64.12.37",
                "publicIp": "45.84.200.113",
                "sessionId": 40213,
                "subscriberId": "alice@example.net",
                "autoLearned": false,
                "portBlocks": [
                    "21504-22015",
                    "22016-22527"
                ],
                "chunkSize": 512,
                "portCap": 4096,
                "createdUtc": "2026-08-03T10:24:00Z"
            }
        ]
    }
}

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/cgn/bindings/{bindingIndex}/identify

Attach a subscriber identity to an auto-learned binding.

Description

Auto-learned bindings start anonymous; this enriches one with the subscriber identity used in compliance/abuse-resolution logging (an Identify event is emitted per port block, and the acting principal is audited). Only auto-learned bindings can be identified. 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.
bindingIndex	path			No	The binding's index (from the bindings list).

Request body

application/json

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

Schema of the request body

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

Responses

200 OK400 Bad Request404 Not Found409 Conflict401 Unauthorized403 Forbidden

application/json

{
    "bindingIndex": 10427,
    "group": "cgn-public-a",
    "insideVrf": "residential",
    "insideIp": "100.64.12.37",
    "publicIp": "45.84.200.113",
    "sessionId": 40213,
    "subscriberId": "alice@example.net",
    "autoLearned": false,
    "portBlocks": [
        "21504-22015",
        "22016-22527"
    ],
    "chunkSize": 512,
    "portCap": 4096,
    "createdUtc": "2026-08-03T10:24:00Z"
}

Schema of the response body

{
    "required": [
        "bindingIndex",
        "group",
        "insideVrf",
        "insideIp",
        "publicIp",
        "sessionId",
        "subscriberId",
        "autoLearned",
        "portBlocks",
        "chunkSize",
        "portCap",
        "createdUtc"
    ],
    "type": "object",
    "properties": {
        "bindingIndex": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Stable index of the binding — the key for the identify endpoint.",
            "format": "uint32"
        },
        "group": {
            "type": "string",
            "description": "CGN IP group the public address came from."
        },
        "insideVrf": {
            "type": "string",
            "description": "Inside VRF of the subscriber (\"default\" = global table)."
        },
        "insideIp": {
            "type": "string",
            "description": "Subscriber's inside IPv4 address."
        },
        "publicIp": {
            "type": "string",
            "description": "Public IPv4 address the subscriber is translated to."
        },
        "sessionId": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Associated BNG session id (0 for anonymous auto-learned bindings).",
            "format": "uint32"
        },
        "subscriberId": {
            "type": "string",
            "description": "Subscriber identity for compliance logging, or null if not identified.",
            "nullable": true
        },
        "autoLearned": {
            "type": "boolean",
            "description": "True when the binding was auto-learned rather than session-driven."
        },
        "portBlocks": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "description": "Allocated port ranges, as \"start-end\" strings."
        },
        "chunkSize": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Ports per block for this binding.",
            "format": "uint16"
        },
        "portCap": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Port cap in force for this binding.",
            "format": "uint16"
        },
        "createdUtc": {
            "type": "string",
            "description": "UTC time the binding was created.",
            "format": "date-time"
        }
    },
    "description": "One live NAT binding (a subscriber's inside address mapped to a public address with\n    one or more port blocks).",
    "example": {
        "bindingIndex": 10427,
        "group": "cgn-public-a",
        "insideVrf": "residential",
        "insideIp": "100.64.12.37",
        "publicIp": "45.84.200.113",
        "sessionId": 40213,
        "subscriberId": "alice@example.net",
        "autoLearned": false,
        "portBlocks": [
            "21504-22015",
            "22016-22527"
        ],
        "chunkSize": 512,
        "portCap": 4096,
        "createdUtc": "2026-08-03T10:24:00Z"
    }
}

application/problem+jsonapplication/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"
    }
}

Schema of the response body

application/problem+jsonapplication/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"
    }
}

Schema of the response body

application/problem+jsonapplication/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"
    }
}

Schema of the response body

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

---

GET /api/v1/cgn/groups

List CGN IP groups (public address pools) with live utilisation.

Description

One row per configured group; utilisation and activeBindings are live values (null/0 when CGN isn't running or the group was added since startup). Fleet-proxyable.

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

[
    {
        "name": "cgn-public-a",
        "description": "Residential CGN pool",
        "outsideVrf": "internet",
        "publicSubnets": [
            "45.84.200.0/24"
        ],
        "chunkSize": 512,
        "portCap": 4096,
        "setupsPerSec": 200,
        "bindingTimeoutSeconds": 300,
        "quarantineSeconds": 120,
        "bypassPrefixes": [
            "100.64.0.0/10"
        ],
        "autoLearn": [
            {
                "insideVrf": "residential",
                "prefixes": [
                    "100.64.0.0/12"
                ]
            }
        ],
        "timeouts": {
            "tcpEstablished": 7440,
            "tcpTransitory": 240,
            "udp": 300,
            "icmp": 60
        },
        "activeBindings": 1842,
        "utilisation": {
            "totalChunks": 9000,
            "freeChunks": 712,
            "usedChunks": 8192,
            "quarantinedChunks": 96
        }
    }
]

Schema of the response body

{
    "type": "array",
    "items": {
        "$ref": "#/components/schemas/CgnGroup"
    }
}

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/cgn/groups

Create a CGN IP group.

Description

Commits through the configuration store. The CGN section is restart-required: the response carries restartRequired: true and the new group only becomes active after a control-plane restart. 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

application/json

{
    "name": "cgn-public-a",
    "description": "Residential CGN pool",
    "outsideVrf": "internet",
    "publicSubnets": [
        "45.84.200.0/24"
    ],
    "chunkSize": 512,
    "portCap": 4096,
    "setupsPerSec": 200,
    "bindingTimeoutSeconds": 300,
    "quarantineSeconds": 120,
    "bypassPrefixes": [
        "100.64.0.0/10"
    ],
    "autoLearn": [
        {
            "insideVrf": "residential",
            "prefixes": [
                "100.64.0.0/12"
            ]
        }
    ],
    "timeouts": {
        "tcpEstablished": 7440,
        "tcpTransitory": 240,
        "udp": 300,
        "icmp": 60
    }
}

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

Schema of the request body

{
    "required": [
        "name",
        "description",
        "outsideVrf",
        "publicSubnets",
        "chunkSize",
        "portCap",
        "setupsPerSec",
        "bindingTimeoutSeconds",
        "quarantineSeconds",
        "bypassPrefixes",
        "autoLearn",
        "timeouts"
    ],
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "description": "Group name — the immutable key (service plans reference it)."
        },
        "description": {
            "type": "string",
            "description": "Free-text description.",
            "nullable": true
        },
        "outsideVrf": {
            "type": "string",
            "description": "VRF holding the public side (null/empty = default table).",
            "nullable": true
        },
        "publicSubnets": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "description": "Public IPv4 subnets (CIDR) the group allocates from.",
            "nullable": true
        },
        "chunkSize": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Ports per allocated port block.",
            "format": "int32"
        },
        "portCap": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Maximum ports one subscriber may hold before extensions stop.",
            "format": "int32"
        },
        "setupsPerSec": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Per-subscriber NAT setup rate limit.",
            "format": "int32"
        },
        "bindingTimeoutSeconds": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Idle teardown for auto-learned bindings.",
            "format": "int32"
        },
        "quarantineSeconds": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Quarantine before a freed port block is reused.",
            "format": "int32"
        },
        "bypassPrefixes": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "description": "Destinations that bypass NAT (CIDR).",
            "nullable": true
        },
        "autoLearn": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/CgnAutoLearn"
            },
            "description": "Auto-learn scopes (inside VRF + prefixes).",
            "nullable": true
        },
        "timeouts": {
            "oneOf": [
                {
                    "nullable": true
                },
                {
                    "$ref": "#/components/schemas/CgnTimeouts"
                }
            ]
        }
    },
    "description": "Request body for CGN IP group create/update.",
    "example": {
        "name": "cgn-public-a",
        "description": "Residential CGN pool",
        "outsideVrf": "internet",
        "publicSubnets": [
            "45.84.200.0/24"
        ],
        "chunkSize": 512,
        "portCap": 4096,
        "setupsPerSec": 200,
        "bindingTimeoutSeconds": 300,
        "quarantineSeconds": 120,
        "bypassPrefixes": [
            "100.64.0.0/10"
        ],
        "autoLearn": [
            {
                "insideVrf": "residential",
                "prefixes": [
                    "100.64.0.0/12"
                ]
            }
        ],
        "timeouts": {
            "tcpEstablished": 7440,
            "tcpTransitory": 240,
            "udp": 300,
            "icmp": 60
        }
    }
}

Responses

200 OK400 Bad Request409 Conflict422 Unprocessable Content401 Unauthorized403 Forbidden

application/json

{
    "status": "committed",
    "name": "cgn-public-a",
    "committedUtc": "2026-08-03T10:24:11Z",
    "restartRequired": true
}

Schema of the response body

{
    "required": [
        "status",
        "name",
        "committedUtc",
        "restartRequired"
    ],
    "type": "object",
    "properties": {
        "status": {
            "type": "string",
            "description": "Always \"committed\"."
        },
        "name": {
            "type": "string",
            "description": "The group/settings object the commit touched."
        },
        "committedUtc": {
            "type": "string",
            "description": "UTC timestamp the new configuration version became active.",
            "format": "date-time",
            "nullable": true
        },
        "restartRequired": {
            "type": "boolean",
            "description": "True — CGN builds its allocators from config at startup, so the\n    change only takes full effect after a control-plane restart."
        }
    },
    "description": "Result of a CGN configuration commit. The CGN section is restart-required, so\n    bool CgnCommitResultDto.RestartRequired is always true.",
    "example": {
        "status": "committed",
        "name": "cgn-public-a",
        "committedUtc": "2026-08-03T10:24:11Z",
        "restartRequired": true
    }
}

application/problem+jsonapplication/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"
    }
}

Schema of the response body

application/problem+jsonapplication/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"
    }
}

Schema of the response body

application/problem+jsonapplication/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"
    }
}

Schema of the response body

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

---

PUT /api/v1/cgn/groups/{name}

Update a CGN IP group.

Description

Full-replace semantics (the name in the URL is the immutable key). While the group carries live bindings, structural fields (chunk size, public subnets, outside VRF) cannot change — drain the pool first; cosmetic fields (description, timeouts, caps) can. Restart-required like create. 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.
name	path	string		No	The IP group to update.

Request body

application/json

{
    "name": "cgn-public-a",
    "description": "Residential CGN pool",
    "outsideVrf": "internet",
    "publicSubnets": [
        "45.84.200.0/24"
    ],
    "chunkSize": 512,
    "portCap": 4096,
    "setupsPerSec": 200,
    "bindingTimeoutSeconds": 300,
    "quarantineSeconds": 120,
    "bypassPrefixes": [
        "100.64.0.0/10"
    ],
    "autoLearn": [
        {
            "insideVrf": "residential",
            "prefixes": [
                "100.64.0.0/12"
            ]
        }
    ],
    "timeouts": {
        "tcpEstablished": 7440,
        "tcpTransitory": 240,
        "udp": 300,
        "icmp": 60
    }
}

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

Schema of the request body

{
    "required": [
        "name",
        "description",
        "outsideVrf",
        "publicSubnets",
        "chunkSize",
        "portCap",
        "setupsPerSec",
        "bindingTimeoutSeconds",
        "quarantineSeconds",
        "bypassPrefixes",
        "autoLearn",
        "timeouts"
    ],
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "description": "Group name — the immutable key (service plans reference it)."
        },
        "description": {
            "type": "string",
            "description": "Free-text description.",
            "nullable": true
        },
        "outsideVrf": {
            "type": "string",
            "description": "VRF holding the public side (null/empty = default table).",
            "nullable": true
        },
        "publicSubnets": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "description": "Public IPv4 subnets (CIDR) the group allocates from.",
            "nullable": true
        },
        "chunkSize": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Ports per allocated port block.",
            "format": "int32"
        },
        "portCap": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Maximum ports one subscriber may hold before extensions stop.",
            "format": "int32"
        },
        "setupsPerSec": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Per-subscriber NAT setup rate limit.",
            "format": "int32"
        },
        "bindingTimeoutSeconds": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Idle teardown for auto-learned bindings.",
            "format": "int32"
        },
        "quarantineSeconds": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Quarantine before a freed port block is reused.",
            "format": "int32"
        },
        "bypassPrefixes": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "description": "Destinations that bypass NAT (CIDR).",
            "nullable": true
        },
        "autoLearn": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/CgnAutoLearn"
            },
            "description": "Auto-learn scopes (inside VRF + prefixes).",
            "nullable": true
        },
        "timeouts": {
            "oneOf": [
                {
                    "nullable": true
                },
                {
                    "$ref": "#/components/schemas/CgnTimeouts"
                }
            ]
        }
    },
    "description": "Request body for CGN IP group create/update.",
    "example": {
        "name": "cgn-public-a",
        "description": "Residential CGN pool",
        "outsideVrf": "internet",
        "publicSubnets": [
            "45.84.200.0/24"
        ],
        "chunkSize": 512,
        "portCap": 4096,
        "setupsPerSec": 200,
        "bindingTimeoutSeconds": 300,
        "quarantineSeconds": 120,
        "bypassPrefixes": [
            "100.64.0.0/10"
        ],
        "autoLearn": [
            {
                "insideVrf": "residential",
                "prefixes": [
                    "100.64.0.0/12"
                ]
            }
        ],
        "timeouts": {
            "tcpEstablished": 7440,
            "tcpTransitory": 240,
            "udp": 300,
            "icmp": 60
        }
    }
}

Responses

200 OK400 Bad Request409 Conflict422 Unprocessable Content401 Unauthorized403 Forbidden

application/json

{
    "status": "committed",
    "name": "cgn-public-a",
    "committedUtc": "2026-08-03T10:24:11Z",
    "restartRequired": true
}

Schema of the response body

{
    "required": [
        "status",
        "name",
        "committedUtc",
        "restartRequired"
    ],
    "type": "object",
    "properties": {
        "status": {
            "type": "string",
            "description": "Always \"committed\"."
        },
        "name": {
            "type": "string",
            "description": "The group/settings object the commit touched."
        },
        "committedUtc": {
            "type": "string",
            "description": "UTC timestamp the new configuration version became active.",
            "format": "date-time",
            "nullable": true
        },
        "restartRequired": {
            "type": "boolean",
            "description": "True — CGN builds its allocators from config at startup, so the\n    change only takes full effect after a control-plane restart."
        }
    },
    "description": "Result of a CGN configuration commit. The CGN section is restart-required, so\n    bool CgnCommitResultDto.RestartRequired is always true.",
    "example": {
        "status": "committed",
        "name": "cgn-public-a",
        "committedUtc": "2026-08-03T10:24:11Z",
        "restartRequired": true
    }
}

application/problem+jsonapplication/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"
    }
}

Schema of the response body

application/problem+jsonapplication/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"
    }
}

Schema of the response body

application/problem+jsonapplication/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"
    }
}

Schema of the response body

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

---

DELETE /api/v1/cgn/groups/{name}

Delete a CGN IP group.

Description

Refused while the group carries live bindings (a restart with subscribers still mapped through the pool would strand their NAT state). Restart-required like create. 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.
name	path	string		No	The IP group to delete.

Responses

200 OK400 Bad Request409 Conflict422 Unprocessable Content401 Unauthorized403 Forbidden

application/json

{
    "status": "committed",
    "name": "cgn-public-a",
    "committedUtc": "2026-08-03T10:24:11Z",
    "restartRequired": true
}

Schema of the response body

{
    "required": [
        "status",
        "name",
        "committedUtc",
        "restartRequired"
    ],
    "type": "object",
    "properties": {
        "status": {
            "type": "string",
            "description": "Always \"committed\"."
        },
        "name": {
            "type": "string",
            "description": "The group/settings object the commit touched."
        },
        "committedUtc": {
            "type": "string",
            "description": "UTC timestamp the new configuration version became active.",
            "format": "date-time",
            "nullable": true
        },
        "restartRequired": {
            "type": "boolean",
            "description": "True — CGN builds its allocators from config at startup, so the\n    change only takes full effect after a control-plane restart."
        }
    },
    "description": "Result of a CGN configuration commit. The CGN section is restart-required, so\n    bool CgnCommitResultDto.RestartRequired is always true.",
    "example": {
        "status": "committed",
        "name": "cgn-public-a",
        "committedUtc": "2026-08-03T10:24:11Z",
        "restartRequired": true
    }
}

application/problem+jsonapplication/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"
    }
}

Schema of the response body

application/problem+jsonapplication/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"
    }
}

Schema of the response body

application/problem+jsonapplication/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"
    }
}

Schema of the response body

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

---

GET /api/v1/cgn/settings

Read the section-level CGN settings.

Description

The configured (not necessarily running) values. Fleet-proxyable.

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

{
    "enabled": true,
    "maxBindings": 65536,
    "maxFlows": 2097152,
    "loggerSpoolSize": 16384
}

Schema of the response body

{
    "required": [
        "enabled",
        "maxBindings",
        "maxFlows",
        "loggerSpoolSize"
    ],
    "type": "object",
    "properties": {
        "enabled": {
            "type": "boolean",
            "description": "Whether CGN activates at control-plane start."
        },
        "maxBindings": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Global cap on concurrent NAT bindings (table size).",
            "format": "int32"
        },
        "maxFlows": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Global cap on concurrent NAT flows (table size).",
            "format": "int32"
        },
        "loggerSpoolSize": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Compliance-logger spool size (events buffered per driver).",
            "format": "int32"
        }
    },
    "description": "Section-level CGN settings (also the PUT body).",
    "example": {
        "enabled": true,
        "maxBindings": 65536,
        "maxFlows": 2097152,
        "loggerSpoolSize": 16384
    }
}

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

---

PUT /api/v1/cgn/settings

Update the section-level CGN settings.

Description

Commits through the configuration store; restart-required (the tables are sized at startup). 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

application/json

{
    "enabled": true,
    "maxBindings": 65536,
    "maxFlows": 2097152,
    "loggerSpoolSize": 16384
}

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

Schema of the request body

{
    "required": [
        "enabled",
        "maxBindings",
        "maxFlows",
        "loggerSpoolSize"
    ],
    "type": "object",
    "properties": {
        "enabled": {
            "type": "boolean",
            "description": "Whether CGN activates at control-plane start."
        },
        "maxBindings": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Global cap on concurrent NAT bindings (table size).",
            "format": "int32"
        },
        "maxFlows": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Global cap on concurrent NAT flows (table size).",
            "format": "int32"
        },
        "loggerSpoolSize": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Compliance-logger spool size (events buffered per driver).",
            "format": "int32"
        }
    },
    "description": "Section-level CGN settings (also the PUT body).",
    "example": {
        "enabled": true,
        "maxBindings": 65536,
        "maxFlows": 2097152,
        "loggerSpoolSize": 16384
    }
}

Responses

200 OK400 Bad Request409 Conflict422 Unprocessable Content401 Unauthorized403 Forbidden

application/json

{
    "status": "committed",
    "name": "cgn-public-a",
    "committedUtc": "2026-08-03T10:24:11Z",
    "restartRequired": true
}

Schema of the response body

{
    "required": [
        "status",
        "name",
        "committedUtc",
        "restartRequired"
    ],
    "type": "object",
    "properties": {
        "status": {
            "type": "string",
            "description": "Always \"committed\"."
        },
        "name": {
            "type": "string",
            "description": "The group/settings object the commit touched."
        },
        "committedUtc": {
            "type": "string",
            "description": "UTC timestamp the new configuration version became active.",
            "format": "date-time",
            "nullable": true
        },
        "restartRequired": {
            "type": "boolean",
            "description": "True — CGN builds its allocators from config at startup, so the\n    change only takes full effect after a control-plane restart."
        }
    },
    "description": "Result of a CGN configuration commit. The CGN section is restart-required, so\n    bool CgnCommitResultDto.RestartRequired is always true.",
    "example": {
        "status": "committed",
        "name": "cgn-public-a",
        "committedUtc": "2026-08-03T10:24:11Z",
        "restartRequired": true
    }
}

application/problem+jsonapplication/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"
    }
}

Schema of the response body

application/problem+jsonapplication/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"
    }
}

Schema of the response body

application/problem+jsonapplication/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"
    }
}

Schema of the response body

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

---

GET /api/v1/cgn/status

CG-NAT status: configuration, live binding counts, and counters.

Description

Merges the configured CGN section (enabled flag, limits, IP groups) with live state: binding counts, per-group pool utilisation, native data-plane counters, and compliance-logger loss counters. running: false means CGN is configured but not active in this control-plane process (it activates at startup) — the config half still renders. Fleet-proxyable.

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

{
    "enabled": true,
    "running": true,
    "maxBindings": 65536,
    "maxFlows": 2097152,
    "activeBindings": 1842,
    "autoLearnedBindings": 37,
    "groups": [
        {
            "name": "cgn-public-a",
            "description": "Residential CGN pool",
            "outsideVrf": "internet",
            "publicSubnets": [
                "45.84.200.0/24"
            ],
            "chunkSize": 512,
            "portCap": 4096,
            "setupsPerSec": 200,
            "bindingTimeoutSeconds": 300,
            "quarantineSeconds": 120,
            "bypassPrefixes": [
                "100.64.0.0/10"
            ],
            "autoLearn": [
                {
                    "insideVrf": "residential",
                    "prefixes": [
                        "100.64.0.0/12"
                    ]
                }
            ],
            "timeouts": {
                "tcpEstablished": 7440,
                "tcpTransitory": 240,
                "udp": 300,
                "icmp": 60
            },
            "activeBindings": 1842,
            "utilisation": {
                "totalChunks": 9000,
                "freeChunks": 712,
                "usedChunks": 8192,
                "quarantinedChunks": 96
            }
        }
    ],
    "nativeCounters": {
        "autolearnMisses": 18342,
        "noMapping": 407,
        "extensionWanted": 1265,
        "eventRingDrops": 0
    },
    "eventsLostByDriver": {
        "syslog": 0
    }
}

Schema of the response body

{
    "required": [
        "enabled",
        "running",
        "maxBindings",
        "maxFlows",
        "activeBindings",
        "autoLearnedBindings",
        "groups",
        "nativeCounters",
        "eventsLostByDriver"
    ],
    "type": "object",
    "properties": {
        "enabled": {
            "type": "boolean",
            "description": "Whether CGN is enabled in configuration."
        },
        "running": {
            "type": "boolean",
            "description": "Whether CGN is active in this control-plane process (activates at startup)."
        },
        "maxBindings": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Configured global cap on concurrent NAT bindings.",
            "format": "int32"
        },
        "maxFlows": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Configured global cap on concurrent NAT flows.",
            "format": "int32"
        },
        "activeBindings": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Live NAT bindings right now (0 when not running).",
            "format": "int32"
        },
        "autoLearnedBindings": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "How many of the live bindings were auto-learned.",
            "format": "int32"
        },
        "groups": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/CgnGroup"
            },
            "description": "The configured IP groups merged with live utilisation."
        },
        "nativeCounters": {
            "$ref": "#/components/schemas/CgnNativeCounters"
        },
        "eventsLostByDriver": {
            "type": "object",
            "additionalProperties": {
                "pattern": "^-?(?:0|[1-9]\\d*)$",
                "format": "int64"
            },
            "description": "Compliance-log events lost per logger driver (null when the\n    logger pump isn't running).",
            "nullable": true
        }
    },
    "description": "GET /api/v1/cgn/status.",
    "example": {
        "enabled": true,
        "running": true,
        "maxBindings": 65536,
        "maxFlows": 2097152,
        "activeBindings": 1842,
        "autoLearnedBindings": 37,
        "groups": [
            {
                "name": "cgn-public-a",
                "description": "Residential CGN pool",
                "outsideVrf": "internet",
                "publicSubnets": [
                    "45.84.200.0/24"
                ],
                "chunkSize": 512,
                "portCap": 4096,
                "setupsPerSec": 200,
                "bindingTimeoutSeconds": 300,
                "quarantineSeconds": 120,
                "bypassPrefixes": [
                    "100.64.0.0/10"
                ],
                "autoLearn": [
                    {
                        "insideVrf": "residential",
                        "prefixes": [
                            "100.64.0.0/12"
                        ]
                    }
                ],
                "timeouts": {
                    "tcpEstablished": 7440,
                    "tcpTransitory": 240,
                    "udp": 300,
                    "icmp": 60
                },
                "activeBindings": 1842,
                "utilisation": {
                    "totalChunks": 9000,
                    "freeChunks": 712,
                    "usedChunks": 8192,
                    "quarantinedChunks": 96
                }
            }
        ],
        "nativeCounters": {
            "autolearnMisses": 18342,
            "noMapping": 407,
            "extensionWanted": 1265,
            "eventRingDrops": 0
        },
        "eventsLostByDriver": {
            "syslog": 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"
    }
}

---

Schemas

CgnAutoLearn

Name	Type	Description
insideVrf	string | null	Inside VRF the prefixes apply to (null = default table).
prefixes	Array<string>	Inside-subscriber prefixes eligible for auto-learned bindings.

CgnBindingRow

Name	Type	Description
autoLearned	boolean	True when the binding was auto-learned rather than session-driven.
bindingIndex		Stable index of the binding — the key for the identify endpoint.
chunkSize		Ports per block for this binding.
createdUtc	string(date-time)	UTC time the binding was created.
group	string	CGN IP group the public address came from.
insideIp	string	Subscriber's inside IPv4 address.
insideVrf	string	Inside VRF of the subscriber ("default" = global table).
portBlocks	Array<string>	Allocated port ranges, as "start-end" strings.
portCap		Port cap in force for this binding.
publicIp	string	Public IPv4 address the subscriber is translated to.
sessionId		Associated BNG session id (0 for anonymous auto-learned bindings).
subscriberId	string | null	Subscriber identity for compliance logging, or null if not identified.

CgnBindingsPage

Name	Type	Description
items	Array<CgnBindingRow>	The page of binding rows.
limit		The effective page size (after clamping).
offset		The offset this page was taken at.
running	boolean	Whether CGN is active in this control-plane process.
total		Bindings matching the filters (before paging).

CgnCommitResult

Name	Type	Description
committedUtc	string(date-time) | null	UTC timestamp the new configuration version became active.
name	string	The group/settings object the commit touched.
restartRequired	boolean	True — CGN builds its allocators from config at startup, so the change only takes full effect after a control-plane restart.
status	string	Always "committed".

CgnGroup

Name	Type	Description
activeBindings		Live bindings currently in this group.
autoLearn	Array<CgnAutoLearn>	Auto-learn scopes (inside VRF + prefixes).
bindingTimeoutSeconds		Idle teardown for auto-learned bindings.
bypassPrefixes	Array<string>	Destinations that bypass NAT (CIDR).
chunkSize		Ports per allocated port block.
description	string	Free-text description.
name	string	Group name (the key; service plans reference it).
outsideVrf	string | null	VRF holding the public side, or null for the default table.
portCap		Maximum ports one subscriber may hold.
publicSubnets	Array<string>	Public IPv4 subnets (CIDR) the group allocates from.
quarantineSeconds		Quarantine before a freed port block is reused.
setupsPerSec		Per-subscriber NAT setup rate limit.
timeouts	CgnTimeouts
utilisation

CgnGroupUtilisation

Name	Type	Description
freeChunks		Blocks free for allocation.
quarantinedChunks		Recently-freed blocks still in reuse quarantine.
totalChunks		Total port blocks in the pool.
usedChunks		Blocks currently allocated to subscribers.

CgnGroupWrite

Name	Type	Description
autoLearn	Array<CgnAutoLearn>	Auto-learn scopes (inside VRF + prefixes).
bindingTimeoutSeconds		Idle teardown for auto-learned bindings.
bypassPrefixes	Array<string>	Destinations that bypass NAT (CIDR).
chunkSize		Ports per allocated port block.
description	string | null	Free-text description.
name	string	Group name — the immutable key (service plans reference it).
outsideVrf	string | null	VRF holding the public side (null/empty = default table).
portCap		Maximum ports one subscriber may hold before extensions stop.
publicSubnets	Array<string>	Public IPv4 subnets (CIDR) the group allocates from.
quarantineSeconds		Quarantine before a freed port block is reused.
setupsPerSec		Per-subscriber NAT setup rate limit.
timeouts

CgnIdentifyBinding

Name	Type	Description
sessionId		BNG session id to associate, when known.
subscriberId	string | null	Subscriber identity for compliance logging (≤ 256 chars).

CgnNativeCounters

Name	Type	Description
autolearnMisses		Reverse-path misses eligible for auto-learn classification.
eventRingDrops		NAT events dropped because the event ring was full.
extensionWanted		Port-exhaustion events requesting an extension port block.
flowCapDrops		Creates refused by the dynamic per-binding flow cap.
mappingCapDrops		Creates refused because the mapping table was full.
noMapping		Packets to a configured public address dropped for lack of a mapping.

CgnSettings

Name	Type	Description
enabled	boolean	Whether CGN activates at control-plane start.
loggerSpoolSize		Compliance-logger spool size (events buffered per driver).
maxBindings		Global cap on concurrent NAT bindings (table size).
maxFlows		Global cap on concurrent NAT flows (table size).

CgnStatus

Name	Type	Description
activeBindings		Live NAT bindings right now (0 when not running).
autoLearnedBindings		How many of the live bindings were auto-learned.
enabled	boolean	Whether CGN is enabled in configuration.
eventsLostByDriver		Compliance-log events lost per logger driver (null when the logger pump isn't running).
groups	Array<CgnGroup>	The configured IP groups merged with live utilisation.
maxBindings		Configured global cap on concurrent NAT bindings.
maxFlows		Configured global cap on concurrent NAT flows.
nativeCounters	CgnNativeCounters
running	boolean	Whether CGN is active in this control-plane process (activates at startup).

CgnTimeouts

Name	Type	Description
icmp		Idle timeout for ICMP (echo) flows.
tcpEstablished		Idle timeout for established TCP flows.
tcpTransitory		Timeout for transitory TCP states (handshake/teardown).
udp		Idle timeout for UDP flows.

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
CGN	Carrier-grade NAT (NAT44): status, IP groups (public pools), live bindings, and binding identity enrichment.