Reports

Get Topology Change Summary

GET /api/v1/reports/change-summary?area_id=<uuid>&period=24h
GET /api/v1/reports/change-summary?pi_id=<uuid>&period=7d
GET /api/v1/reports/change-summary?rd_id=<uuid>&period=30d
GET /api/v1/reports/change-summary?network_id=<uuid>&period=1h

Aggregates topology events by type over the specified period. Groups event type counts into structured categories (devices, links, stubs) with raw counts preserved.

Query parameters:

Response: 200 OK

{
  "period": {
    "from": "2026-02-23T08:00:00Z",
    "to": "2026-02-24T08:00:00Z"
  },
  "devices": { "added": 2, "removed": 1, "changed": 3 },
  "links": { "added": 5, "removed": 2, "state_changes": 8, "cost_changes": 1 },
  "stubs": { "added": 4, "removed": 1, "changed": 0 },
  "total_events": 27,
  "raw_counts": {
    "device_added": 2,
    "device_removed": 1,
    "device_flags_changed": 3,
    "link_added": 5,
    "link_removed": 2,
    "link_state_changed": 8,
    "link_cost_changed": 1,
    "stub_added": 4,
    "stub_removed": 1
  }
}

Error responses:

Get Congestion Trend Report

GET /api/v1/reports/congestion?area_id=<uuid>
GET /api/v1/reports/congestion?pi_id=<uuid>
GET /api/v1/reports/congestion?rd_id=<uuid>
GET /api/v1/reports/congestion?network_id=<uuid>

Identifies interfaces that have consistently exceeded a utilization threshold over a configurable time period. Uses hourly bucketed data from the utilization_history table (populated by the SNMP poller). Returns hotspots sorted by hours above threshold, with per-hour history for sparkline rendering.

Query parameters:

Response: 200 OK

{
  "hotspots": [
    {
      "interface_id": "uuid",
      "device_id": "uuid",
      "router_id": "10.0.0.1",
      "hostname": "rtr-core-01",
      "if_name": "Gi0/0/0",
      "speed_mbps": 1000,
      "max_utilization": 97.3,
      "avg_utilization": 82.1,
      "hours_above_threshold": 42,
      "total_hours": 168,
      "trend": "increasing",
      "history": [
        { "bucket_time": "2026-02-17T00:00:00Z", "max_util": 85.2 }
      ]
    }
  ],
  "summary": {
    "interfaces_checked": 64,
    "above_threshold": 3,
    "threshold": 80,
    "period": "7d"
  }
}

Notes:

Auth: Required (all roles).

Error responses:

GET /api/v1/lsdb?area_id=<uuid>
GET /api/v1/lsdb?pi_id=<uuid>
GET /api/v1/lsdb?rd_id=<uuid>
GET /api/v1/lsdb?network_id=<uuid>

Reconstructs the OSPF LSDB from existing topology tables (devices, interfaces, stub_networks, inter_area_route, asbr_entry, external_route). Returns summary counts and per-type LSA arrays.

Type-5/7 arrays retain stored advertisements excluded from ordinary route reports. Entries add area_id, current area_type, area_type_source (operator_declared for totally_stub/totally_nssa, otherwise unknown), optional reported_by_collector_id (existing last-writer attribution), and optional routing_exclusion: "type5_area_type_conflict". Absence of that reason only means the area filter permits the row, not proof of routability. Historical rows use the current area classification; deleted advertisements and SNMP rows discarded before storage cannot be reconstructed. Counts and truncation include excluded stored rows.

Query parameters:

Response: 200 OK

{
  "summary": {
    "router_lsas": 12,
    "network_lsas": 4,
    "summary_lsas": 28,
    "asbr_summaries": 2,
    "external_lsas": 15,
    "nssa_externals": 0,
    "total": 61
  },
  "router_lsas": [
    {
      "link_state_id": "10.0.0.1",
      "adv_router": "10.0.0.1",
      "hostname": "rtr-core-01",
      "is_abr": true,
      "is_asbr": false,
      "link_count": 4,
      "links": [
        { "type": "point_to_point", "link_id": "10.0.0.2", "link_data": "10.1.0.1", "metric": 10 },
        { "type": "stub", "link_id": "192.168.1.0", "link_data": "255.255.255.0", "metric": 1 }
      ],
      "header": {
        "seq_number": 2147483648,
        "ls_age": 45,
        "checksum": 12345,
        "options": 34,
        "updated_at": "2026-03-05T14:23:46.456Z"
      }
    }
  ],
  "network_lsas": [
    {
      "link_state_id": "10.1.0.1",
      "adv_router": "10.0.0.1",
      "network_mask": "255.255.255.252",
      "attached_routers": ["10.0.0.1", "10.0.0.2"],
      "header": {
        "seq_number": 2147483648,
        "ls_age": 120,
        "checksum": 56789,
        "options": 34,
        "updated_at": "2026-03-05T14:20:15.123Z"
      }
    }
  ],
  "summary_lsas": [
    {
      "link_state_id": "192.0.2.0",
      "adv_router": "10.0.0.1",
      "network_mask": "255.255.255.0",
      "metric": 100
    }
  ],
  "asbr_summaries": [
    {
      "link_state_id": "10.0.0.5",
      "adv_router": "10.0.0.1",
      "metric": 50
    }
  ],
  "external_lsas": [
    {
      "link_state_id": "0.0.0.0",
      "adv_router": "10.0.0.5",
      "network_mask": "0.0.0.0",
      "metric": 1,
      "metric_type": "E2",
      "forward_address": "0.0.0.0",
      "tag": 0
    }
  ],
  "nssa_externals": []
}

Notes:

GET /api/v1/isis-lsdb?area_id=<uuid>

Returns IS-IS LSP headers from the isis_lsp_header table for the IS-IS LSDB browser. Enriched with device hostnames resolved from system_id.

Query parameters:

Response: 200 OK

{
  "lsp_count": 3,
  "lsps": [
    {
      "lsp_id": "0100.0000.0001.00-00",
      "system_id": "0100.0000.0001",
      "pseudonode_id": 0,
      "fragment": 0,
      "seq_number": 42,
      "remaining_lifetime": 1100,
      "checksum": 12345,
      "overload_bit": false,
      "attached_bit": false,
      "is_type_bits": 3,
      "pdu_length": 350,
      "first_seen": "2026-03-15T10:00:00Z",
      "updated_at": "2026-03-15T14:30:00Z",
      "hostname": "rtr-core-01"
    }
  ]
}

Notes:

Auth: Required (all roles).

Error responses: