list_node_groups
const url = 'https://example.com/api/v1/node-groups';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://example.com/api/v1/node-groups \ --header 'Authorization: Bearer <token>'Authorizations
Section titled “Authorizations”Responses
Section titled “Responses”Every folder group in the inventory tree
One group row returned by the API. group_type is the snake_case key.
object
Where this group sits on the map after inheritance: its own coordinates, else the nearest ancestor’s, else null. Computed on every read; never stored.
These do not add a pin. A group is drawn on the map only when geo_source is own;
for every other group this says which pin its nodes are counted at (geo_group).
This folder’s labels plus every ancestor’s, minus its exclusions — what it effectively
carries, and therefore what everything beneath it inherits. Resolved on every read and
never stored, the same call effective_latitude/effective_longitude above make and for
the same reason.
🚨 Shipped resolved on the row, following geo rather than pool. pool is not
resolved here, and the cost of that is visible: web/src/lib/pool.ts has to re-walk the
folder tree client-side, carrying a warning that it is only safe for form previews. A
client walk is also wrong for a group-scoped caller, whose breadcrumb ancestors arrive as
names with their content cleared.
There is deliberately no tag_source beside this: unlike a pin or a pool, a label has no
single supplier, and the one question a screen asks — which of these are mine — is
effective_tags minus tags, on the row, with no walk.
The group that supplied the effective position: this group when geo_source is own, the
ancestor it inherited from when inherited, null when unset. This is the pin the group’s
nodes belong to, so a client never has to walk the folder tree itself.
Whether the effective position is the group’s own, inherited from an ancestor, or absent.
The group’s own geo coordinates, as stored (both set ⇒ drawn as a pin). A descendant
folder normally leaves these null and inherits — see the effective_* pair below.
Poll-pool this folder assigns to its nodes (ADR-009/020, migration 0054). null ⇒ inherit
from the nearest ancestor that sets one, else the default pool. A node’s own pool still
wins — see [crate::poolres].
The IP prefixes in use at this folder (ADR-100 decision 10, migration 0104). Empty for a folder nothing has attached one to, which is every folder in a deployment with no NetBox.
🚨 Empty also means “you may not see them”. [crate::api::groups::visible_groups]
clears this on a row a scoped caller receives only as a breadcrumb ancestor: such a row is
listed so the tree has a spine, and handing over the subnet layout of a site whose
membership the caller cannot see would be a leak the folder’s name does not constitute.
One IP prefix attached to a folder.
Three fields, and the third was added under the rule the original two were chosen by
(ADR-131 decision 9). NetBox’s prefix rows also carry status, vrf, is_pool, role and a
tenant, and none of them has a reader here — the bar for a field is a real reader, not
availability. source cleared that bar when two appeared at once: the range editor must not
offer to delete a row it cannot delete, and the folder detail pane says where a range came
from. It costs one column on a SELECT attach_prefixes already runs.
object
NetBox’s description of the range (“Matsuyama LAN”), or what the operator typed, or empty.
Canonical CIDR, e.g. "192.168.1.0/24". PostgreSQL’s cidr type rendered as text, so the
mask is always present — unlike inet, where a host address would print bare.
Whether an operator typed this row or a sync wrote it.
Manual order within the parent scope (the UI sorts siblings by this, then by name).
Labels stored on this folder (ADR-135 inc. 2, migration 0110). Every folder and node
beneath it carries them too — see effective_tags.
Labels this folder refuses to inherit from its own ancestors. Shown in full, including entries naming a label nothing currently supplies: an exclusion that cannot be seen cannot be undone.
Example
[ { "geo_source": "own", "origin": "meraki", "prefixes": [ { "source": "manual" } ] }]No valid bearer token
The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI
document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies
undescribed — a client that has to guess the failure shape ends up parsing the success shape and
reading undefined.
object
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}Role lacks the View permission
The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI
document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies
undescribed — a client that has to guess the failure shape ends up parsing the success shape and
reading undefined.
object
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}This core has no write side (skeleton mode)
The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI
document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies
undescribed — a client that has to guess the failure shape ends up parsing the success shape and
reading undefined.
object
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}