The node's current CDP/LLDP neighbours.

GET

/api/v1/nodes/{node_id}/neighbors

curl --request GET \
  --url https://example.com/api/v1/nodes/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/neighbors \
  --header 'Authorization: Bearer <token>'

404 means no walk has recorded anything for this node yet — the node may not be an SNMP device, may not speak either protocol, or may simply not have been walked since collection was enabled. It is distinct from a recorded empty set, which is a real answer meaning the device reports no neighbours.

Authorizations

• bearer

Parameters

Path Parameters

node_id

required

string format: uuid

Node id

Responses

200

The node’s current adjacency and how long it has held

Media typeapplication/json

A node’s current adjacency and how long it has held.

object

first_seen

required

When this exact set was first seen (RFC 3339).

string

last_seen

required

When it was last confirmed unchanged (RFC 3339).

string

neighbors

required

The adjacencies the node last reported.

object

neighbors

The adjacencies, canonically ordered.

Array<object>

One observed adjacency.

The first three string fields are the identity; everything below them is payload. Payload changes still append a history row (a peer that was reimaged is a real change on that port), but they never split one link into two records.

object

capabilities

What the peer says it is, normalized across both protocols.

Array<string>

Allowed values: router bridge switch wlan_ap phone host repeater cable_device igmp other

local_ifindex

The local ifIndex, when the protocol genuinely supplies one. CDP indexes its cache by ifIndex so this is exact; LLDP’s lldpLocPortNum is an arbitrary local index that only often equals ifIndex, so LLDP records leave this None rather than guess.

integer | null format: int32

local_port

required

The local port, as the device names it: LLDP renders lldpLocPortId by its subtype, CDP uses cdpInterfaceName. Falls back to port <n> / ifindex <n> when the naming table has no row, so the record still has an identity rather than being dropped.

string

proto

required

Which protocol reported this.

string

Allowed values: lldp cdp

remote_chassis

required

The peer’s chassis id, rendered by subtype: LLDP lldpRemChassisId, CDP cdpCacheDeviceId.

string

remote_mgmt_addr

The peer’s management address, from cdpCacheAddress for CDP and from lldpRemManAddrTable for LLDP. None when the peer advertised none.

string | null

remote_platform

cdpCachePlatform — the peer’s hardware/software platform string (CDP only).

string | null

remote_port

required

The peer’s port id, rendered by subtype: LLDP lldpRemPortId, CDP cdpCacheDevicePort.

string

remote_port_desc

lldpRemPortDesc — the peer’s own description of its port.

string | null

remote_sys_desc

lldpRemSysDesc.

string | null

remote_sys_name

lldpRemSysName. CDP has no separate system name (its device id serves both).

string | null

truncated

Whether [MAX_NEIGHBORS_PER_NODE] was hit and rows were dropped. Reported rather than silently swallowed — a truncated view that looks complete is worse than no view.

boolean

Example

{
  "neighbors": {
    "neighbors": [
      {
        "capabilities": [
          "router"
        ],
        "proto": "lldp"
      }
    ]
  }
}

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 View

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

404

No adjacency has been recorded for the node

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

Inventory storage is unavailable (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"
  }
}