BGP Peers API

A BGP peer is the session through which Prelude TE receives BGP-LS NLRIs and reconstructs the network topology. After this first mention, the rest of this page refers to Prelude TE as "the engine". Every entity in the topology graph comes from one or more peer sessions, so the BGP Peers API is the ingress layer of the system. This page covers when to call the API, common mistakes, and a worked onboarding flow. For the full endpoint schema, see the API reference.

When to use this API

• Onboarding a new ingress point. Create a peer to start receiving BGP-LS NLRIs from a new router or route reflector.
• Operational changes. Tune hold-time, keepalive-time, or connect-retry, or toggle enabled to start and stop a session without losing its configuration.
• Decommissioning. Delete a peer when the upstream router is removed from the network so the engine stops attempting to connect.
• Audit and inventory. Scripted GET /api/bgp/peers snapshots feed compliance reports and topology change reviews.

Endpoints

Common pitfalls

• PUT is a full replace, not a patch. Fields omitted from the body are reset to their zero value. To change one field, fetch the peer first, mutate the field, then PUT the whole object back.
• Confusing enabled with state. enabled is your intent (the engine should run this session); state is the live FSM state reported by the engine (idle, connect, active, opensent, openconfirm, established). For live state, also see Health.
• Operational fields on create or update. Anything that the engine owns — state, messages-sent, messages-received, last-state-change, last-error — is ignored on input. Send only configuration fields and the engine will keep operational fields up to date.
• ASN encoding. user-peer-as accepts 2-byte plain, 4-byte plain, or dotted notation (65000.1). Pick one per environment and stick with it to keep diff tooling readable.
• Storing auth-password in plain text. The password is stored encrypted server-side but it still travels over the wire on create and update. Use HTTPS and treat the value as a secret.

Worked example: onboard a peer end to end

# 1. Create the peer (disabled, for review).
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "rr-paris-01",
        "description": "Route reflector — Paris core",
        "peer-address": "192.0.2.10",
        "user-peer-as": "65001",
        "hold-time": 180,
        "keepalive-time": 60,
        "connect-retry": 120,
        "enabled": false
      }' \
  https://te.example.com/api/bgp/peers
# 201 Created -> {"id":42, ...}

# 2. Enable the session once the upstream side is ready.
curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "rr-paris-01",
        "description": "Route reflector — Paris core",
        "peer-address": "192.0.2.10",
        "user-peer-as": "65001",
        "hold-time": 180,
        "keepalive-time": 60,
        "connect-retry": 120,
        "enabled": true
      }' \
  https://te.example.com/api/bgp/peers/42

# 3. Verify the session is established.
curl -H "Authorization: Bearer $TOKEN" \
  https://te.example.com/api/bgp/peers/42
# look for "state": "established"

Bruno: BGP Peers / Create peer, BGP Peers / Update peer, BGP Peers / Get peer

Once the session is established, the topology graph should populate within seconds. Confirm with the Topology API or the Topology view in the UI.

Reference

The full set of request fields, response shapes, validation errors, and CRUD ordering for clean teardown lives in the Bruno collection.

See also

• Concepts: Data flow
• BGP Peers / Peers
• BGP Peers / Authentication
• BGP Peers / Hold/Keepalive tuning
• Topology API
• Health API