--- 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 - `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 - `metadata` DiscoveryMetadata[], required - union - object - … - object - … - object - … - 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 - … - `metadata` DiscoveryMetadata[], required - union - object - … - object - … - 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 - `virtualization` HostVirtualization, required - `details` ProxmoxVirtualization, required - `service_id` string, uuid, required - `vm_id` string, nullable - `vm_name` string, nullable - `type` 'Proxmox', required - `created_at` string, date-time, required - `id` string, uuid, required - `updated_at` string, date-time, required - `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) - `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 - `id` string, uuid, required - `updated_at` string, date-time, required - `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 - `id` string, uuid, required - `updated_at` string, date-time, required - `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 - `id` string, uuid, required - `updated_at` string, date-time, required - `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 - `id` string, uuid, required - `updated_at` string, date-time, required - 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 - `id` string, uuid, required - `updated_at` string, date-time, required - `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 - `metadata` DiscoveryMetadata[], required - union - object - … - object - … - object - … - 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 - … - `metadata` DiscoveryMetadata[], required - union - object - … - object - … - object - … - object - … - `type` 'DiscoveryWithMatch', required - object - `type` 'Unknown', required - `tags` string[], required - `virtualization` ServiceVirtualization - `details` DockerVirtualization, required - `compose_project` string, nullable - `container_id` string, nullable - `container_name` string, nullable - `service_id` string, uuid, required - `type` 'Docker', required - `created_at` string, date-time, required - `id` string, uuid, required - `updated_at` string, date-time, required - `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 - `description` string, nullable - `name` string, required - `network_id` string, uuid, required - `source` union, required - object - `type` 'Manual', required - object - `type` 'System', required - object - `metadata` DiscoveryMetadata[], required - union - object - … - object - … - object - … - 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 - … - `metadata` DiscoveryMetadata[], required - union - object - … - object - … - object - … - object - … - `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 - `id` string, uuid, required - `updated_at` string, date-time, required ## 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 - `created_at` string, date-time, required - `credential_assignments` CredentialAssignment[] - `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 - `hidden` boolean, required - `hostname` string, nullable - `id` string, uuid, required - `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) - `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 - `id` string, uuid, required - `updated_at` string, date-time, required - `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 - `id` string, uuid, required - `updated_at` string, date-time, required - `management_url` string, nullable - `name` string, required - `network_id` string, uuid, required - `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 - `id` string, uuid, required - `updated_at` string, date-time, required - `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 - `id` string, uuid, required - `updated_at` string, date-time, required - 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 - `id` string, uuid, required - `updated_at` string, date-time, required - `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 - `metadata` DiscoveryMetadata[], required - union - … - `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 - … - `metadata` DiscoveryMetadata[], required - union - … - `type` 'DiscoveryWithMatch', required - object - `type` 'Unknown', required - `tags` string[], required - `virtualization` ServiceVirtualization - `details` DockerVirtualization, required - `compose_project` string, nullable - `container_id` string, nullable - `container_name` string, nullable - `service_id` string, uuid, required - `type` 'Docker', required - `created_at` string, date-time, required - `id` string, uuid, required - `updated_at` string, date-time, required - `source` union, required - object - `type` 'Manual', required - object - `type` 'System', required - object - `metadata` DiscoveryMetadata[], required - union - object - … - object - … - object - … - 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 - … - `metadata` DiscoveryMetadata[], required - union - object - … - object - … - object - … - object - … - `type` 'DiscoveryWithMatch', required - object - `type` 'Unknown', required - `sys_contact` string, nullable - `sys_descr` string, nullable - `sys_location` string, nullable - `sys_object_id` string, nullable - `tags` string[], required - `updated_at` string, date-time, required - `virtualization` HostVirtualization - `details` ProxmoxVirtualization, required - `service_id` string, uuid, required - `vm_id` string, nullable - `vm_name` string, nullable - `type` 'Proxmox', required - `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` — Daemon cannot create hosts on other networks ## Changes - **2026-04-20** `f04499e2280f` — 10 breaking, 31 warning, 6 info - added the new required request property `host/allOf[#/components/schemas/HostBase]/source/oneOf[subschema #3: Discovery]/metadata` - added the new required request property `host/allOf[#/components/schemas/HostBase]/source/oneOf[subschema #4: DiscoveryWithMatch]/metadata` - added the new required request property `services/items/allOf[#/components/schemas/ServiceBase]/source/oneOf[subschema #3: Discovery]/metadata` - added the new required request property `services/items/allOf[#/components/schemas/ServiceBase]/source/oneOf[subschema #4: DiscoveryWithMatch]/metadata` - …43 more [Change history](https://skmtc.dev/scanopy/apis/scanopy-api/changes/api/v1/hosts/discovery/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/f04499e2280f/schema)