Skip to content
Documentation Prelude Topology Engine 1.0.0

Topology API

Read the consolidated topology graph computed by Prelude TE — stats, per-domain export, individual nodes and links. When to use the API, common pitfalls, and a worked exploration flow.

The Topology API exposes the in-memory graph that Prelude TE reconstructs from BGP-LS NLRIs. After this first mention, the rest of this page refers to Prelude TE as "the engine". Every endpoint is read-only: the topology mutates as BGP-LS updates and withdraws arrive from peers, not in response to API calls. This page covers when to call the API, common mistakes, and a worked exploration flow. For the full endpoint schema, see the API reference.

When to use this API

  • Powering custom dashboards. A per-domain export feeds a UI that renders nodes, links, and prefixes outside Prelude TE.
  • One-shot extraction. Snapshot the graph for an audit, capacity model, or path-computation engine that does not consume the streaming output.
  • Operational diagnostics. GET /api/topology/stats is the cheapest signal that the engine is past startup and the data pipeline is moving — pair it with Health.
  • Drilling into a single entity. Use the per-node and per-link endpoints to inspect attributes the UI does not show by default, or to compare two snapshots in tooling.

Endpoints

Method Path Purpose
GET /api/topology/stats List domains plus per-domain counters and timestamps.
GET /api/topology Topology export for every domain.
GET /api/topology/domains/{domain} Topology export for one domain.
GET /api/topology/domains/{domain}/nodes/{safeId} Retrieve a single node by safe-id.
GET /api/topology/domains/{domain}/links/{safeId} Retrieve a single link by safe-id.

{domain} is the BGP-LS Instance Identifier — see Domains. {safeId} is a stable, URL-encoded identifier the engine assigns to each entity (the raw BGP-LS key contains characters that are awkward in a URL).

Common pitfalls

  • Treating the export as a stream. The Topology API is a snapshot at request time. For change events as they happen, use the Outputs API (NATS) and not a polling loop on /api/topology.
  • Pulling the full export when you only need stats. /api/topology/stats is constant-time; /api/topology walks every domain and serializes the entire graph. Use stats for dashboards, the full export only when you need the entities.
  • Hardcoding the domain. The list of domains is discovered from peer NLRIs, so it depends on what the peers advertise. Read it from /api/topology/stats rather than baking values into scripts.
  • Caching safe-id across upgrades. The format is stable within a release line; treat it as opaque and re-resolve from the parent domain export when a script restarts.

Worked example: explore a domain end to end

# 1. Discover the domains and pick one.
curl -H "Authorization: Bearer $TOKEN" \
  https://te.example.com/api/topology/stats
# {"domains":["100","200"], "stats": { "100": {...}, "200": {...} } }

# 2. Pull the full export for domain 100.
curl -H "Authorization: Bearer $TOKEN" \
  "https://te.example.com/api/topology/domains/100"
# {"domain":"100","nodes":[...],"links":[...],"prefixes":[...]}

# 3. Drill into a specific node identified above.
NODE_SAFE_ID="0000.0000.0001"   # pulled from the response of step 2
curl -H "Authorization: Bearer $TOKEN" \
  "https://te.example.com/api/topology/domains/100/nodes/$NODE_SAFE_ID"

Bruno: Topology / Get stats, Topology / Get domain, Topology / Get node, Topology / Get link

The Bruno collection chains these requests through the topologyDomain, topologyNode, and topologyLink variables, so you can run the whole folder without pasting values by hand.

Reference

NodeExport, LinkExport, and PrefixExport shapes — including the SR-MPLS, SRv6, and Flex-Algo attributes — are documented under Topology / Nodes, Topology / Links, and Topology / Prefixes. Run the corresponding Bruno request to inspect a live sample.

See also

Filtering by: