The derived connectivity graph: every link between monitored nodes, with the evidence that produced it.

GET

/api/v1/topology/links

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

Links are derived from CDP/LLDP adjacency and from nodes sharing an IP subnet; they are recomputed periodically rather than stored by hand. A group-scoped caller sees only links whose both endpoints are visible to them.

Authorizations

• bearer

Parameters

Query Parameters

cursor

integer | null format: int64

Return links with an id greater than this (the previous page’s next_cursor).

limit

integer | null format: int64

Maximum links to return.

Responses

200

One keyset page of the connectivity graph; next_cursor is null on the last page

Media typeapplication/json

One keyset page of the derived connectivity graph, with what the last derivation run saw.

object

derived_at

When the graph was last derived (RFC 3339), or null before the first run.

string | null

links

required

Array<object>

One undirected link in the derived connectivity graph.

object

a_if_name

Port name on the a side, when a source reported one.

string | null

a_ifindex

ifIndex on the a side, when a source reported one.

integer | null format: int32

a_node

One endpoint. null is reserved for an endpoint that is not a monitored node.

string | null format: uuid

b_if_name

Port name on the b side, when a source reported one.

string | null

b_ifindex

ifIndex on the b side, when a source reported one.

integer | null format: int32

b_node

The other endpoint. null is reserved for an endpoint that is not a monitored node.

string | null format: uuid

first_seen

required

When this link was first derived (RFC 3339).

string

forced_parent

The endpoint an operator declared upstream, when one was declared. null means the direction is worked out from how far each end is from a poller.

string | null format: uuid

id

required

Stable id, and the keyset cursor.

integer format: int64

last_seen

required

When it was last confirmed (RFC 3339).

string

source

required

The strongest of sources — what to label the link with.

string

Allowed values: manual lldp cdp ospf route bgp l3_subnet

sources

required

Every kind of evidence that produced this link.

Array<string>

Allowed values: manual lldp cdp ospf route bgp l3_subnet

subnet

The subnet behind a shared-subnet link, e.g. 192.168.1.0/24.

string | null

next_cursor

Pass back as cursor for the next page; null ⇒ this was the last one.

integer | null format: int64

summary

required

Counters for everything the last derivation declined to turn into a link.

object

ambiguous_mgmt_addrs

Adjacency rows whose management address matched more than one node, so no link could be attributed without guessing which.

integer format: int32

bgp_links

Links produced from a BGP peering session.

integer format: int32

bgp_peers_not_adjacent

BGP peers that matched a monitored node but sit on no network the reporting node terminates, so the session is not evidence of a link between them. The normal reading is iBGP between loopbacks; a number that stays at zero on a network running iBGP means the reporting node’s interface addresses have not been observed.

integer format: int32

cdp_links

Links produced from a CDP adjacency.

integer format: int32

duplicate_addresses

Addresses claimed by two or more nodes — a shared virtual IP, or a duplicate-address misconfiguration.

integer format: int32

l3_links

Links whose strongest evidence is shared-subnet membership.

integer format: int32

lldp_links

Links produced from an LLDP adjacency.

integer format: int32

ospf_links

Links produced from an OSPF neighbour relationship.

integer format: int32

oversized_segments

Segments with more than two members where no member could be identified as routing for the others, so no link was drawn.

integer format: int32

route_links

Links produced from a connected host route — the point-to-point links that share no subnet.

integer format: int32

subnet_prefix_mismatch

Addresses sharing network bits but disagreeing on prefix length.

integer format: int32

truncated_nodes

Nodes whose observation hit a per-node cap, so what is recorded for them is incomplete.

integer format: int32

unmatched_cdp_rows

CDP rows whose management address matched no monitored node.

integer format: int32

unmatched_lldp_rows

LLDP rows whose management address matched no monitored node.

integer format: int32

unmatched_routing_peers

Routing adjacencies whose peer address matched no monitored node.

integer format: int32

total_links

required

How many links the whole graph holds, not just this page.

integer format: int64

Example

{
  "links": [
    {
      "source": "manual",
      "sources": [
        "manual"
      ]
    }
  ]
}

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

Skeleton mode has no inventory to build the graph from

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