Sign in

v62

latestOpenAPI 3.1.0Dual (AGPL3.0, Commercial License Available)raw.githubusercontent.com2026-08-03211303932.5 KB
Hosts
internal

Internal endpoint for daemon 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.

post/api/v1/hosts/discovery

Request body

interfaces_completeboolean

Whether interfaces is a complete, authoritative ifTable. When false (a partial SNMP walk cut short by timeout/error), the server must NOT prune interfaces missing from this scan — otherwise a transient partial walk tears down the host's L2 topology (#649). Daemons that predate this field omit it; it defaults to true so their behavior is unchanged.

Example request

{
  "host": {
    "created_at": "2026-01-15T10:30:00Z",
    "credential_assignments": [],
    "description": "Primary web server",
    "first_discovery_id": null,
    "hidden": false,
    "hostname": "web-server-01.local",
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "last_discovery_id": null,
    "last_seen_at": "2026-01-15T10:30:00Z",
    "lineage_id": null,
    "name": "web-server-01",
    "network_id": "550e8400-e29b-41d4-a716-446655440002",
    "source": {
      "type": "Manual"
    },
    "tags": [],
    "updated_at": "2026-01-15T10:30:00Z",
    "valid_from": "2026-01-15T10:30:00Z",
    "valid_to": null,
    "virtualization": null
  },
  "interfaces": [
    {
      "cdp_address": "192.168.1.1",
      "lldp_mgmt_addr": "192.168.1.1",
      "mac_address": "a4:bb:6d:12:34:56"
    }
  ],
  "ip_addresses": [
    {
      "created_at": "2026-01-15T10:30:00Z",
      "first_discovery_id": null,
      "host_id": "550e8400-e29b-41d4-a716-446655440003",
      "id": "550e8400-e29b-41d4-a716-446655440005",
      "ip_address": "192.168.1.100",
      "last_discovery_id": null,
      "last_seen_at": "2026-01-15T10:30:00Z",
      "lineage_id": null,
      "mac_address": "DE:AD:BE:EF:CA:FE",
      "name": "eth0",
      "network_id": "550e8400-e29b-41d4-a716-446655440002",
      "position": 0,
      "subnet_id": "550e8400-e29b-41d4-a716-446655440004",
      "updated_at": "2026-01-15T10:30:00Z",
      "valid_from": "2026-01-15T10:30:00Z",
      "valid_to": null
    }
  ],
  "ports": [
    {
      "created_at": "2026-01-15T10:30:00Z",
      "first_discovery_id": null,
      "host_id": "550e8400-e29b-41d4-a716-446655440003",
      "id": "550e8400-e29b-41d4-a716-446655440006",
      "last_discovery_id": null,
      "last_seen_at": "2026-01-15T10:30:00Z",
      "lineage_id": null,
      "network_id": "550e8400-e29b-41d4-a716-446655440002",
      "number": 80,
      "protocol": "Tcp",
      "type": "Http",
      "updated_at": "2026-01-15T10:30:00Z",
      "valid_from": "2026-01-15T10:30:00Z",
      "valid_to": null
    }
  ],
  "services": [
    {
      "bindings": [
        {
          "created_at": "2026-07-29T15:23:06.660341Z",
          "first_discovery_id": null,
          "id": "999dbf39-0357-4b20-8bd8-cc20520334ea",
          "ip_address_id": "550e8400-e29b-41d4-a716-446655440005",
          "last_discovery_id": null,
          "last_seen_at": "2026-07-29T15:23:06.660341Z",
          "lineage_id": null,
          "network_id": "550e8400-e29b-41d4-a716-446655440002",
          "port_id": "550e8400-e29b-41d4-a716-446655440006",
          "service_id": "550e8400-e29b-41d4-a716-446655440007",
          "type": "Port",
          "updated_at": "2026-07-29T15:23:06.660341Z",
          "valid_from": "2026-07-29T15:23:06.660341Z",
          "valid_to": null
        }
      ],
      "created_at": "2026-01-15T10:30:00Z",
      "first_discovery_id": null,
      "host_id": "550e8400-e29b-41d4-a716-446655440003",
      "id": "550e8400-e29b-41d4-a716-446655440007",
      "last_discovery_id": null,
      "last_seen_at": "2026-01-15T10:30:00Z",
      "lineage_id": null,
      "name": "nginx",
      "network_id": "550e8400-e29b-41d4-a716-446655440002",
      "position": 0,
      "service_definition": "Unclaimed Open Ports",
      "source": {
        "type": "Manual"
      },
      "tags": [],
      "updated_at": "2026-01-15T10:30:00Z",
      "valid_from": "2026-01-15T10:30:00Z",
      "valid_to": null,
      "virtualization": null
    }
  ],
  "subnets": [
    {
      "cidr": "192.168.1.0/24",
      "created_at": "2026-01-15T10:30:00Z",
      "description": "Local area network",
      "first_discovery_id": null,
      "id": "550e8400-e29b-41d4-a716-446655440004",
      "last_discovery_id": null,
      "last_seen_at": "2026-01-15T10:30:00Z",
      "lineage_id": null,
      "name": "LAN",
      "network_id": "550e8400-e29b-41d4-a716-446655440002",
      "source": {
        "type": "Manual"
      },
      "subnet_type": "Lan",
      "tags": [],
      "updated_at": "2026-01-15T10:30:00Z",
      "valid_from": "2026-01-15T10:30:00Z",
      "valid_to": null
    }
  ]
}

Response

Host discovered/updated 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": {
    "created_at": "2026-01-15T10:30:00Z",
    "credential_assignments": [],
    "description": "Primary web server",
    "hidden": false,
    "hostname": "web-server-01.local",
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "interfaces": [
      {
        "admin_status": "Up",
        "cdp_address": null,
        "cdp_device_id": null,
        "cdp_platform": null,
        "cdp_port_id": null,
        "created_at": "2026-01-15T10:30:00Z",
        "first_discovery_id": null,
        "host_id": "550e8400-e29b-41d4-a716-446655440003",
        "id": "550e8400-e29b-41d4-a716-44665544000f",
        "if_alias": "Uplink to Core Switch",
        "if_descr": "GigabitEthernet0/1",
        "if_index": 1,
        "if_name": "Gi0/1",
        "if_type": 6,
        "ip_address_id": "550e8400-e29b-41d4-a716-446655440005",
        "last_discovery_id": null,
        "last_seen_at": "2026-01-15T10:30:00Z",
        "lineage_id": null,
        "lldp_chassis_id": null,
        "lldp_mgmt_addr": null,
        "lldp_port_desc": null,
        "lldp_port_id": null,
        "lldp_sys_desc": null,
        "lldp_sys_name": null,
        "mac_address": "DE:AD:BE:EF:CA:FE",
        "neighbor": null,
        "network_id": "550e8400-e29b-41d4-a716-446655440002",
        "oper_status": "Up",
        "speed_bps": 1000000000,
        "updated_at": "2026-01-15T10:30:00Z",
        "valid_from": "2026-01-15T10:30:00Z",
        "valid_to": null
      }
    ],
    "ip_addresses": [
      {
        "created_at": "2026-01-15T10:30:00Z",
        "first_discovery_id": null,
        "host_id": "550e8400-e29b-41d4-a716-446655440003",
        "id": "550e8400-e29b-41d4-a716-446655440005",
        "ip_address": "192.168.1.100",
        "last_discovery_id": null,
        "last_seen_at": "2026-01-15T10:30:00Z",
        "lineage_id": null,
        "mac_address": "DE:AD:BE:EF:CA:FE",
        "name": "eth0",
        "network_id": "550e8400-e29b-41d4-a716-446655440002",
        "position": 0,
        "subnet_id": "550e8400-e29b-41d4-a716-446655440004",
        "updated_at": "2026-01-15T10:30:00Z",
        "valid_from": "2026-01-15T10:30:00Z",
        "valid_to": null
      }
    ],
    "last_seen_at": "2026-01-15T10:30:00Z",
    "name": "web-server-01",
    "network_id": "550e8400-e29b-41d4-a716-446655440002",
    "ports": [
      {
        "created_at": "2026-01-15T10:30:00Z",
        "first_discovery_id": null,
        "host_id": "550e8400-e29b-41d4-a716-446655440003",
        "id": "550e8400-e29b-41d4-a716-446655440006",
        "last_discovery_id": null,
        "last_seen_at": "2026-01-15T10:30:00Z",
        "lineage_id": null,
        "network_id": "550e8400-e29b-41d4-a716-446655440002",
        "number": 80,
        "protocol": "Tcp",
        "type": "Http",
        "updated_at": "2026-01-15T10:30:00Z",
        "valid_from": "2026-01-15T10:30:00Z",
        "valid_to": null
      }
    ],
    "services": [
      {
        "bindings": [
          {
            "created_at": "2026-07-29T15:23:06.660146Z",
            "first_discovery_id": null,
            "id": "1065baf6-9ba7-46ec-aad9-9aa6ce7cfed6",
            "ip_address_id": "550e8400-e29b-41d4-a716-446655440005",
            "last_discovery_id": null,
            "last_seen_at": "2026-07-29T15:23:06.660146Z",
            "lineage_id": null,
            "network_id": "550e8400-e29b-41d4-a716-446655440002",
            "port_id": "550e8400-e29b-41d4-a716-446655440006",
            "service_id": "550e8400-e29b-41d4-a716-446655440007",
            "type": "Port",
            "updated_at": "2026-07-29T15:23:06.660146Z",
            "valid_from": "2026-07-29T15:23:06.660146Z",
            "valid_to": null
          }
        ],
        "created_at": "2026-01-15T10:30:00Z",
        "first_discovery_id": null,
        "host_id": "550e8400-e29b-41d4-a716-446655440003",
        "id": "550e8400-e29b-41d4-a716-446655440007",
        "last_discovery_id": null,
        "last_seen_at": "2026-01-15T10:30:00Z",
        "lineage_id": null,
        "name": "nginx",
        "network_id": "550e8400-e29b-41d4-a716-446655440002",
        "position": 0,
        "service_definition": "Unclaimed Open Ports",
        "source": {
          "type": "Manual"
        },
        "tags": [],
        "updated_at": "2026-01-15T10:30:00Z",
        "valid_from": "2026-01-15T10:30:00Z",
        "valid_to": null,
        "virtualization": null
      }
    ],
    "source": {
      "type": "Manual"
    },
    "tags": [],
    "updated_at": "2026-01-15T10:30:00Z",
    "virtualization": null
  },
  "meta": {
    "api_version": 1,
    "server_version": "0.17.7"
  }
}