SCscanopy
Interfaces

Create interface

Changed on

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

post/api/v1/interfaces

Request

  • Base URL
    https://app.scanopy.net
  • URL
    https://app.scanopy.net/api/v1/interfaces
  • Auth
    • API key in header Authorization
    • or API key in cookie session_id

Request body

mac_addressstring

MAC address, as discovered.

fdb_macsstring[]

MAC addresses the switch learned on this port. A port with one learned MAC can be resolved to a neighbor link; several indicate an uplink.

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

SNMP ifAdminStatus values per IF-MIB RFC 2863

host_idstring uuid required

The host this entity belongs to.

if_aliasstring nullable

SNMP ifAlias - user-configured description

if_descrstring nullable

SNMP ifDescr - interface description (e.g., GigabitEthernet0/1), where one was read.

None for a source with nothing to put here — PROFINET DCP Identify carries no per-port description at all. Same principle as if_index/if_type: an absent value is None, never a fabricated string standing in for it.

if_indexinteger nullable

SNMP ifIndex — stable identifier within device, where one was read.

None for a port learned from a neighbour's LLDP/CDP advertisement rather than from the device's own ifTable: the far end tells us the port exists and what it is called, never its index. 0 used to stand in for that, which is a real ifIndex on some agents and made "never read" indistinguishable from "read as zero".

Not the identity of the row. match_existing_interface tries (host_id, if_name) first and the live unique index is on that pair; the index tier only runs for a row that has one.

if_namestring nullable

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

if_typeinteger nullable

SNMP ifType - IANAifType integer (6=ethernet, 24=loopback, etc.), where one was read.

None is unknown, never a type. Everything that filters on this must treat unknown as included — a port at the far end of a cable is physical by construction, and excluding it for lack of a number would drop the row from resolution and from the map.

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".

ip_configuredboolean

Whether the device's own SNMP ipAddrTable lists this ifIndex as carrying one of its configured IP addresses.

Independent of ip_address_id: that FK is set server-side and requires the interface's MAC to be unique on the host before it links anything (plan_interface_ip_links), so it stays NULL on exactly the hosts this field exists to help — a Windows NIC and its NDIS filter/LWF pseudo-interfaces sharing one MAC (GH #668). ipAddrTable only ever binds an address to a real IP-stack adapter; a filter driver is never a separate one, so this distinguishes the physical interface among MAC-sharing candidates. #[serde(default)] so a daemon predating this field is read as false on every row — never worse than today's behavior.

native_vlan_idstring uuid nullable

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

oper_status'Up' | 'Down' | 'Testing' | 'Unknown' | 'Dormant' | 'NotPresent' | 'LowerLayerDown'

SNMP ifOperStatus values per IF-MIB RFC 2863

site_idstring uuid required

The site this entity belongs to.

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.

display_namestring nullable

What to call this interface when it has no if_alias/if_descr: the MAC it was identified by, or "Interface" when it has neither.

Read-only and computed from [Interface::display_name] — the same ladder topology port labels an interface with, so it cannot be called one thing in a list and another on the map. Set on every interface read from storage, so every endpoint that returns one carries it; absent on a daemon's own submission, and ignored on write.

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

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

Response

If entry created successfully

errorstring nullable

Not sent on a successful response. Failure messages arrive in an ApiErrorResponse.

successboolean required

Always true on a successful response.

Example response

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

Changes

  • c94279effef3Revision changes
    • warning

      added the new Lpd enum value to the /////////// response property for the response status

    • warning

      added the new Lpd enum value to the /////////// response property for the response status

    • warning

      added the new Lpd enum value to the /////////// response property for the response status

    • warning

      added the new Lpd enum value to the /////////// response property for the response status

    • warning

      added the new Lpd enum value to the //////// response property for the response status

    • warning

      added the new Lpd enum value to the //////// response property for the response status

    • warning

      added the new Lpd enum value to the ////////// response property for the response status

    • warning

      added the new Lpd enum value to the ////////// response property for the response status

    • warning

      added the new Lpd enum value to the //////// response property for the response status

    • warning

      added the new Lpd enum value to the //////// response property for the response status

    • info

      added the new Lpd enum value to the request property //////////

    • info

      added the new Lpd enum value to the request property //////////

    • info

      added the new Lpd enum value to the request property //////////

    • info

      added the new Lpd enum value to the request property //////////

    • info

      added the new Lpd enum value to the request property ///////

    • info

      added the new Lpd enum value to the request property ///////

    • info

      added the new Lpd enum value to the request property /////////

    • info

      added the new Lpd enum value to the request property /////////

    • info

      added the new Lpd enum value to the request property ///////

    • info

      added the new Lpd enum value to the request property ///////

  • c2ab03503a27Revision changes
    • breaking

      added subschema #11 subschema #12 subschema #13 subschema #14 subschema #15 subschema #16 subschema #17 subschema #18 subschema #19 subschema #20 to the ///////// response property oneOf list for the response status

    • breaking

      added subschema #11 subschema #12 subschema #13 subschema #14 subschema #15 subschema #16 subschema #17 subschema #18 subschema #19 subschema #20 to the ///////// response property oneOf list for the response status

    • breaking

      added subschema #11 subschema #12 subschema #13 subschema #14 subschema #15 subschema #16 subschema #17 subschema #18 subschema #19 subschema #20 to the ////// response property oneOf list for the response status

    • breaking

      added subschema #11 subschema #12 subschema #13 subschema #14 subschema #15 subschema #16 subschema #17 subschema #18 subschema #19 subschema #20 to the //////// response property oneOf list for the response status

    • breaking

      added subschema #11 subschema #12 subschema #13 subschema #14 subschema #15 subschema #16 subschema #17 subschema #18 subschema #19 subschema #20 to the ////// response property oneOf list for the response status

    • info

      added subschema #11 subschema #12 subschema #13 subschema #14 subschema #15 subschema #16 subschema #17 subschema #18 subschema #19 subschema #20 to the //////// request property oneOf list

    • info

      added subschema #11 subschema #12 subschema #13 subschema #14 subschema #15 subschema #16 subschema #17 subschema #18 subschema #19 subschema #20 to the //////// request property oneOf list

    • info

      added subschema #11 subschema #12 subschema #13 subschema #14 subschema #15 subschema #16 subschema #17 subschema #18 subschema #19 subschema #20 to the ///// request property oneOf list

    • info

      added subschema #11 subschema #12 subschema #13 subschema #14 subschema #15 subschema #16 subschema #17 subschema #18 subschema #19 subschema #20 to the /////// request property oneOf list

    • info

      added subschema #11 subschema #12 subschema #13 subschema #14 subschema #15 subschema #16 subschema #17 subschema #18 subschema #19 subschema #20 to the ///// request property oneOf list