Addresses seen on the network that Yagra does not monitor.

GET

/api/v1/discovered-endpoints

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

Built from the ARP / IPv6-neighbour caches of the nodes that are monitored, so an endpoint appears here only if some monitored router has spoken to it. Requires the ARP walk to be enabled (Settings ▸ System settings ▸ Discovery walks); with it off the list is empty, which is an answer rather than an outage.

summary.truncated_nodes > 0 means at least one router’s cache exceeded its row budget and this list is a sample, not a complete inventory of the segment.

Authorizations

• bearer

Parameters

Query Parameters

limit

integer format: int64

via_node

string format: uuid

Only endpoints seen by this node.

include_promoted

boolean

Include endpoints that have since become monitored nodes. Default false.

before_last_seen

string

before_id

string format: uuid

Responses

200

One page of unmonitored endpoints, most recently seen first

Media typeapplication/json

One page of discovered endpoints, most recently seen first.

object

endpoints

required

Array<object>

One address the fleet has resolved on the wire but does not monitor.

object

first_seen

required

When it was first seen anywhere in the fleet (RFC 3339).

string

id

required

string format: uuid

ip

required

The endpoint’s address.

string

last_seen

required

When it was last confirmed still present (RFC 3339).

string

mac

Its hardware address, lowercase colon-separated hex; null for an incomplete ARP entry.

string | null

promoted_node_id

The node this address became, once it is monitored; null while it is still unmonitored.

string | null format: uuid

via_ifindex

The SNMP ifIndex it was resolved on — the port it is behind.

integer | null format: int32

via_node

Which monitored node resolved it; null once that node has been deleted.

string | null format: uuid

next

One of:

null

null

object

Pass back as before_last_seen+before_id; null ⇒ this was the last page.

object

id

required

string format: uuid

last_seen

required

string

summary

required

How much of the fleet’s ARP data this list was built from.

object

nodes_reporting

required

How many nodes have reported an ARP/ND cache at all.

integer format: int64

observed_total

required

Total endpoints observed across the fleet, before dedup and before the unmonitored filter.

integer format: int64

truncated_nodes

required

How many of those hit a cap, making their contribution a sample rather than a total.

integer format: int64

Example^generated

{
  "endpoints": [
    {
      "first_seen": "example",
      "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "ip": "example",
      "last_seen": "example",
      "mac": "example",
      "promoted_node_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "via_ifindex": 1,
      "via_node": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
    }
  ],
  "next": {
    "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "last_seen": "example"
  },
  "summary": {
    "nodes_reporting": 1,
    "observed_total": 1,
    "truncated_nodes": 1
  }
}

400

Before_last_seen and before_id must be given together, and before_last_seen must be RFC 3339

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

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

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