Sign in
Interfaces

Create a new Interface

Creates an SNMP ifTable entry for a host. These are typically created by SNMP discovery, but can also be created manually.

post/api/v1/if-entries

Request body

admin_status'Up' | 'Down' | 'Testing' required

SNMP ifAdminStatus values per IF-MIB RFC 2863

cdp_addressstring nullable

Remote management IP from CDP (cdpCacheAddress). IPv4 or IPv6.

cdp_device_idstring nullable

Remote device ID from CDP (typically hostname, locally unique)

cdp_platformstring nullable

Remote platform from CDP (e.g., "Cisco IOS")

cdp_port_idstring nullable

Remote port ID from CDP

fdb_macsstring[] 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_idstring uuid required

The host this entity belongs to.

if_aliasstring nullable

SNMP ifAlias - user-configured description

if_descrstring required

SNMP ifDescr - interface description (e.g., GigabitEthernet0/1)

if_indexinteger required

SNMP ifIndex - stable identifier within device

if_namestring nullable

SNMP ifName - short interface name (e.g., Gi1/0/1)

if_typeinteger required

SNMP ifType - IANAifType integer (6=ethernet, 24=loopback, etc.)

ip_address_idstring uuid nullable

FK to IPAddress entity - this port's IP assignment (must be on same host). Old daemons send this as "interface_id".

lldp_mgmt_addrstring nullable

Remote management IP from LLDP neighbor (lldpRemManAddr). IPv4 or IPv6.

lldp_port_descstring nullable

Remote port description from LLDP neighbor (lldpRemPortDesc)

lldp_sys_descstring nullable

Remote system description from LLDP neighbor (lldpRemSysDesc) - platform info

lldp_sys_namestring nullable

Remote system name from LLDP neighbor (lldpRemSysName)

mac_addressstring nullable

MAC address from SNMP ifPhysAddress - immutable once set

native_vlan_idstring uuid nullable

Native/untagged VLAN entity ID on this port (resolved from Q-BRIDGE dot1qPvid)

neighbor_seen_atstring date-time nullable

When a scan last carried evidence that something is adjacent to this port.

The freshness subject for the link, as last_seen_at is for the port. A port keeps appearing in the ifTable long after its neighbour record stops arriving, so last_seen_at cannot tell a live adjacency from one whose evidence has vanished. Judged against the same Network::stale_cutoff as every other freshness verdict.

None means no scan has ever carried evidence for this row, and reads as unknown — never as stale. Server-owned: stamped on the discovery ingest path, never sent by a daemon.

network_idstring 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_bpsinteger nullable

Interface speed from ifSpeed/ifHighSpeed in bits per second

vlan_idsstring[] nullable

Tagged VLAN entity IDs on this port (resolved from Q-BRIDGE dot1qVlanCurrentEgressPorts)

created_atstring date-time required

When this record was first created.

first_discovery_idstring uuid nullable

The discovery that first observed this entity.

idstring uuid required

Server-assigned unique identifier.

last_discovery_idstring uuid nullable

The most recent discovery that observed this entity.

last_seen_atstring date-time

When a discovery last observed this entity.

lineage_idstring uuid nullable

Stable identifier shared by every revision of the same entity across its history.

updated_atstring date-time required

When this record was last modified.

valid_fromstring date-time

Start of the interval this revision was current for (SCD2 history).

valid_tostring date-time nullable

End of the interval this revision was current for. null while it is the live revision.

Example request

{
  "cdp_address": "192.168.1.1",
  "lldp_mgmt_addr": "192.168.1.1",
  "mac_address": "a4:bb:6d:12:34:56"
}

Response

If entry created successfully

errorstring nullable

Human-readable failure message. Omitted on success.

successboolean required

true when the request succeeded. false responses carry error instead of data.

Example response

{
  "data": {
    "cdp_address": "192.168.1.1",
    "lldp_mgmt_addr": "192.168.1.1",
    "mac_address": "a4:bb:6d:12:34:56"
  },
  "meta": {
    "api_version": 1,
    "server_version": "0.17.13"
  }
}

Changes