--- title: "Create a new Interface" method: POST path: "/api/v1/if-entries" tags: ["Interfaces"] --- # Create a new Interface `POST /api/v1/if-entries` Creates an SNMP ifTable entry for a host. These are typically created by SNMP discovery, but can also be created manually. ## Request body - Interface - `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. ## Response `200` If entry created successfully - ApiResponseInterface - `data` object — The result payload. Omitted on failure. - `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. - `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` — Network mismatch or duplicate if_index --- [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)