---
title: "Unified entity-set endpoint for the topology view."
method: GET
path: "/api/v1/topology/data"
tags: ["Topologies", "internal"]
---

# Unified entity-set endpoint for the topology view.

`GET /api/v1/topology/data`

`?snapshot_id=<id>` resolves to the snapshot's `taken_at` and returns the
as-of-T entity set; otherwise returns live entities. The frontend
`TopologyTab` is the sole intended consumer.

## Query parameters

- `network_id` string, uuid, required
- `snapshot_id` string, uuid, nullable
- `mark_viewed` boolean, nullable

## Response `200`

Topology entity bundle

- ApiResponseTopologyData
  - `data` object — Bundle of entities that feed `build_graph` and the topology export pipeline. Loaded by [`crate::server::topology::service::main::TopologyService::get_topology_data`] for either the live view (`at = None`) or a point-in-time snapshot (`at = Some(taken_at)`). Replaces the entity-blob columns previously persisted on the topology row.
    - `bindings` Binding[], required
      - union
        - object — Association between a service and a port / interface that the service is listening on
          - `ip_address_id` string, uuid, required
          - `type` 'IPAddress', required
          - `network_id` string, uuid, required
          - `service_id` string, uuid, required
          - `created_at` string, date-time, required
          - `first_discovery_id` string, uuid, nullable
          - `id` string, uuid, required
          - `last_discovery_id` string, uuid, nullable
          - `last_seen_at` string, date-time
          - `lineage_id` string, uuid, nullable
          - `updated_at` string, date-time, required
          - `valid_from` string, date-time
          - `valid_to` string, date-time, nullable
        - object — Association between a service and a port / interface that the service is listening on
          - `ip_address_id` string, uuid, nullable, required — The IP address this port binding applies to. If `null`, the binding applies to all IP addresses on the host (and supersedes specific-IP-address bindings for this port).
          - `port_id` string, uuid, required
          - `type` 'Port', required
          - `network_id` string, uuid, required
          - `service_id` string, uuid, required
          - `created_at` string, date-time, required
          - `first_discovery_id` string, uuid, nullable
          - `id` string, uuid, required
          - `last_discovery_id` string, uuid, nullable
          - `last_seen_at` string, date-time
          - `lineage_id` string, uuid, nullable
          - `updated_at` string, date-time, required
          - `valid_from` string, date-time
          - `valid_to` string, date-time, nullable
    - `dependencies` Dependency[], required
      - `color` 'Pink' | 'Rose' | 'Red' | 'Amber' | 'Orange' | 'Green' | 'Emerald' | 'Teal' | 'Cyan' | 'Blue' | 'Indigo' | 'Purple' | 'Fuchsia' | 'Violet' | 'Sky' | 'Gray' | 'Lime' | 'Yellow', required
      - `dependency_type` 'RequestPath' | 'HubAndSpoke', required
      - `description` string, nullable
      - `edge_style` 'Straight' | 'SmoothStep' | 'Bezier', required
      - `members` union, required — The members of a dependency: either service-level or binding-level. Bindings are all-or-nothing: either every position has a binding (full L3 detail) or none do (Application-level only).
        - object — Application-level only. Ordered list of service IDs.
          - `service_ids` string[], required
          - `type` 'Services', required
        - object — Full L3 detail. Ordered list of binding IDs (one per service in the chain).
          - `binding_ids` string[], required
          - `type` 'Bindings', required
      - `name` string, required
      - `network_id` string, uuid, required
      - `source` union
        - object
          - `type` 'Manual', required
        - object
          - `type` 'System', required
        - object
          - `type` 'Discovery', required
        - object
          - `details` MatchDetails, required
            - `confidence` 'NotApplicable' | 'Low' | 'Medium' | 'High' | 'Certain', required
            - `reason` union, required — Match reason - either a simple reason string or a container with nested reasons
              - …
          - `type` 'DiscoveryWithMatch', required
        - object
          - `type` 'Unknown', required
      - `tags` string[], required
      - `created_at` string, date-time, required
      - `id` string, uuid, required
      - `lineage_id` string, uuid, nullable
      - `updated_at` string, date-time, required
      - `valid_from` string, date-time
      - `valid_to` string, date-time, nullable
    - `hosts` Host[], required
      - `chassis_id` string, nullable — LLDP lldpLocChassisId - globally unique device identifier for deduplication
      - `credential_assignments` CredentialAssignment[], required — Credential assignments for this host (hydrated from junction table).
        - `credential_id` string, uuid, required
        - `ip_address_ids` string[], nullable, required — Interface IDs to limit this credential to. None = all host ip_addresses.
      - `description` string, nullable, required
      - `hidden` boolean, required
      - `hostname` string, nullable, required
      - `management_url` string, nullable — URL for device management interface (manual or discovered)
      - `manufacturer` string, nullable — ENTITY-MIB entPhysicalMfgName - hardware manufacturer
      - `model` string, nullable — ENTITY-MIB entPhysicalModelName - hardware model
      - `name` string, required
      - `network_id` string, uuid, required
      - `serial_number` string, nullable — ENTITY-MIB entPhysicalSerialNum - hardware serial number
      - `source` union, required
        - object
          - `type` 'Manual', required
        - object
          - `type` 'System', required
        - object
          - `type` 'Discovery', required
        - object
          - `details` MatchDetails, required
            - `confidence` 'NotApplicable' | 'Low' | 'Medium' | 'High' | 'Certain', required
            - `reason` union, required — Match reason - either a simple reason string or a container with nested reasons
              - …
          - `type` 'DiscoveryWithMatch', required
        - object
          - `type` 'Unknown', required
      - `sys_contact` string, nullable — SNMP sysContact.0 - admin contact info
      - `sys_descr` string, nullable — SNMP sysDescr.0 - full system description
      - `sys_location` string, nullable — SNMP sysLocation.0 - physical location
      - `sys_name` string, nullable — SNMP sysName.0 - administratively-assigned hostname
      - `sys_object_id` string, nullable — SNMP sysObjectID.0 - vendor OID for device identification
      - `tags` string[], required
      - `virtualization` union, required
        - object
          - `details` ProxmoxVirtualization, required
            - `service_id` string, uuid, required
            - `vm_id` string, nullable
            - `vm_name` string, nullable
          - `type` 'Proxmox', required
        - object
          - `details` VCenterVirtualization, required
            - `service_id` string, uuid, required
            - `vm_id` string, nullable
            - `vm_name` string, nullable
          - `type` 'VCenter', required
        - object
          - `details` EsxiVirtualization, required
            - `service_id` string, uuid, required
            - `vm_id` string, nullable
            - `vm_name` string, nullable
          - `type` 'ESXi', required
      - `created_at` string, date-time, required
      - `first_discovery_id` string, uuid, nullable — Discovery (historical row) that first observed this entity. Set once (post-terminal); immutable thereafter via the `IS NULL` guard in `update_discovery_fks`.
      - `id` string, uuid, required
      - `last_discovery_id` string, uuid, nullable — Discovery (historical row) that last touched this entity. Populated post-terminal by the per-entity-service subscriber on `DiscoveryProcessed`. NULL until the first successful discovery session terminates after this row was created.
      - `last_seen_at` string, date-time — Last successful natural-key match by daemon discovery against this live row. Refreshed every scan, regardless of field changes.
      - `lineage_id` string, uuid, nullable — Lineage pointer on closed historical rows back to the live row whose state they capture. NULL on live rows.
      - `updated_at` string, date-time, required
      - `valid_from` string, date-time — SCD2: when this row version became live. Equal to `created_at` for rows that have never ridden a snapshot; advanced to the snapshot's `taken_at` for live rows after a network snapshot fires.
      - `valid_to` string, date-time, nullable — SCD2: when this row was closed by a snapshot. NULL = currently live.
    - `interfaces` Interface[], required
      - `admin_status` 'Up' | 'Down' | 'Testing', required — SNMP ifAdminStatus values per IF-MIB RFC 2863
      - `cdp_address` string, nullable — Remote management IP from CDP (cdpCacheAddress)
      - `cdp_device_id` string, nullable — Remote device ID from CDP (typically hostname, locally unique)
      - `cdp_platform` string, nullable — Remote platform from CDP (e.g., "Cisco IOS")
      - `cdp_port_id` string, nullable — Remote port ID from CDP
      - `fdb_macs` string[], nullable — Bridge FDB: learned MAC addresses on this switch port. Single-MAC ports can be resolved to neighbor links server-side. Multi-MAC ports indicate uplinks where LLDP/CDP is the better source.
      - `host_id` string, uuid, required
      - `if_alias` string, nullable — SNMP ifAlias - user-configured description
      - `if_descr` string, required — SNMP ifDescr - interface description (e.g., GigabitEthernet0/1)
      - `if_index` integer, required — SNMP ifIndex - stable identifier within device
      - `if_name` string, nullable — SNMP ifName - short interface name (e.g., Gi1/0/1)
      - `if_type` integer, required — SNMP ifType - IANAifType integer (6=ethernet, 24=loopback, etc.)
      - `ip_address_id` string, uuid, nullable — FK to IPAddress entity - this port's IP assignment (must be on same host). Old daemons send this as "interface_id".
      - `lldp_chassis_id` union — LLDP Chassis ID subtypes per IEEE 802.1AB. The chassis ID identifies the remote device. Different network equipment may use different subtypes depending on configuration and capabilities.
        - object — Subtype 1: Chassis component (e.g., backplane serial number)
          - `subtype` 'ChassisComponent', required
          - `value` string, required — Subtype 1: Chassis component (e.g., backplane serial number)
        - object — Subtype 2: Interface alias (ifAlias from IF-MIB)
          - `subtype` 'InterfaceAlias', required
          - `value` string, required — Subtype 2: Interface alias (ifAlias from IF-MIB)
        - object — Subtype 3: Port component (e.g., backplane port number)
          - `subtype` 'PortComponent', required
          - `value` string, required — Subtype 3: Port component (e.g., backplane port number)
        - object — Subtype 4: MAC address (most common)
          - `subtype` 'MacAddress', required
          - `value` string, required — Subtype 4: MAC address (most common)
        - object — Subtype 5: Network address (IP address stored as string)
          - `subtype` 'NetworkAddress', required
          - `value` string, required — Subtype 5: Network address (IP address stored as string)
        - object — Subtype 6: Interface name (ifName from IF-MIB)
          - `subtype` 'InterfaceName', required
          - `value` string, required — Subtype 6: Interface name (ifName from IF-MIB)
        - object — Subtype 7: Locally assigned (device-specific identifier)
          - `subtype` 'LocallyAssigned', required
          - `value` string, required — Subtype 7: Locally assigned (device-specific identifier)
      - `lldp_mgmt_addr` string, nullable — Remote management IP from LLDP neighbor (lldpRemManAddr)
      - `lldp_port_desc` string, nullable — Remote port description from LLDP neighbor (lldpRemPortDesc)
      - `lldp_port_id` union — LLDP Port ID subtypes per IEEE 802.1AB. The port ID identifies the specific port on the remote device.
        - object — Subtype 1: Interface alias (ifAlias from IF-MIB)
          - `subtype` 'InterfaceAlias', required
          - `value` string, required — Subtype 1: Interface alias (ifAlias from IF-MIB)
        - object — Subtype 2: Port component (e.g., backplane port number)
          - `subtype` 'PortComponent', required
          - `value` string, required — Subtype 2: Port component (e.g., backplane port number)
        - object — Subtype 3: MAC address
          - `subtype` 'MacAddress', required
          - `value` string, required — Subtype 3: MAC address
        - object — Subtype 4: Network address (IP address stored as string)
          - `subtype` 'NetworkAddress', required
          - `value` string, required — Subtype 4: Network address (IP address stored as string)
        - object — Subtype 5: Interface name (ifName from IF-MIB)
          - `subtype` 'InterfaceName', required
          - `value` string, required — Subtype 5: Interface name (ifName from IF-MIB)
        - object — Subtype 6: Agent circuit ID (used by some providers)
          - `subtype` 'AgentCircuitId', required
          - `value` string, required — Subtype 6: Agent circuit ID (used by some providers)
        - object — Subtype 7: Locally assigned (device-specific identifier)
          - `subtype` 'LocallyAssigned', required
          - `value` string, required — Subtype 7: Locally assigned (device-specific identifier)
      - `lldp_sys_desc` string, nullable — Remote system description from LLDP neighbor (lldpRemSysDesc) - platform info
      - `lldp_sys_name` string, nullable — Remote system name from LLDP neighbor (lldpRemSysName)
      - `mac_address` string, nullable — MAC address from SNMP ifPhysAddress - immutable once set
      - `native_vlan_id` string, uuid, nullable — Native/untagged VLAN entity ID on this port (resolved from Q-BRIDGE dot1qPvid)
      - `neighbor` union — Resolved LLDP/CDP neighbor connection. Represents the remote endpoint this port connects to, discovered via LLDP or CDP. The two variants are mutually exclusive and represent different resolution states.
        - object — Full resolution - the specific remote port was identified
          - `id` string, uuid, required — Full resolution - the specific remote port was identified
          - `type` 'Interface', required
        - object — Partial resolution - the remote device was identified but not the specific port
          - `id` string, uuid, required — Partial resolution - the remote device was identified but not the specific port
          - `type` 'Host', required
      - `network_id` string, uuid, required
      - `oper_status` 'Up' | 'Down' | 'Testing' | 'Unknown' | 'Dormant' | 'NotPresent' | 'LowerLayerDown', required — SNMP ifOperStatus values per IF-MIB RFC 2863
      - `speed_bps` integer, nullable — Interface speed from ifSpeed/ifHighSpeed in bits per second
      - `vlan_ids` string[], nullable — Tagged VLAN entity IDs on this port (resolved from Q-BRIDGE dot1qVlanCurrentEgressPorts)
      - `created_at` string, date-time, required
      - `first_discovery_id` string, uuid, nullable
      - `id` string, uuid, required
      - `last_discovery_id` string, uuid, nullable
      - `last_seen_at` string, date-time
      - `lineage_id` string, uuid, nullable
      - `updated_at` string, date-time, required
      - `valid_from` string, date-time
      - `valid_to` string, date-time, nullable
    - `ip_addresses` IPAddress[], required
      - `host_id` string, uuid, required
      - `ip_address` string, required
      - `mac_address` string, nullable — MAC address discovered from ARP, SNMP, or Docker - immutable once set
      - `name` string, nullable, required
      - `network_id` string, uuid, required
      - `position` integer — Position of this IP address in the host's IP address list (for ordering)
      - `subnet_id` string, uuid, required
      - `created_at` string, date-time, required
      - `first_discovery_id` string, uuid, nullable
      - `id` string, uuid, required
      - `last_discovery_id` string, uuid, nullable
      - `last_seen_at` string, date-time
      - `lineage_id` string, uuid, nullable
      - `updated_at` string, date-time, required
      - `valid_from` string, date-time
      - `valid_to` string, date-time, nullable
    - `ports` Port[], required
      - `number` integer, required
      - `protocol` 'Udp' | 'Tcp', required
      - `type` string — Auto-derived from number+protocol; optional on create
      - `host_id` string, uuid, required
      - `network_id` string, uuid, required
      - `created_at` string, date-time, required
      - `first_discovery_id` string, uuid, nullable
      - `id` string, uuid, required
      - `last_discovery_id` string, uuid, nullable
      - `last_seen_at` string, date-time
      - `lineage_id` string, uuid, nullable
      - `updated_at` string, date-time, required
      - `valid_from` string, date-time
      - `valid_to` string, date-time, nullable
    - `services` Service[], required
      - `bindings` Binding[], required
        - union
          - object — Association between a service and a port / interface that the service is listening on
            - `ip_address_id` string, uuid, required
            - `type` 'IPAddress', required
            - `network_id` string, uuid, required
            - `service_id` string, uuid, required
            - `created_at` string, date-time, required
            - `first_discovery_id` string, uuid, nullable
            - `id` string, uuid, required
            - `last_discovery_id` string, uuid, nullable
            - `last_seen_at` string, date-time
            - `lineage_id` string, uuid, nullable
            - `updated_at` string, date-time, required
            - `valid_from` string, date-time
            - `valid_to` string, date-time, nullable
          - object — Association between a service and a port / interface that the service is listening on
            - `ip_address_id` string, uuid, nullable, required — The IP address this port binding applies to. If `null`, the binding applies to all IP addresses on the host (and supersedes specific-IP-address bindings for this port).
            - `port_id` string, uuid, required
            - `type` 'Port', required
            - `network_id` string, uuid, required
            - `service_id` string, uuid, required
            - `created_at` string, date-time, required
            - `first_discovery_id` string, uuid, nullable
            - `id` string, uuid, required
            - `last_discovery_id` string, uuid, nullable
            - `last_seen_at` string, date-time
            - `lineage_id` string, uuid, nullable
            - `updated_at` string, date-time, required
            - `valid_from` string, date-time
            - `valid_to` string, date-time, nullable
      - `host_id` string, uuid, required
      - `name` string, required
      - `network_id` string, uuid, required
      - `position` integer, required — Position of this service in the host's service list (for ordering)
      - `service_definition` string, required
      - `source` union, required
        - object
          - `type` 'Manual', required
        - object
          - `type` 'System', required
        - object
          - `type` 'Discovery', required
        - object
          - `details` MatchDetails, required
            - `confidence` 'NotApplicable' | 'Low' | 'Medium' | 'High' | 'Certain', required
            - `reason` union, required — Match reason - either a simple reason string or a container with nested reasons
              - …
          - `type` 'DiscoveryWithMatch', required
        - object
          - `type` 'Unknown', required
      - `tags` string[], required
      - `virtualization` union
        - object
          - `details` DockerVirtualization, required
            - `compose_project` string, nullable
            - `container_id` string, nullable
            - `container_name` string, nullable
            - `service_id` string, uuid, required
          - `type` 'Docker', required
        - object
          - `details` PodmanVirtualization, required
            - `compose_project` string, nullable
            - `container_id` string, nullable
            - `container_name` string, nullable
            - `service_id` string, uuid, required
          - `type` 'Podman', required
      - `created_at` string, date-time, required
      - `first_discovery_id` string, uuid, nullable
      - `id` string, uuid, required
      - `last_discovery_id` string, uuid, nullable
      - `last_seen_at` string, date-time
      - `lineage_id` string, uuid, nullable
      - `updated_at` string, date-time, required
      - `valid_from` string, date-time
      - `valid_to` string, date-time, nullable
    - `subnets` Subnet[], required
      - `cidr` string, required
      - `description` string, nullable
      - `name` string, required
      - `network_id` string, uuid, required
      - `source` union, required
        - object
          - `type` 'Manual', required
        - object
          - `type` 'System', required
        - object
          - `type` 'Discovery', required
        - object
          - `details` MatchDetails, required
            - `confidence` 'NotApplicable' | 'Low' | 'Medium' | 'High' | 'Certain', required
            - `reason` union, required — Match reason - either a simple reason string or a container with nested reasons
              - …
          - `type` 'DiscoveryWithMatch', required
        - object
          - `type` 'Unknown', required
      - `subnet_type` 'Internet' | 'Remote' | 'Gateway' | 'VpnTunnel' | 'Dmz' | 'Lan' | 'WiFi' | 'IoT' | 'Guest' | 'DockerBridge' | 'MacVlan' | 'IpVlan' | 'Management' | 'Storage' | 'Loopback' | 'Unknown', required
      - `tags` string[], required
      - `virtualization` SubnetVirtualization — Docker bridge network — host-scoped, same CIDR on different hosts are distinct subnets.
        - `service_id` string, uuid, required — The Docker daemon service that owns this bridge network. Different Docker daemons on different hosts = distinct bridge subnets.
        - `type` 'Docker', required
      - `created_at` string, date-time, required
      - `first_discovery_id` string, uuid, nullable
      - `id` string, uuid, required
      - `last_discovery_id` string, uuid, nullable
      - `last_seen_at` string, date-time
      - `lineage_id` string, uuid, nullable
      - `updated_at` string, date-time, required
      - `valid_from` string, date-time
      - `valid_to` string, date-time, nullable
    - `tags` Tag[], required
      - `color` 'Pink' | 'Rose' | 'Red' | 'Amber' | 'Orange' | 'Green' | 'Emerald' | 'Teal' | 'Cyan' | 'Blue' | 'Indigo' | 'Purple' | 'Fuchsia' | 'Violet' | 'Sky' | 'Gray' | 'Lime' | 'Yellow', required
      - `description` string, nullable
      - `is_application` boolean
      - `name` string, required
      - `organization_id` string, uuid, required
      - `created_at` string, date-time, required
      - `id` string, uuid, required
      - `lineage_id` string, uuid, nullable
      - `updated_at` string, date-time, required
      - `valid_from` string, date-time
      - `valid_to` string, date-time, nullable
    - `vlans` Vlan[], required
      - `description` string, nullable
      - `name` string, required
      - `network_id` string, uuid, required
      - `organization_id` string, uuid, required
      - `source` union
        - object
          - `type` 'Manual', required
        - object
          - `type` 'System', required
        - object
          - `type` 'Discovery', required
        - object
          - `details` MatchDetails, required
            - `confidence` 'NotApplicable' | 'Low' | 'Medium' | 'High' | 'Certain', required
            - `reason` union, required — Match reason - either a simple reason string or a container with nested reasons
              - …
          - `type` 'DiscoveryWithMatch', required
        - object
          - `type` 'Unknown', required
      - `vlan_number` integer, required — The 802.1Q VLAN number (1-4094)
      - `created_at` string, date-time, required
      - `first_discovery_id` string, uuid, nullable
      - `id` string, uuid, required
      - `last_discovery_id` string, uuid, nullable
      - `last_seen_at` string, date-time
      - `lineage_id` string, uuid, nullable
      - `updated_at` string, date-time, required
      - `valid_from` string, date-time
      - `valid_to` string, date-time, nullable
  - `error` string, nullable
  - `meta` ApiMeta, required — API metadata included in all responses
    - `api_version` integer, required — API version (integer, increments on breaking changes)
    - `server_version` string, required — Server version (semver)
  - `success` boolean, required

## Other responses

- `403` — Access denied
- `404` — Snapshot not found

## Changes

- **2026-06-20** `cf0e0b2b8df7` — 2 breaking
  - added `subschema #2: Podman` to the `data/services/items/allOf[#/components/schemas/ServiceBase]/virtualization/oneOf[subschema #2: ServiceVirtualization]/` response property `oneOf` list for the response status `200`
  - added `subschema #2: VCenter, subschema #3: ESXi` to the `data/hosts/items/allOf[#/components/schemas/HostBase]/virtualization/oneOf[subschema #2: HostVirtualization]/` response property `oneOf` list for the response status `200`
- **2026-06-18** `b3b0d516977c` — 1 info
  - added the new optional `query` request parameter `mark_viewed`
- **2026-06-18** `4169a28d0625` — 1 warning
  - deleted the `query` request parameter `mark_viewed`
- **2026-06-17** `ce7fd0ef19ae` — 1 info
  - added the new optional `query` request parameter `mark_viewed`
- **2026-06-11** `c7bad4e3d772` — 1 info
  - endpoint added

[Full history](https://skmtc.dev/scanopy/apis/scanopy-api/changes/api/v1/topology/data/get.md)

---

[API](https://skmtc.dev/scanopy/apis/scanopy-api.md) · [All operations](https://skmtc.dev/scanopy/apis/scanopy-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/scanopy/scanopy-api/revisions/87fbc9fdb32c/schema)