---
title: "Refresh topology data"
method: POST
path: "/api/v1/topology/{id}/refresh"
tags: ["Topologies", "internal"]
---

# Refresh topology data

`POST /api/v1/topology/{id}/refresh`

## Path parameters

- `id` string, uuid, required

## Request body

- TopologyRebuildRequest — Lightweight request type for topology rebuild/refresh operations. This type only includes the fields actually needed by the server - entity data (hosts, ip_addresses, services, etc.) is fetched fresh from the database. Using this instead of the full Topology dramatically reduces payload size for large networks (from MBs to KBs), fixing HTTP 413 errors.
  - `edges` Edge[] — Existing edges for reference during rebuild
    - union
      - object
        - `edge_type` 'SameHost', required
        - `host_id` string, uuid, required
        - `id` string, uuid, required
        - `is_multi_hop` boolean, required
        - `label` string, nullable, required
        - `source` string, uuid, required
        - `source_handle` 'Top' | 'Bottom' | 'Left' | 'Right', required
        - `target` string, uuid, required
        - `target_handle` 'Top' | 'Bottom' | 'Left' | 'Right', required
        - `view_config` union — Per-view configuration for an edge: disabled (not in this view) or active with properties
          - object — Edge is not available in this view
            - `type` 'disabled', required
          - object — Edge is active in this view with specific properties
            - `affects_layout` boolean, required — Whether ELK should use this edge for layout positioning
            - `default_visibility` 'visible' | 'hidden', required — Whether an edge is visible by default or hidden behind a toggle
            - `highlight_behavior` 'when_visible' | 'always' | 'never', required — Controls when an edge contributes to node highlighting on selection
            - `show_directionality` boolean, required — Whether this edge should show directional animation when highlighted
            - `stroke` 'solid' | 'dashed', required — Visual stroke style for an edge
            - `type` 'active', required
            - `will_target_container` boolean, required — Whether this edge should be elevated to target an accepting container instead of the element inside it
      - object
        - `edge_type` 'Hypervisor', required
        - `hypervisor_service_id` string, uuid, required
        - `id` string, uuid, required
        - `is_multi_hop` boolean, required
        - `label` string, nullable, required
        - `source` string, uuid, required
        - `source_handle` 'Top' | 'Bottom' | 'Left' | 'Right', required
        - `target` string, uuid, required
        - `target_handle` 'Top' | 'Bottom' | 'Left' | 'Right', required
        - `view_config` union — Per-view configuration for an edge: disabled (not in this view) or active with properties
          - object — Edge is not available in this view
            - `type` 'disabled', required
          - object — Edge is active in this view with specific properties
            - `affects_layout` boolean, required — Whether ELK should use this edge for layout positioning
            - `default_visibility` 'visible' | 'hidden', required — Whether an edge is visible by default or hidden behind a toggle
            - `highlight_behavior` 'when_visible' | 'always' | 'never', required — Controls when an edge contributes to node highlighting on selection
            - `show_directionality` boolean, required — Whether this edge should show directional animation when highlighted
            - `stroke` 'solid' | 'dashed', required — Visual stroke style for an edge
            - `type` 'active', required
            - `will_target_container` boolean, required — Whether this edge should be elevated to target an accepting container instead of the element inside it
      - object
        - `edge_type` 'ContainerRuntime', required
        - `host_id` string, uuid, required
        - `service_id` string, uuid, required
        - `id` string, uuid, required
        - `is_multi_hop` boolean, required
        - `label` string, nullable, required
        - `source` string, uuid, required
        - `source_handle` 'Top' | 'Bottom' | 'Left' | 'Right', required
        - `target` string, uuid, required
        - `target_handle` 'Top' | 'Bottom' | 'Left' | 'Right', required
        - `view_config` union — Per-view configuration for an edge: disabled (not in this view) or active with properties
          - object — Edge is not available in this view
            - `type` 'disabled', required
          - object — Edge is active in this view with specific properties
            - `affects_layout` boolean, required — Whether ELK should use this edge for layout positioning
            - `default_visibility` 'visible' | 'hidden', required — Whether an edge is visible by default or hidden behind a toggle
            - `highlight_behavior` 'when_visible' | 'always' | 'never', required — Controls when an edge contributes to node highlighting on selection
            - `show_directionality` boolean, required — Whether this edge should show directional animation when highlighted
            - `stroke` 'solid' | 'dashed', required — Visual stroke style for an edge
            - `type` 'active', required
            - `will_target_container` boolean, required — Whether this edge should be elevated to target an accepting container instead of the element inside it
      - object
        - `dependency_id` string, uuid, required
        - `edge_type` 'RequestPath', required
        - `source_id` string, uuid, required
        - `target_id` string, uuid, required
        - `id` string, uuid, required
        - `is_multi_hop` boolean, required
        - `label` string, nullable, required
        - `source` string, uuid, required
        - `source_handle` 'Top' | 'Bottom' | 'Left' | 'Right', required
        - `target` string, uuid, required
        - `target_handle` 'Top' | 'Bottom' | 'Left' | 'Right', required
        - `view_config` union — Per-view configuration for an edge: disabled (not in this view) or active with properties
          - object — Edge is not available in this view
            - `type` 'disabled', required
          - object — Edge is active in this view with specific properties
            - `affects_layout` boolean, required — Whether ELK should use this edge for layout positioning
            - `default_visibility` 'visible' | 'hidden', required — Whether an edge is visible by default or hidden behind a toggle
            - `highlight_behavior` 'when_visible' | 'always' | 'never', required — Controls when an edge contributes to node highlighting on selection
            - `show_directionality` boolean, required — Whether this edge should show directional animation when highlighted
            - `stroke` 'solid' | 'dashed', required — Visual stroke style for an edge
            - `type` 'active', required
            - `will_target_container` boolean, required — Whether this edge should be elevated to target an accepting container instead of the element inside it
      - object
        - `dependency_id` string, uuid, required
        - `edge_type` 'HubAndSpoke', required
        - `source_id` string, uuid, required
        - `target_id` string, uuid, required
        - `id` string, uuid, required
        - `is_multi_hop` boolean, required
        - `label` string, nullable, required
        - `source` string, uuid, required
        - `source_handle` 'Top' | 'Bottom' | 'Left' | 'Right', required
        - `target` string, uuid, required
        - `target_handle` 'Top' | 'Bottom' | 'Left' | 'Right', required
        - `view_config` union — Per-view configuration for an edge: disabled (not in this view) or active with properties
          - object — Edge is not available in this view
            - `type` 'disabled', required
          - object — Edge is active in this view with specific properties
            - `affects_layout` boolean, required — Whether ELK should use this edge for layout positioning
            - `default_visibility` 'visible' | 'hidden', required — Whether an edge is visible by default or hidden behind a toggle
            - `highlight_behavior` 'when_visible' | 'always' | 'never', required — Controls when an edge contributes to node highlighting on selection
            - `show_directionality` boolean, required — Whether this edge should show directional animation when highlighted
            - `stroke` 'solid' | 'dashed', required — Visual stroke style for an edge
            - `type` 'active', required
            - `will_target_container` boolean, required — Whether this edge should be elevated to target an accepting container instead of the element inside it
      - object — Physical link discovered via LLDP/CDP neighbor discovery
        - `edge_type` 'PhysicalLink', required
        - `protocol` 'LLDP' | 'CDP', required — Protocol that discovered the physical link between network devices
        - `source_entity_id` string, uuid, required
        - `target_entity_id` string, uuid, required
        - `id` string, uuid, required
        - `is_multi_hop` boolean, required
        - `label` string, nullable, required
        - `source` string, uuid, required
        - `source_handle` 'Top' | 'Bottom' | 'Left' | 'Right', required
        - `target` string, uuid, required
        - `target_handle` 'Top' | 'Bottom' | 'Left' | 'Right', required
        - `view_config` union — Per-view configuration for an edge: disabled (not in this view) or active with properties
          - object — Edge is not available in this view
            - `type` 'disabled', required
          - object — Edge is active in this view with specific properties
            - `affects_layout` boolean, required — Whether ELK should use this edge for layout positioning
            - `default_visibility` 'visible' | 'hidden', required — Whether an edge is visible by default or hidden behind a toggle
            - `highlight_behavior` 'when_visible' | 'always' | 'never', required — Controls when an edge contributes to node highlighting on selection
            - `show_directionality` boolean, required — Whether this edge should show directional animation when highlighted
            - `stroke` 'solid' | 'dashed', required — Visual stroke style for an edge
            - `type` 'active', required
            - `will_target_container` boolean, required — Whether this edge should be elevated to target an accepting container instead of the element inside it
  - `network_id` string, uuid, required — Network ID for authorization and data fetching
  - `nodes` Node[] — Existing nodes for position preservation during rebuild
    - union
      - object
        - `associated_service_definition` string, nullable — Service definition ID for logo rendering (e.g. "Docker", "Proxmox VE"). Used by Hypervisor and Stack subcontainers to show the service's logo.
        - `color` string, nullable — Display color name (set by graph builder from the source entity, e.g. subnet type)
        - `container_type` 'Subnet' | 'ServiceCategory' | 'Application' | 'Root' | 'Host' | 'NestedTag' | 'NestedServiceCategory' | 'Hypervisor' | 'ContainerRuntime' | 'Stack' | 'TrunkPort' | 'VLAN' | 'PortOpStatus'
        - `element_rule_id` string, uuid, nullable — ID of the element rule that created this container (for subcontainers like NestedTag, Hypervisor, etc.)
        - `entity_id` string, uuid, nullable — The entity this container represents (e.g. host ID for Host containers, subnet ID for Subnet containers). Used for ownership mapping on the frontend.
        - `icon` string, nullable — Display icon name (set by graph builder from the source entity, e.g. subnet type)
        - `node_type` 'Container', required
        - `parent_container_id` string, uuid, nullable
        - `will_accept_edges` boolean — When true, this container accepts edges with `will_target_container`, causing them to visually attach here instead of at elements inside.
        - `header` string, nullable
        - `id` string, uuid, required
        - `position` Ixy, required
          - `x` integer, required
          - `y` integer, required
        - `size` Uxy, required — 2D unsigned coordinate. Used for node positions and sizes. Element node sizes are computed by the frontend (elkjs); the backend sets `Uxy::default()` for element nodes.
          - `x` integer, required
          - `y` integer, required
      - object
        - `element_type` 'IPAddress', required
        - `ip_address_id` string, uuid, nullable
        - `subnet_id` string, uuid, required
        - `container_id` string, uuid
        - `host_id` string, uuid, required
        - `inline_groups` InlineGroup[] — Visual grouping metadata for services inlined on this element. Populated by element rules (e.g., Docker containers on a VM host get InlineGroups with Header/Member roles for dotted-border rendering).
          - `entity_id` string, uuid, required — The inlined entity's ID (e.g., service ID).
          - `group_id` string, uuid, required — Shared by all members of the visual group.
          - `role` 'Header' | 'Member', required — Role of an inlined entity within its visual group.
        - `node_type` 'Element', required
        - `header` string, nullable
        - `id` string, uuid, required
        - `position` Ixy, required
          - `x` integer, required
          - `y` integer, required
        - `size` Uxy, required — 2D unsigned coordinate. Used for node positions and sizes. Element node sizes are computed by the frontend (elkjs); the backend sets `Uxy::default()` for element nodes.
          - `x` integer, required
          - `y` integer, required
      - object
        - `element_type` 'Service', required
        - `container_id` string, uuid
        - `host_id` string, uuid, required
        - `inline_groups` InlineGroup[] — Visual grouping metadata for services inlined on this element. Populated by element rules (e.g., Docker containers on a VM host get InlineGroups with Header/Member roles for dotted-border rendering).
          - `entity_id` string, uuid, required — The inlined entity's ID (e.g., service ID).
          - `group_id` string, uuid, required — Shared by all members of the visual group.
          - `role` 'Header' | 'Member', required — Role of an inlined entity within its visual group.
        - `node_type` 'Element', required
        - `header` string, nullable
        - `id` string, uuid, required
        - `position` Ixy, required
          - `x` integer, required
          - `y` integer, required
        - `size` Uxy, required — 2D unsigned coordinate. Used for node positions and sizes. Element node sizes are computed by the frontend (elkjs); the backend sets `Uxy::default()` for element nodes.
          - `x` integer, required
          - `y` integer, required
      - object
        - `element_type` 'Host', required
        - `container_id` string, uuid
        - `host_id` string, uuid, required
        - `inline_groups` InlineGroup[] — Visual grouping metadata for services inlined on this element. Populated by element rules (e.g., Docker containers on a VM host get InlineGroups with Header/Member roles for dotted-border rendering).
          - `entity_id` string, uuid, required — The inlined entity's ID (e.g., service ID).
          - `group_id` string, uuid, required — Shared by all members of the visual group.
          - `role` 'Header' | 'Member', required — Role of an inlined entity within its visual group.
        - `node_type` 'Element', required
        - `header` string, nullable
        - `id` string, uuid, required
        - `position` Ixy, required
          - `x` integer, required
          - `y` integer, required
        - `size` Uxy, required — 2D unsigned coordinate. Used for node positions and sizes. Element node sizes are computed by the frontend (elkjs); the backend sets `Uxy::default()` for element nodes.
          - `x` integer, required
          - `y` integer, required
      - object
        - `element_type` 'Interface', required
        - `interface_id` string, uuid, required
        - `container_id` string, uuid
        - `host_id` string, uuid, required
        - `inline_groups` InlineGroup[] — Visual grouping metadata for services inlined on this element. Populated by element rules (e.g., Docker containers on a VM host get InlineGroups with Header/Member roles for dotted-border rendering).
          - `entity_id` string, uuid, required — The inlined entity's ID (e.g., service ID).
          - `group_id` string, uuid, required — Shared by all members of the visual group.
          - `role` 'Header' | 'Member', required — Role of an inlined entity within its visual group.
        - `node_type` 'Element', required
        - `header` string, nullable
        - `id` string, uuid, required
        - `position` Ixy, required
          - `x` integer, required
          - `y` integer, required
        - `size` Uxy, required — 2D unsigned coordinate. Used for node positions and sizes. Element node sizes are computed by the frontend (elkjs); the backend sets `Uxy::default()` for element nodes.
          - `x` integer, required
          - `y` integer, required
  - `options` TopologyOptions, required
    - `local` TopologyLocalOptions, required
      - `bundle_edges` boolean
      - `hide_edge_types` EdgeTypeDiscriminants[], required
      - `no_fade_edges` boolean, required
      - `show_minimap` boolean
      - `tag_filter` TopologyTagFilter — Filter settings for hiding entities by tag in topology visualization.
        - `hidden_host_tag_ids` string[] — Host tag IDs to hide (hosts with these tags will fade out)
        - `hidden_service_tag_ids` string[] — Service tag IDs to hide (services with these tags will be hidden from nodes)
        - `hidden_subnet_tag_ids` string[] — Subnet tag IDs to hide (subnets with these tags will fade out)
    - `request` TopologyRequestOptions, required
      - `container_rules` object
      - `element_rules` IdentifiedRuleElementRule[]
        - `id` string, uuid, required
        - `rule` union, required — Rules that organize nodes within a container into sub-groups.
          - object
            - `ByServiceCategory` object, required
              - …
          - object
            - `ByTag` object, required
              - …
          - 'ByHypervisor'
          - 'ByContainerRuntime'
          - 'ByStack'
          - 'ByTrunkPort' — Groups trunk ports (ports with tagged VLANs) into a "Trunk Ports" subcontainer. Higher priority than ByVLAN — prevents trunk ports from being grouped by VLAN.
          - 'ByVLAN' — Groups access ports by their native VLAN ID into per-VLAN subcontainers.
          - 'ByPortOpStatus' — Groups ports by operational status (Up, Down, etc.) into per-status subcontainers.
      - `hide_entities` object — Entity types hidden per view. Keyed by TopologyView, values are entity types (matching those declared as container/element/inline in the view's element_config). Hides every manifestation of the entity in that view — element nodes, container nodes, and inline rows on element cards. Supersedes the old `hide_ports` (L3-only, inline-only).
      - `hide_metadata_values` object — Generic per-(view, entity, filter) hide-set for metadata filters (Category, Virtualization, etc). Supersedes the old `hide_service_categories`; nested so JSON keys are strings all the way down.
      - `view` 'L2Physical' | 'L3Logical' | 'Workloads' | 'Application' — Which topology view is being rendered

## Response `200`

Topology refreshed

- ApiResponse
  - `data` TupleUnit — unresolved $ref
  - `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` — Topology not found

## Changes

- **2026-04-20** `f04499e2280f` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/scanopy/apis/scanopy-api/changes/api/v1/topology/:id/refresh/post.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/71cdaaff2425/schema)