GRE Circuits#

8 operations. Roles, error format and pagination are common to the whole API — see the REST API overview.

Authentication

Use a named bearer token. Every endpoint except POST /api/v1/auth/login, POST /api/v1/auth/enrol and GET /api/v1/system/health requires one. A super-user creates a token with POST /api/v1/auth/tokens; the plaintext (bngtok_…) is returned exactly once at creation and only a SHA-256 hash is stored on the appliance, so a lost token is replaced rather than recovered. Send it on every request:

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

GRE Circuits#

GET /api/v1/gre-circuits#

List the configured CPE circuits.

Description

Configuration only — see GET /api/v1/gre-circuits/status for live tunnel and BGP state. Optionally filtered to one customer VRF.

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.
`vrf`	query	string		No	Only circuits in this customer VRF.

Responses

200 OK401 Unauthorized403 Forbidden

application/json

[
    {
        "id": "string",
        "listenerId": "string",
        "vrf": "string",
        "remote": "string",
        "localTunnelAddress": "string",
        "remoteTunnelAddress": "string",
        "peerAsn": null,
        "description": "string",
        "maximumPrefix": null,
        "bfd": true,
        "key": null,
        "clampMss": true,
        "mtu": null
    }
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

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

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/gre-circuits/listeners#

List the shared local tunnel endpoints CPE circuits terminate on.

Description

Usually a single entry per box. Every circuit references one by id.

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

[
    {
        "id": "string",
        "localAddress": "string",
        "underlayInterface": "string",
        "ttl": null
    }
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

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

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/gre-circuits/listeners/{id}#

Create or replace a tunnel listener.

Description

The id in the URL is the key; an existing listener with that id is replaced. Changing a listener's local address re-provisions every circuit that references it.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`bearerToken`	header	string	N/A	No	Named API token — the recommended credential for automation. See Authentication in the API overview.
`id`	path	string		No	Listener id.

Request body

application/json

{
    "localAddress": "string",
    "underlayInterface": "string",
    "ttl": null
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

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

Schema of the request body

{
    "required": [
        "localAddress"
    ],
    "type": "object",
    "properties": {
        "localAddress": {
            "type": "string",
            "nullable": true
        },
        "underlayInterface": {
            "type": "string",
            "nullable": true
        },
        "ttl": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "format": "int32",
            "nullable": true
        }
    },
    "description": "Body for a listener write. Absent fields take their schema defaults."
}

Responses

200 OK409 Conflict422 Unprocessable Content401 Unauthorized403 Forbidden

application/json

{
    "status": "committed",
    "name": "residential",
    "committedUtc": "2026-08-03T10:24:11Z"
}

Schema of the response body

{
    "required": [
        "status",
        "name",
        "committedUtc"
    ],
    "type": "object",
    "properties": {
        "status": {
            "type": "string",
            "description": "Always \"committed\"."
        },
        "name": {
            "type": "string",
            "description": "The object the commit touched (VRF name, CGN group name, peer address, …)."
        },
        "committedUtc": {
            "type": "string",
            "description": "UTC timestamp the new configuration version became active.",
            "format": "date-time",
            "nullable": true
        }
    },
    "description": "Result of a successful configuration commit performed by a mutating endpoint.",
    "example": {
        "status": "committed",
        "name": "residential",
        "committedUtc": "2026-08-03T10:24:11Z"
    }
}

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/gre-circuits/listeners/{id}#

Delete a tunnel listener.

Description

Refused while circuits still reference it — those circuits would have no local endpoint to build a tunnel from, and config validation would reject the commit anyway.

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.
`id`	path	string		No	Listener id.

Responses

200 OK400 Bad Request401 Unauthorized403 Forbidden

application/json

{
    "status": "committed",
    "name": "residential",
    "committedUtc": "2026-08-03T10:24:11Z"
}

Schema of the response body

{
    "required": [
        "status",
        "name",
        "committedUtc"
    ],
    "type": "object",
    "properties": {
        "status": {
            "type": "string",
            "description": "Always \"committed\"."
        },
        "name": {
            "type": "string",
            "description": "The object the commit touched (VRF name, CGN group name, peer address, …)."
        },
        "committedUtc": {
            "type": "string",
            "description": "UTC timestamp the new configuration version became active.",
            "format": "date-time",
            "nullable": true
        }
    },
    "description": "Result of a successful configuration commit performed by a mutating endpoint.",
    "example": {
        "status": "committed",
        "name": "residential",
        "committedUtc": "2026-08-03T10:24:11Z"
    }
}

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/gre-circuits/status#

Live status of the configured circuits: tunnel state, BGP state, prefixes received.

Description

The declared circuits joined to ip link and vtysh output — the same data, from the same reporter, as show circuits and netavo-vpe --show circuits.

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.
`vrf`	query	string		No	Only circuits in this customer VRF.

Responses

200 OK503 Service Unavailable401 Unauthorized403 Forbidden

application/json

[
    {
        "id": "string",
        "vrf": "string",
        "device": "string",
        "remote": "string",
        "localTunnelAddress": "string",
        "remoteTunnelAddress": "string",
        "peerAsn": null,
        "description": "string",
        "tunnelState": "string",
        "rxBytes": null,
        "txBytes": null,
        "bgpState": "string",
        "bgpUptime": "string",
        "prefixesReceived": null
    }
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

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

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/gre-circuits/{id}#

Get one circuit's configuration.

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.
`id`	path	string		No	Circuit id (the SIM/site reference).

Responses

200 OK404 Not Found401 Unauthorized403 Forbidden

application/json

{
    "id": "string",
    "listenerId": "string",
    "vrf": "string",
    "remote": "string",
    "localTunnelAddress": "string",
    "remoteTunnelAddress": "string",
    "peerAsn": null,
    "description": "string",
    "maximumPrefix": null,
    "bfd": true,
    "key": null,
    "clampMss": true,
    "mtu": null
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "required": [
        "id",
        "listenerId",
        "vrf",
        "remote",
        "localTunnelAddress",
        "remoteTunnelAddress",
        "peerAsn"
    ],
    "type": "object",
    "properties": {
        "id": {
            "type": "string"
        },
        "listenerId": {
            "type": "string"
        },
        "vrf": {
            "type": "string"
        },
        "remote": {
            "type": "string"
        },
        "localTunnelAddress": {
            "type": "string"
        },
        "remoteTunnelAddress": {
            "type": "string"
        },
        "peerAsn": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "format": "uint32"
        },
        "description": {
            "type": "string",
            "nullable": true
        },
        "maximumPrefix": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "format": "uint32",
            "nullable": true
        },
        "bfd": {
            "type": "boolean",
            "default": false
        },
        "key": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "format": "uint32",
            "nullable": true
        },
        "clampMss": {
            "type": "boolean",
            "default": true
        },
        "mtu": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "format": "int32",
            "default": 0
        }
    },
    "description": "doc 40 §40.4: one CPE/SIM's GRE tunnel + the BGP session that runs inside it. Always 1:1, so\nmodeled as a single object rather than two lists (a tunnel-interface list and a BGP-peer list)\nan operator would otherwise have to keep address-matched by hand across ~250 entries — the same\nclass of drift risk string? GreTunnelListener.UnderlayInterface avoids, at 250x the\nsurface area.\n\nThis is ordinary PE-CE eBGP inside a plain GRE tunnel, NOT the remote-PE mechanism\nLocalInterfaceConfig's `gre` type implements (MPLS-in-GRE transport to a hub,\ncarrying vpn-only sessions). Nothing here is MPLS-capable and nothing here talks to the core."
}

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/gre-circuits/{id}#

Create or replace a CPE circuit.

Description

The id in the URL is the key (and what the kernel device name is derived from), so a PUT to an existing id edits that circuit in place rather than creating a second one. Committing re-provisions: the tunnel converges to the new endpoints and FRR picks up the neighbour, without touching the other circuits.

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.
`id`	path	string		No	Circuit id (the SIM/site reference).

Request body

application/json

{
    "listenerId": "string",
    "vrf": "string",
    "remote": "string",
    "localTunnelAddress": "string",
    "remoteTunnelAddress": "string",
    "peerAsn": null,
    "description": "string",
    "maximumPrefix": null,
    "bfd": true,
    "key": null,
    "clampMss": true,
    "mtu": null
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

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

Schema of the request body

{
    "type": "object",
    "properties": {
        "listenerId": {
            "type": "string",
            "nullable": true
        },
        "vrf": {
            "type": "string",
            "nullable": true
        },
        "remote": {
            "type": "string",
            "nullable": true
        },
        "localTunnelAddress": {
            "type": "string",
            "nullable": true
        },
        "remoteTunnelAddress": {
            "type": "string",
            "nullable": true
        },
        "peerAsn": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "format": "uint32",
            "nullable": true
        },
        "description": {
            "type": "string",
            "nullable": true
        },
        "maximumPrefix": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "format": "uint32",
            "nullable": true
        },
        "bfd": {
            "type": "boolean",
            "nullable": true
        },
        "key": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "format": "uint32",
            "nullable": true
        },
        "clampMss": {
            "type": "boolean",
            "nullable": true
        },
        "mtu": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "format": "int32",
            "nullable": true
        }
    },
    "description": "Body for a circuit write. On a PUT over an existing circuit, an absent field keeps\n            its current value, so a caller can flip one knob without restating the whole circuit."
}

Responses

200 OK409 Conflict422 Unprocessable Content401 Unauthorized403 Forbidden

application/json

{
    "status": "committed",
    "name": "residential",
    "committedUtc": "2026-08-03T10:24:11Z"
}

Schema of the response body

{
    "required": [
        "status",
        "name",
        "committedUtc"
    ],
    "type": "object",
    "properties": {
        "status": {
            "type": "string",
            "description": "Always \"committed\"."
        },
        "name": {
            "type": "string",
            "description": "The object the commit touched (VRF name, CGN group name, peer address, …)."
        },
        "committedUtc": {
            "type": "string",
            "description": "UTC timestamp the new configuration version became active.",
            "format": "date-time",
            "nullable": true
        }
    },
    "description": "Result of a successful configuration commit performed by a mutating endpoint.",
    "example": {
        "status": "committed",
        "name": "residential",
        "committedUtc": "2026-08-03T10:24:11Z"
    }
}

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/gre-circuits/{id}#

Delete a CPE circuit.

Description

Committing removes the kernel tunnel and de-configures the circuit's BGP neighbour (doc 40 §40.6a) — the other circuits' sessions stay established.

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.
`id`	path	string		No	Circuit id.

Responses

200 OK400 Bad Request401 Unauthorized403 Forbidden

application/json

{
    "status": "committed",
    "name": "residential",
    "committedUtc": "2026-08-03T10:24:11Z"
}

Schema of the response body

{
    "required": [
        "status",
        "name",
        "committedUtc"
    ],
    "type": "object",
    "properties": {
        "status": {
            "type": "string",
            "description": "Always \"committed\"."
        },
        "name": {
            "type": "string",
            "description": "The object the commit touched (VRF name, CGN group name, peer address, …)."
        },
        "committedUtc": {
            "type": "string",
            "description": "UTC timestamp the new configuration version became active.",
            "format": "date-time",
            "nullable": true
        }
    },
    "description": "Result of a successful configuration commit performed by a mutating endpoint.",
    "example": {
        "status": "committed",
        "name": "residential",
        "committedUtc": "2026-08-03T10:24:11Z"
    }
}

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

Schemas#

CommitResult#

Name	Type	Description
`committedUtc`	string(date-time) \| null	UTC timestamp the new configuration version became active.
`name`	string	The object the commit touched (VRF name, CGN group name, peer address, …).
`status`	string	Always "committed".

CpeCircuitStatus#

Name	Type	Description
`bgpState`	string
`bgpUptime`	string
`description`	string \| null
`device`	string
`id`	string
`localTunnelAddress`	string
`peerAsn`
`prefixesReceived`
`remote`	string
`remoteTunnelAddress`	string
`rxBytes`
`tunnelState`	string
`txBytes`
`vrf`	string

CpeGreCircuit#

Name	Type	Description
`bfd`	boolean
`clampMss`	boolean
`description`	string \| null
`id`	string
`key`
`listenerId`	string
`localTunnelAddress`	string
`maximumPrefix`
`mtu`
`peerAsn`
`remote`	string
`remoteTunnelAddress`	string
`vrf`	string

CpeGreCircuitWrite#

Name	Type	Description
`bfd`	boolean \| null
`clampMss`	boolean \| null
`description`	string \| null
`key`
`listenerId`	string \| null
`localTunnelAddress`	string \| null
`maximumPrefix`
`mtu`
`peerAsn`
`remote`	string \| null
`remoteTunnelAddress`	string \| null
`vrf`	string \| null

GreTunnelListener#

Name	Type	Description
`id`	string
`localAddress`	string
`ttl`
`underlayInterface`	string \| null

GreTunnelListenerWrite#

Name	Type	Description
`localAddress`	string \| null
`ttl`
`underlayInterface`	string \| null

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
GRE Circuits