ScanopyScanopy
Hosts

Create a new host

Creates a host with optional ip_addresses, ports, and services. The source field is automatically set to Manual.

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
POST
/api/v1/hosts

Authorization

Authorization<token>

User API key (Bearer scp_u_...). Create in Platform > API Keys.

In: header

Request Body

application/json

name*string
network_id*string
Formatuuid
tags*array<string>
chassis_id?string|null
credential_assignments?
description?string|null
hidden?boolean
hostname?string|null
interfaces?

SNMP interface entries (ifTable data) - server assigns UUIDs

ip_addresses?

Interfaces to create with this host (client provides UUIDs)

management_url?string|null
ports?

Ports to create with this host (client provides UUIDs)

services?

Services to create with this host (can reference ip_addresses/ports by their UUIDs)

sys_contact?string|null
sys_descr?string|null
sys_location?string|null
sys_object_id?string|null
virtualization?null|

Response Body

application/json

application/json

application/json

curl -X POST "https://loading/api/v1/hosts" \  -H "Content-Type: application/json" \  -d '{    "credential_assignments": [],    "description": "Primary web server",    "hidden": false,    "hostname": "web-server-01.local",    "interfaces": [],    "ip_addresses": [      {        "id": "550e8400-e29b-41d4-a716-446655440005",        "ip_address": "192.168.1.100",        "mac_address": "DE:AD:BE:EF:12:34",        "name": "eth0",        "position": 0,        "subnet_id": "550e8400-e29b-41d4-a716-446655440004"      }    ],    "name": "web-server-01",    "network_id": "550e8400-e29b-41d4-a716-446655440002",    "ports": [      {        "id": "550e8400-e29b-41d4-a716-446655440006",        "number": 80,        "protocol": "Tcp"      }    ],    "services": [      {        "bindings": [          {            "id": "550e8400-e29b-41d4-a716-446655440009",            "ip_address_id": "550e8400-e29b-41d4-a716-446655440005",            "port_id": "550e8400-e29b-41d4-a716-446655440006",            "type": "Port"          }        ],        "id": "550e8400-e29b-41d4-a716-446655440007",        "name": "nginx",        "position": 0,        "service_definition": "MySQL",        "tags": [],        "virtualization": null      }    ],    "tags": [],    "virtualization": null  }'
{
  "meta": {
    "api_version": 1,
    "server_version": "0.17.7"
  },
  "success": true,
  "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-29T01:29:50.375125Z",
            "first_discovery_id": null,
            "id": "42977d9d-07f3-40f5-904a-a9872d72e7b2",
            "ip_address_id": "550e8400-e29b-41d4-a716-446655440005",
            "last_discovery_id": null,
            "last_seen_at": "2026-07-29T01:29:50.375125Z",
            "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-29T01:29:50.375125Z",
            "valid_from": "2026-07-29T01:29:50.375125Z",
            "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": "MySQL",
        "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
  },
  "error": "string"
}
{
  "meta": {
    "api_version": 1,
    "server_version": "0.17.7"
  },
  "success": true,
  "code": "string",
  "error": "string",
  "params": {
    "property1": null,
    "property2": null
  }
}
{
  "meta": {
    "api_version": 1,
    "server_version": "0.17.7"
  },
  "success": true,
  "code": "string",
  "error": "string",
  "params": {
    "property1": null,
    "property2": null
  }
}

Bulk delete hosts

Deletes multiple hosts in a single request. The request body should be an array of host IDs to delete. Fails if any host has an associated daemon.

Rescan a host

Starts a one-shot scan of this host's addresses and nothing else, answering "is this host still there, and is its data current?" without sweeping the whole subnet. The scan runs on the daemon that last discovered this host — evidence it can reach the address — and only if that daemon still has an interface on a subnet containing one of the host's IPs. That constraint is what lets the daemon ARP the target rather than fall back to a TCP probe, which would report a live but firewalled host as unresponsive. When it can't be met the request is refused with the specific reason rather than run at lower fidelity. Returns the session, which streams progress over `/api/v1/discovery/stream` like any other scan. A `Queued` phase means the daemon is busy; it will start when the running scan finishes.