---
title: "Internal endpoint for daemon discovery"
method: POST
path: "/api/v1/hosts/discovery"
tags: ["Hosts", "internal"]
---

# Internal endpoint for daemon discovery

`POST /api/v1/hosts/discovery`

Used by daemons to report discovered hosts. Accepts full entities with
pre-generated IDs. Uses upsert behavior to merge with existing hosts.

Tagged as "internal" - included in OpenAPI spec for client generation
but hidden from public documentation.

## Request body

- DiscoveryHostRequest — Request type for daemon discovery - accepts full entities with IDs. Used internally by daemons for host creation/upsert, NOT the external API. This supports the discovery workflow where daemons manage entity IDs. ## Backwards compatibility (daemons < v0.16.0) Pre-v0.16.0 daemons send the old field layout: - `interfaces` → IPAddress data (now `ip_addresses`) - `if_entries` → SNMP Interface data (now `interfaces`) The custom deserializer detects the old layout (missing `ip_addresses` field) and remaps fields automatically. This can be removed once all daemons are ≥ v0.16.0.
  - `host` Host, required — Base data for a Host entity (stored in database). Child entities (ip_addresses, ports, services) are stored in their own tables and queried by `host_id`. They are NOT stored on the host.
    - `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 — The credential this entity refers to.
      - `ip_address_ids` string[], nullable, required — Interface IDs to limit this credential to. None = all host ip_addresses.
    - `description` string, nullable, required — Free-text notes about the host.
    - `hidden` boolean, required — Whether the host is hidden from topology views.
    - `hostname` string, nullable, required — Hostname as resolved or reported by the host.
    - `management_url` string, uri, 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 — Human-facing name for the host. Always the best name known. Which rung of the naming ladder it came from is recorded separately in `name_source`, and only `apply_name` may write either.
    - `name_source` 'Unspecified' | 'Ip' | 'DetectedService' | 'Hostname' | 'Integration' | 'Manual' — Which rung of the naming ladder produced a host's display name, weakest first. Declaration order is the precedence order — `Ord` is derived from it, and that derive is the whole enforcement mechanism: a rung inserted at its rank propagates to every comparison, so there is no per-call-site precedence to keep in sync. Persisted as bare text (`Manual`, `Integration`, …) via `Display`/`FromStr`.
    - `network_id` string, uuid, required — The network this entity belongs to.
    - `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
            - object
              - …
            - object
              - …
        - `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 — Tags assigned to this entity.
    - `virtualization_metadata` union, required
      - object
        - `details` ProxmoxVirtualization, required
          - `vm_id` string, nullable — Proxmox VMID of the guest.
          - `vm_name` string, nullable — Guest name as configured in Proxmox.
        - `type` 'Proxmox', required
      - object
        - `details` VCenterVirtualization, required
          - `vm_id` string, nullable — vCenter managed object ID of the guest.
          - `vm_name` string, nullable — Guest name as configured in vCenter.
        - `type` 'VCenter', required
      - object
        - `details` EsxiVirtualization, required
          - `vm_id` string, nullable — ESXi identifier of the guest.
          - `vm_name` string, nullable — Guest name as configured on the ESXi host.
        - `type` 'ESXi', required
    - `virtualization_service_id` string, uuid, nullable, required — The service doing the virtualizing — the hypervisor this VM runs on. Its own column with a foreign key rather than a field inside [`HostVirtualization`]: a reference that no longer resolves now fails the write instead of surviving as a value nothing matches, and `ON DELETE SET NULL` clears it when the hypervisor service goes away (GH #650).
    - `created_at` string, date-time, required — When this record was first created.
    - `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 — Server-assigned unique identifier.
    - `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 — When this record was last modified.
    - `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.
  - `interface_data_complete` InterfaceDataComplete — Which groups of per-interface data the daemon read in full during a scan. Each group comes from its own SNMP walk, and a walk cut short by a timeout yields exactly the same empty result as a device that genuinely has nothing to report. Without knowing which happened, the server overwrote good data with NULL on every truncation — and for the neighbour fields that also dropped the row out of L2 resolution permanently, since the resolution filter requires a chassis id or CDP device id to be present. Every field defaults to `true`, so a daemon predating this behaves exactly as before: it reports everything as authoritative and the server overwrites.
    - `cdp` boolean — `cdp_device_id`, `cdp_port_id`, `cdp_platform`, `cdp_address`
    - `fdb` boolean — `fdb_macs`
    - `lldp` boolean — `lldp_chassis_id`, `lldp_port_id`, `lldp_sys_name`, `lldp_port_desc`, `lldp_mgmt_addr`, `lldp_sys_desc`
    - `vlan_membership` boolean — `native_vlan_id`, `vlan_ids`
  - `interfaces` Interface[] — SNMP interface entries (ifTable data) - optional, populated when SNMP is enabled.
    - `admin_status` 'Up' | 'Down' | 'Testing', required — SNMP ifAdminStatus values per IF-MIB RFC 2863
    - `cdp_address` string, nullable — Remote management IP from CDP (cdpCacheAddress). IPv4 or IPv6.
    - `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 — The host this entity belongs to.
    - `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). IPv4 or IPv6.
    - `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 — The network this entity belongs to.
    - `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 — When this record was first created.
    - `first_discovery_id` string, uuid, nullable — The discovery that first observed this entity.
    - `id` string, uuid, required — Server-assigned unique identifier.
    - `last_discovery_id` string, uuid, nullable — The most recent discovery that observed this entity.
    - `last_seen_at` string, date-time — When a discovery last observed this entity.
    - `lineage_id` string, uuid, nullable — Stable identifier shared by every revision of the same entity across its history.
    - `updated_at` string, date-time, required — When this record was last modified.
    - `valid_from` string, date-time — Start of the interval this revision was current for (SCD2 history).
    - `valid_to` string, date-time, nullable — End of the interval this revision was current for. `null` while it is the live revision.
  - `interfaces_complete` boolean — Whether `interfaces` is a complete, authoritative ifTable. When false (a partial SNMP walk cut short by timeout/error), the server must NOT prune interfaces missing from this scan — otherwise a transient partial walk tears down the host's L2 topology (#649). Daemons that predate this field omit it; it defaults to true so their behavior is unchanged.
  - `ip_addresses` IPAddress[], required — IP addresses observed on the host.
    - `host_id` string, uuid, required — The host this entity belongs to.
    - `ip_address` string, required — IPv4 or IPv6 address.
    - `mac_address` string, nullable — MAC address discovered from ARP, SNMP, or Docker - immutable once set
    - `name` string, nullable, required — Human-facing name for this IP address.
    - `network_id` string, uuid, required — The network this entity belongs to.
    - `position` integer — Position of this IP address in the host's IP address list (for ordering)
    - `subnet_id` string, uuid, required — The subnet this entity belongs to.
    - `created_at` string, date-time, required — When this record was first created.
    - `first_discovery_id` string, uuid, nullable — The discovery that first observed this entity.
    - `id` string, uuid, required — Server-assigned unique identifier.
    - `last_discovery_id` string, uuid, nullable — The most recent discovery that observed this entity.
    - `last_seen_at` string, date-time — When a discovery last observed this entity.
    - `lineage_id` string, uuid, nullable — Stable identifier shared by every revision of the same entity across its history.
    - `updated_at` string, date-time, required — When this record was last modified.
    - `valid_from` string, date-time — Start of the interval this revision was current for (SCD2 history).
    - `valid_to` string, date-time, nullable — End of the interval this revision was current for. `null` while it is the live revision.
  - `ports` Port[], required — Open ports observed on the host.
    - `number` integer, required — TCP or UDP port number
    - `protocol` 'Udp' | 'Tcp', required — Transport protocol the port is open on.
    - `type` 'Ssh' | 'Telnet' | 'DnsUdp' | 'DnsTcp' | 'Samba' | 'Nfs' | 'Ftp' | 'Ipp' | 'LdpTcp' | 'LdpUdp' | 'Ldap' | 'Ldaps' | 'Kerberos' | 'Snmp' | 'SnmpAlt' | 'Rdp' | 'Ntp' | 'Sip' | 'SipTls' | 'Rtsp' | 'Dhcp' | 'Http' | 'MySql' | 'PostgreSQL' | 'MongoDB' | 'Redis' | 'MsSql' | 'Docker' | 'DockerTls' | 'Kubernetes' | 'RabbitMqMgmt' | 'Cassandra' | 'Elasticsearch' | 'InfluxDb' | 'CouchDb' | 'Kafka' | 'Http3000' | 'Http5000' | 'Http8080' | 'Http8081' | 'Http8082' | 'Http8888' | 'Http9000' | 'Https' | 'Https8443' | 'Https9443' | 'Https10443' | 'Mqtt' | 'MqttTls' | 'AMQP' | 'AMQPTls' | 'Wireguard' | 'OpenVPN' | 'BACnet' | 'JetDirect' | 'Custom' — Well-known port identifier. Auto-derived from number+protocol, so it is optional on create.
    - `host_id` string, uuid, required — The host this entity belongs to.
    - `network_id` string, uuid, required — The network this entity belongs to.
    - `created_at` string, date-time, required — When this record was first created.
    - `first_discovery_id` string, uuid, nullable — The discovery that first observed this entity.
    - `id` string, uuid, required — Server-assigned unique identifier.
    - `last_discovery_id` string, uuid, nullable — The most recent discovery that observed this entity.
    - `last_seen_at` string, date-time — When a discovery last observed this entity.
    - `lineage_id` string, uuid, nullable — Stable identifier shared by every revision of the same entity across its history.
    - `updated_at` string, date-time, required — When this record was last modified.
    - `valid_from` string, date-time — Start of the interval this revision was current for (SCD2 history).
    - `valid_to` string, date-time, nullable — End of the interval this revision was current for. `null` while it is the live revision.
  - `services` Service[], required — Services identified on the host.
    - `bindings` Binding[], required — Ports and IP addresses this service is reachable on.
      - union
        - object — Association between a service and a port / interface that the service is listening on
          - `ip_address_id` string, uuid, required — The IP address the service is present at.
          - `type` 'IPAddress', required
          - `network_id` string, uuid, required — The network this entity belongs to.
          - `service_id` string, uuid, required — The service this entity refers to.
          - `created_at` string, date-time, required — When this record was first created.
          - `first_discovery_id` string, uuid, nullable — The discovery that first observed this entity.
          - `id` string, uuid, required — Server-assigned unique identifier.
          - `last_discovery_id` string, uuid, nullable — The most recent discovery that observed this entity.
          - `last_seen_at` string, date-time — When a discovery last observed this entity.
          - `lineage_id` string, uuid, nullable — Stable identifier shared by every revision of the same entity across its history.
          - `updated_at` string, date-time, required — When this record was last modified.
          - `valid_from` string, date-time — Start of the interval this revision was current for (SCD2 history).
          - `valid_to` string, date-time, nullable — End of the interval this revision was current for. `null` while it is the live revision.
        - 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 — The port the service listens on.
          - `type` 'Port', required
          - `network_id` string, uuid, required — The network this entity belongs to.
          - `service_id` string, uuid, required — The service this entity refers to.
          - `created_at` string, date-time, required — When this record was first created.
          - `first_discovery_id` string, uuid, nullable — The discovery that first observed this entity.
          - `id` string, uuid, required — Server-assigned unique identifier.
          - `last_discovery_id` string, uuid, nullable — The most recent discovery that observed this entity.
          - `last_seen_at` string, date-time — When a discovery last observed this entity.
          - `lineage_id` string, uuid, nullable — Stable identifier shared by every revision of the same entity across its history.
          - `updated_at` string, date-time, required — When this record was last modified.
          - `valid_from` string, date-time — Start of the interval this revision was current for (SCD2 history).
          - `valid_to` string, date-time, nullable — End of the interval this revision was current for. `null` while it is the live revision.
    - `host_id` string, uuid, required — The host this entity belongs to.
    - `name` string, required — Human-facing name for the service.
    - `network_id` string, uuid, required — The network this entity belongs to.
    - `position` integer, required — Position of this service in the host's service list (for ordering)
    - `service_definition` string, required — Which known software this service is, if identified.
    - `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
            - object
              - …
            - object
              - …
        - `type` 'DiscoveryWithMatch', required
      - object
        - `type` 'Unknown', required
    - `tags` string[], required — Tags assigned to this entity.
    - `virtualization_metadata` union
      - object
        - `details` DockerVirtualization, required
          - `compose_project` string, nullable — Compose project the container belongs to, when it was started by Compose.
          - `container_id` string, nullable — Docker container ID.
          - `container_name` string, nullable — Container name as reported by Docker.
        - `type` 'Docker', required
      - object
        - `details` PodmanVirtualization, required
          - `compose_project` string, nullable — Compose project the container belongs to, when it was started by Compose.
          - `container_id` string, nullable — Podman container ID.
          - `container_name` string, nullable — Container name as reported by Podman.
        - `type` 'Podman', required
    - `virtualization_service_id` string, uuid, nullable, required — The container runtime service hosting this container — see the note on `HostBase::virtualization_service_id`.
    - `created_at` string, date-time, required — When this record was first created.
    - `first_discovery_id` string, uuid, nullable — The discovery that first observed this entity.
    - `id` string, uuid, required — Server-assigned unique identifier.
    - `last_discovery_id` string, uuid, nullable — The most recent discovery that observed this entity.
    - `last_seen_at` string, date-time — When a discovery last observed this entity.
    - `lineage_id` string, uuid, nullable — Stable identifier shared by every revision of the same entity across its history.
    - `updated_at` string, date-time, required — When this record was last modified.
    - `valid_from` string, date-time — Start of the interval this revision was current for (SCD2 history).
    - `valid_to` string, date-time, nullable — End of the interval this revision was current for. `null` while it is the live revision.
  - `subnets` Subnet[] — Integration-derived subnets (e.g., Docker bridge networks) — created during create_with_children after service dedup so virtualization.service_id is correct.
    - `cidr` string, required — Subnet in CIDR notation, IPv4 or IPv6.
    - `description` string, nullable — Free-text notes about the subnet.
    - `name` string, required — Human-facing name for this subnet.
    - `network_id` string, uuid, required — The network this entity belongs to.
    - `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
            - object
              - …
            - object
              - …
        - `type` 'DiscoveryWithMatch', required
      - object
        - `type` 'Unknown', required
    - `subnet_type` 'Internet' | 'Remote' | 'Gateway' | 'VpnTunnel' | 'Dmz' | 'Lan' | 'WiFi' | 'IoT' | 'Guest' | 'DockerBridge' | 'PodmanBridge' | 'MacVlan' | 'IpVlan' | 'Management' | 'Storage' | 'Loopback' | 'Unknown', required
    - `tags` string[], required — Tags assigned to this entity.
    - `virtualization_service_id` string, uuid, nullable, required — The container runtime service that owns this bridge network. Load-bearing for dedup: the same CIDR on two different Docker daemons is two distinct subnets, so bridge rows only merge when this matches as well as the CIDR and network. A foreign key rather than a field inside a JSONB blob because a stale value here is precisely what made a scan add a duplicate bridge row every time (GH #650) — now it cannot be written at all.
    - `created_at` string, date-time, required — When this record was first created.
    - `first_discovery_id` string, uuid, nullable — The discovery that first observed this entity.
    - `id` string, uuid, required — Server-assigned unique identifier.
    - `last_discovery_id` string, uuid, nullable — The most recent discovery that observed this entity.
    - `last_seen_at` string, date-time — When a discovery last observed this entity.
    - `lineage_id` string, uuid, nullable — Stable identifier shared by every revision of the same entity across its history.
    - `updated_at` string, date-time, required — When this record was last modified.
    - `valid_from` string, date-time — Start of the interval this revision was current for (SCD2 history).
    - `valid_to` string, date-time, nullable — End of the interval this revision was current for. `null` while it is the live revision.

## Response `200`

Host discovered/updated successfully

- ApiResponseHostResponse
  - `data` object — Response type for host endpoints. Includes children (ip_addresses, ports, services, interfaces).
    - `chassis_id` string, nullable — LLDP chassis identifier, used to match the host to its neighbours.
    - `created_at` string, date-time, required — When this record was first created.
    - `credential_assignments` CredentialAssignment[] — Credentials assigned to scan this host.
      - `credential_id` string, uuid, required — The credential this entity refers to.
      - `ip_address_ids` string[], nullable, required — Interface IDs to limit this credential to. None = all host ip_addresses.
    - `description` string, nullable — Free-text notes about the host.
    - `hidden` boolean, required — Whether the host is hidden from topology views.
    - `hostname` string, nullable — Hostname as resolved or reported by the host.
    - `id` string, uuid, required — Server-assigned unique identifier.
    - `interfaces` Interface[], required — SNMP ifTable entries
      - `admin_status` 'Up' | 'Down' | 'Testing', required — SNMP ifAdminStatus values per IF-MIB RFC 2863
      - `cdp_address` string, nullable — Remote management IP from CDP (cdpCacheAddress). IPv4 or IPv6.
      - `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 — The host this entity belongs to.
      - `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). IPv4 or IPv6.
      - `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 — The network this entity belongs to.
      - `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 — When this record was first created.
      - `first_discovery_id` string, uuid, nullable — The discovery that first observed this entity.
      - `id` string, uuid, required — Server-assigned unique identifier.
      - `last_discovery_id` string, uuid, nullable — The most recent discovery that observed this entity.
      - `last_seen_at` string, date-time — When a discovery last observed this entity.
      - `lineage_id` string, uuid, nullable — Stable identifier shared by every revision of the same entity across its history.
      - `updated_at` string, date-time, required — When this record was last modified.
      - `valid_from` string, date-time — Start of the interval this revision was current for (SCD2 history).
      - `valid_to` string, date-time, nullable — End of the interval this revision was current for. `null` while it is the live revision.
    - `ip_addresses` IPAddress[], required — IP addresses on this host.
      - `host_id` string, uuid, required — The host this entity belongs to.
      - `ip_address` string, required — IPv4 or IPv6 address.
      - `mac_address` string, nullable — MAC address discovered from ARP, SNMP, or Docker - immutable once set
      - `name` string, nullable, required — Human-facing name for this IP address.
      - `network_id` string, uuid, required — The network this entity belongs to.
      - `position` integer — Position of this IP address in the host's IP address list (for ordering)
      - `subnet_id` string, uuid, required — The subnet this entity belongs to.
      - `created_at` string, date-time, required — When this record was first created.
      - `first_discovery_id` string, uuid, nullable — The discovery that first observed this entity.
      - `id` string, uuid, required — Server-assigned unique identifier.
      - `last_discovery_id` string, uuid, nullable — The most recent discovery that observed this entity.
      - `last_seen_at` string, date-time — When a discovery last observed this entity.
      - `lineage_id` string, uuid, nullable — Stable identifier shared by every revision of the same entity across its history.
      - `updated_at` string, date-time, required — When this record was last modified.
      - `valid_from` string, date-time — Start of the interval this revision was current for (SCD2 history).
      - `valid_to` string, date-time, nullable — End of the interval this revision was current for. `null` while it is the live revision.
    - `last_seen_at` string, date-time, required — Last time discovery observed this host. User-facing (drives the "Last seen" column and the stale badge), which is why it is carried here while the rest of the SCD2/audit columns are not.
    - `management_url` string, nullable — Link to the host's own management interface.
    - `name` string, required — Human-facing name for the host.
    - `name_source` 'Unspecified' | 'Ip' | 'DetectedService' | 'Hostname' | 'Integration' | 'Manual' — Which rung of the naming ladder produced a host's display name, weakest first. Declaration order is the precedence order — `Ord` is derived from it, and that derive is the whole enforcement mechanism: a rung inserted at its rank propagates to every comparison, so there is no per-call-site precedence to keep in sync. Persisted as bare text (`Manual`, `Integration`, …) via `Display`/`FromStr`.
    - `network_id` string, uuid, required — The network this entity belongs to.
    - `ports` Port[], required — Open ports on this host.
      - `number` integer, required — TCP or UDP port number
      - `protocol` 'Udp' | 'Tcp', required — Transport protocol the port is open on.
      - `type` 'Ssh' | 'Telnet' | 'DnsUdp' | 'DnsTcp' | 'Samba' | 'Nfs' | 'Ftp' | 'Ipp' | 'LdpTcp' | 'LdpUdp' | 'Ldap' | 'Ldaps' | 'Kerberos' | 'Snmp' | 'SnmpAlt' | 'Rdp' | 'Ntp' | 'Sip' | 'SipTls' | 'Rtsp' | 'Dhcp' | 'Http' | 'MySql' | 'PostgreSQL' | 'MongoDB' | 'Redis' | 'MsSql' | 'Docker' | 'DockerTls' | 'Kubernetes' | 'RabbitMqMgmt' | 'Cassandra' | 'Elasticsearch' | 'InfluxDb' | 'CouchDb' | 'Kafka' | 'Http3000' | 'Http5000' | 'Http8080' | 'Http8081' | 'Http8082' | 'Http8888' | 'Http9000' | 'Https' | 'Https8443' | 'Https9443' | 'Https10443' | 'Mqtt' | 'MqttTls' | 'AMQP' | 'AMQPTls' | 'Wireguard' | 'OpenVPN' | 'BACnet' | 'JetDirect' | 'Custom' — Well-known port identifier. Auto-derived from number+protocol, so it is optional on create.
      - `host_id` string, uuid, required — The host this entity belongs to.
      - `network_id` string, uuid, required — The network this entity belongs to.
      - `created_at` string, date-time, required — When this record was first created.
      - `first_discovery_id` string, uuid, nullable — The discovery that first observed this entity.
      - `id` string, uuid, required — Server-assigned unique identifier.
      - `last_discovery_id` string, uuid, nullable — The most recent discovery that observed this entity.
      - `last_seen_at` string, date-time — When a discovery last observed this entity.
      - `lineage_id` string, uuid, nullable — Stable identifier shared by every revision of the same entity across its history.
      - `updated_at` string, date-time, required — When this record was last modified.
      - `valid_from` string, date-time — Start of the interval this revision was current for (SCD2 history).
      - `valid_to` string, date-time, nullable — End of the interval this revision was current for. `null` while it is the live revision.
    - `services` Service[], required — Services running on this host.
      - `bindings` Binding[], required — Ports and IP addresses this service is reachable on.
        - union
          - object — Association between a service and a port / interface that the service is listening on
            - `ip_address_id` string, uuid, required — The IP address the service is present at.
            - `type` 'IPAddress', required
            - `network_id` string, uuid, required — The network this entity belongs to.
            - `service_id` string, uuid, required — The service this entity refers to.
            - `created_at` string, date-time, required — When this record was first created.
            - `first_discovery_id` string, uuid, nullable — The discovery that first observed this entity.
            - `id` string, uuid, required — Server-assigned unique identifier.
            - `last_discovery_id` string, uuid, nullable — The most recent discovery that observed this entity.
            - `last_seen_at` string, date-time — When a discovery last observed this entity.
            - `lineage_id` string, uuid, nullable — Stable identifier shared by every revision of the same entity across its history.
            - `updated_at` string, date-time, required — When this record was last modified.
            - `valid_from` string, date-time — Start of the interval this revision was current for (SCD2 history).
            - `valid_to` string, date-time, nullable — End of the interval this revision was current for. `null` while it is the live revision.
          - 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 — The port the service listens on.
            - `type` 'Port', required
            - `network_id` string, uuid, required — The network this entity belongs to.
            - `service_id` string, uuid, required — The service this entity refers to.
            - `created_at` string, date-time, required — When this record was first created.
            - `first_discovery_id` string, uuid, nullable — The discovery that first observed this entity.
            - `id` string, uuid, required — Server-assigned unique identifier.
            - `last_discovery_id` string, uuid, nullable — The most recent discovery that observed this entity.
            - `last_seen_at` string, date-time — When a discovery last observed this entity.
            - `lineage_id` string, uuid, nullable — Stable identifier shared by every revision of the same entity across its history.
            - `updated_at` string, date-time, required — When this record was last modified.
            - `valid_from` string, date-time — Start of the interval this revision was current for (SCD2 history).
            - `valid_to` string, date-time, nullable — End of the interval this revision was current for. `null` while it is the live revision.
      - `host_id` string, uuid, required — The host this entity belongs to.
      - `name` string, required — Human-facing name for the service.
      - `network_id` string, uuid, required — The network this entity belongs to.
      - `position` integer, required — Position of this service in the host's service list (for ordering)
      - `service_definition` string, required — Which known software this service is, if identified.
      - `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 — Tags assigned to this entity.
      - `virtualization_metadata` union
        - object
          - `details` DockerVirtualization, required
            - `compose_project` string, nullable — Compose project the container belongs to, when it was started by Compose.
            - `container_id` string, nullable — Docker container ID.
            - `container_name` string, nullable — Container name as reported by Docker.
          - `type` 'Docker', required
        - object
          - `details` PodmanVirtualization, required
            - `compose_project` string, nullable — Compose project the container belongs to, when it was started by Compose.
            - `container_id` string, nullable — Podman container ID.
            - `container_name` string, nullable — Container name as reported by Podman.
          - `type` 'Podman', required
      - `virtualization_service_id` string, uuid, nullable, required — The container runtime service hosting this container — see the note on `HostBase::virtualization_service_id`.
      - `created_at` string, date-time, required — When this record was first created.
      - `first_discovery_id` string, uuid, nullable — The discovery that first observed this entity.
      - `id` string, uuid, required — Server-assigned unique identifier.
      - `last_discovery_id` string, uuid, nullable — The most recent discovery that observed this entity.
      - `last_seen_at` string, date-time — When a discovery last observed this entity.
      - `lineage_id` string, uuid, nullable — Stable identifier shared by every revision of the same entity across its history.
      - `updated_at` string, date-time, required — When this record was last modified.
      - `valid_from` string, date-time — Start of the interval this revision was current for (SCD2 history).
      - `valid_to` string, date-time, nullable — End of the interval this revision was current for. `null` while it is the live revision.
    - `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
            - object
              - …
            - object
              - …
        - `type` 'DiscoveryWithMatch', required
      - object
        - `type` 'Unknown', required
    - `sys_contact` string, nullable — SNMP sysContact — administrative contact as configured on the device.
    - `sys_descr` string, nullable — SNMP sysDescr — the device's own description of itself.
    - `sys_location` string, nullable — SNMP sysLocation — physical location as configured on the device.
    - `sys_object_id` string, nullable — SNMP sysObjectID — the vendor's identifier for the device model.
    - `tags` string[], required — Tags assigned to this entity.
    - `updated_at` string, date-time, required — When this record was last modified.
    - `virtualization_metadata` union
      - object
        - `details` ProxmoxVirtualization, required
          - `vm_id` string, nullable — Proxmox VMID of the guest.
          - `vm_name` string, nullable — Guest name as configured in Proxmox.
        - `type` 'Proxmox', required
      - object
        - `details` VCenterVirtualization, required
          - `vm_id` string, nullable — vCenter managed object ID of the guest.
          - `vm_name` string, nullable — Guest name as configured in vCenter.
        - `type` 'VCenter', required
      - object
        - `details` EsxiVirtualization, required
          - `vm_id` string, nullable — ESXi identifier of the guest.
          - `vm_name` string, nullable — Guest name as configured on the ESXi host.
        - `type` 'ESXi', required
    - `virtualization_service_id` string, uuid, nullable — The hypervisor service this VM runs on.
  - `error` string, nullable — Human-readable failure message. Omitted on success.
  - `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 — `true` when the request succeeded. `false` responses carry `error` instead of `data`.

## Other responses

- `403` — Daemon cannot create hosts on other networks

---

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