Addresses seen on the network that Yagra does not monitor.
const url = 'https://example.com/api/v1/discovered-endpoints';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/discovered-endpoints \ --header 'Authorization: Bearer <token>'Built from what the monitored nodes report and what reaches Yagra on its own: ARP / IPv6
neighbour caches, LLDP and CDP neighbours that advertise a management address (phones and end
stations left out), OSPF neighbours and BGP peers, and syslog/trap senders that match no node.
evidence says which of those saw each one. The ARP half needs the ARP walk enabled (Settings ▸
System settings ▸ Discovery walks); the others are collected by default.
An endpoint only a syslog or trap sender vouches for has no observing node, so it is listed only to a caller whose scope is unrestricted.
summary.truncated_nodes > 0 means at least one router’s ARP cache exceeded its row budget and
the ARP half of this list is a sample, not a complete inventory of the segment.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Only rows whose representative observer (via_node, the lowest-id observing node) is
this node. A row this node also saw, but a lower-id node saw too, is not returned.
Include endpoints that have since become monitored nodes. Default false.
Responses
Section titled “Responses”One page of unmonitored endpoints, most recently seen first
One page of discovered endpoints, most recently seen first.
object
One address the fleet has resolved on the wire but does not monitor.
object
Where it was seen, ordered by source (ARP, LLDP, CDP, OSPF, BGP, syslog, trap) and capped at eight. Never empty.
One observation that made an address a candidate.
object
What the source said about the endpoint: its platform or system description (LLDP/CDP), or the hostname it put in its syslog messages. Device-supplied text.
The reporting node’s own port name, as its LLDP/CDP table names it.
What saw it.
The reporting node’s ifIndex, when the source names one.
The monitored node that reported it; null for a syslog or trap sender, which reported
itself.
When it was first seen anywhere in the fleet (RFC 3339).
The endpoint’s address.
When it was last confirmed still present (RFC 3339).
Its hardware address, lowercase colon-separated hex; null for an incomplete ARP entry.
The best name any source gave it: the LLDP system name, then the CDP device id, then the
hostname in its syslog messages. null when none did. Device-supplied text.
The node this address became, once it is monitored; null while it is still unmonitored.
The SNMP ifIndex it was resolved on — the port it is behind.
The row’s one representative observer: the lowest-id monitored node among its evidence
(every observer is listed in evidence). null when no monitored node saw it — a
syslog/trap sender only — or once that node has been deleted.
How much of the fleet’s ARP data this list was built from.
object
How many nodes have reported an ARP/ND cache at all.
Total endpoints observed across the fleet, before dedup and before the unmonitored filter.
How many of those hit a cap, making their contribution a sample rather than a total.
How many endpoints the caller can see that are still unmonitored, across every page.
Example
{ "endpoints": [ { "evidence": [ { "source": "arp" } ] } ]}Before_last_seen and before_id must be given together, and before_last_seen must be RFC 3339
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" }}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 View
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" }}Inventory storage is unavailable (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" }}