get_site_prefix_gaps

GET

/api/v1/prefix-gaps

curl --request GET \
  --url https://example.com/api/v1/prefix-gaps \
  --header 'Authorization: Bearer <token>'

Authorizations

• bearer

Responses

200

For every site holding a device this caller may see, the subnets its devices carry that none of the IP prefixes filed in the site’s folder or beneath it contains, with why each is reported and whether an operator marked it as intentional. A site is the nearest folder of type Site above a device, else the device’s own folder; devices filed in no folder are one site

Media typeapplication/json

What Nodes ▸ Missing IP prefixes shows.

object

gaps_listed

required

Gaps listed in sites. Less than gaps_total when the answer was cut at 2,000.

integer format: int32

gaps_total

required

Gaps across every site, marked ones included.

integer format: int32

nodes_total

required

Devices across those sites.

integer format: int32

nodes_truncated

required

integer format: int32

nodes_with_addresses

required

Of those, how many have reported their addresses at all. No gaps is complete only when this equals nodes_total.

integer format: int32

sites

required

Every site holding a device this caller may see. Most unmarked gaps first, then by name.

Array<object>

One site’s answer.

object

gap_count

required

How many of its gaps nobody has marked as intentional. gaps may list fewer when the answer was cut.

integer format: int32

gaps

required

The unmarked gaps first, then the marked ones; inside each, by kind, then subnet - the folder pane’s order. So a cut answer drops marked gaps before unmarked ones.

Array<object>

One subnet a folder’s devices carry that its own ranges do not cover.

object

intentional

One of:

null

null

object

Set when an operator marked this gap as intentional on Nodes ▸ Missing IP prefixes (ADR-170 Inc.4). Always null on a folder’s own report, which is not read per site.

object

note

required

What the operator wrote when marking it; may be empty.

string

kind

required

Why a subnet is reported. Ordered by how directly it names something to fix in NetBox.

string

Allowed values: unregistered partial other_folder parent_only

node_count

required

How many distinct devices carry an address in this subnet.

integer format: int32

range

The range that contains it (parent_only, other_folder) or lies inside it (partial). null for unregistered, and when that range belongs to a folder this caller may not see — a folder’s subnet layout is not disclosed past its scope (ADR-014, ADR-100 decision 10).

string | null

range_group

The folder range belongs to, under the same rule.

string | null format: uuid

range_group_name

That folder’s name, under the same rule.

string | null

seen_on

required

Up to [SEEN_ON_MAX] of the places it was seen, ordered by device then port.

Array<object>

One place a subnet was seen: a device, the port it is configured on, and the address itself.

object

if_name

The port’s name when the interface inventory has one. Filled by the caller.

string | null

ifindex

required

integer format: int32

ip

required

string

node_id

required

string format: uuid

subnet

required

The subnet, as network/length.

string

intentional_count

required

How many of its gaps were marked as intentional.

integer format: int32

is_site

required

Whether the folder is of type Site. A device with no Site folder above it is compared against its own folder, which is then listed as a site with this false.

boolean

name

The folder’s name; null for the root.

string | null

nodes_total

required

Devices in the site. URL, DNS, Meraki and wireless-AP nodes report no interface addresses and are not counted.

integer format: int32

nodes_truncated

required

Of those, how many address lists were cut at the per-device cap.

integer format: int32

nodes_with_addresses

required

Of those, how many have reported their addresses at all.

integer format: int32

path

required

The folders above it, outermost first — only those this caller may see. The site’s own name is given even to a caller scoped below it: naming the folder above yours is the breadcrumb ADR-014 allows (groups::group_ancestors), and says nothing of what is in it.

Array<string>

prefixes

required

IP prefixes filed in the site’s folder or beneath it — only in folders this caller may see.

integer format: int32

site_id

The site’s folder. null is the root: every device filed in no folder, taken as one site.

string | null format: uuid

status

required

Where one site stands - the screen’s four tabs, in their order.

string

Allowed values: gaps clean intentional no_data

subnets_checked

required

Distinct subnets compared, covered ones included.

integer format: int32

subnets_checked

required

Subnets compared, summed over sites — one carried at two sites counts twice.

integer format: int32

Example

{
  "sites": [
    {
      "gaps": [
        {
          "kind": "unregistered"
        }
      ],
      "status": "gaps"
    }
  ]
}

401

No valid bearer token

Media typeapplication/json

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

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Role lacks the View permission

Media typeapplication/json

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

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

This core has no write side (skeleton mode)

Media typeapplication/json

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

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}