--- title: "Update a host" method: PUT path: "/api/v1/hosts/{id}" tags: ["Hosts"] --- # Update a host `PUT /api/v1/hosts/{id}` Updates host properties. Children (ip_addresses, ports, services) are managed via their own endpoints. ### Tag Validation - Tags must exist and belong to your organization - Duplicate tag UUIDs are automatically deduplicated - Invalid or cross-organization tag UUIDs return a 400 error ## Path parameters - `id` string, uuid, required ## Request body - UpdateHostRequest — Request type for updating a host with its children. Uses the same input types as CreateHostRequest. Server will sync children (create new, update existing, delete removed) only if provided. - `credential_assignments` CredentialAssignment[], nullable — Credential assignments for this host. If provided, replaces all existing credential assignments. - `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. - `expected_updated_at` string, date-time, nullable — Optional: expected updated_at timestamp for optimistic locking. - `hidden` boolean, required — Hide the host from topology views without deleting it. - `hostname` string, nullable — Hostname as resolved or reported by the host. - `id` string, uuid, required — Server-assigned unique identifier. - `ip_addresses` IPAddressInput[], nullable — Interfaces to sync with this host. If Some, server will create/update/delete to match this list. If None, existing ip_addresses are preserved. - `id` string, uuid, required — Client-provided UUID for this interface - `ip_address` string, required — IPv4 or IPv6 address. - `mac_address` string, nullable — MAC address, when known. - `name` string, nullable — Human-facing name for this IP address. - `position` integer, nullable — Position in the host's interface list (for ordering). If omitted on create: appends to end of list. If omitted on update: existing ip_addresses keep their positions; new ip_addresses append. Must be all specified or all omitted across all ip_addresses in the request. - `subnet_id` string, uuid, required — The subnet this entity belongs to. - `name` string, required — Human-facing name for the host. - `ports` PortInput[], nullable — Ports to sync with this host. If Some, server will create/update/delete to match this list. If None, existing ports are preserved. - `id` string, uuid, required — Client-provided UUID for this port - `number` integer, required — Port number (1-65535) - `protocol` 'Udp' | 'Tcp', required - `services` ServiceInput[], nullable — Services to sync with this host. If Some, server will create/update/delete to match this list. If None, existing services are preserved. - `bindings` BindingInput[] — Bindings that associate this service with ports/interfaces - union — Input for creating or updating a binding within a service. Used in both CreateHostRequest and UpdateHostRequest. Client must provide a UUID for the binding. - object — Bind to an interface (service is present at this interface without a specific port) - `id` string, uuid, required — Client-provided UUID for this binding - `ip_address_id` string, uuid, required — The IP address the service is present at. - `type` 'IPAddress', required - object — Bind to a port (optionally on a specific ip_address) - `id` string, uuid, required — Client-provided UUID for this binding - `ip_address_id` string, uuid, nullable — null = bind to all ip_addresses - `port_id` string, uuid, required — The port the service listens on. - `type` 'Port', required - `id` string, uuid, required — Client-provided UUID for this service - `name` string, required — Display name for this service - `position` integer, nullable — Position in the host's service list (for ordering). If omitted on create: appends to end of list. If omitted on update: existing services keep their positions; new services append. Must be all specified or all omitted across all services in the request. - `service_definition` string, required — Service definition ID (e.g., "Nginx", "PostgreSQL") - `tags` string[] — Tags for categorization - `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 — The container runtime service hosting this container, if any. - `tags` string[], required — Tags assigned to this entity. - `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. ## Response `200` Host updated - 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. - `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 - `400` — Validation error: invalid tags - `404` — Host not found --- [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/versions/28e466341947/schema)