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": "GitLab",        "tags": [],        "virtualization": null      }    ],    "tags": [],    "virtualization": null  }'
{
  "meta": {
    "api_version": 1,
    "server_version": "0.16.0"
  },
  "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",
        "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",
        "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"
      }
    ],
    "ip_addresses": [
      {
        "created_at": "2026-01-15T10:30:00Z",
        "host_id": "550e8400-e29b-41d4-a716-446655440003",
        "id": "550e8400-e29b-41d4-a716-446655440005",
        "ip_address": "192.168.1.100",
        "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"
      }
    ],
    "name": "web-server-01",
    "network_id": "550e8400-e29b-41d4-a716-446655440002",
    "ports": [
      {
        "created_at": "2026-01-15T10:30:00Z",
        "host_id": "550e8400-e29b-41d4-a716-446655440003",
        "id": "550e8400-e29b-41d4-a716-446655440006",
        "network_id": "550e8400-e29b-41d4-a716-446655440002",
        "number": 80,
        "protocol": "Tcp",
        "type": "Http",
        "updated_at": "2026-01-15T10:30:00Z"
      }
    ],
    "services": [
      {
        "bindings": [
          {
            "created_at": "2026-04-17T16:32:49.045955Z",
            "id": "40b9463a-420c-4ddf-90b7-4eeb6fe5180f",
            "ip_address_id": "550e8400-e29b-41d4-a716-446655440005",
            "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-04-17T16:32:49.045955Z"
          }
        ],
        "created_at": "2026-01-15T10:30:00Z",
        "host_id": "550e8400-e29b-41d4-a716-446655440003",
        "id": "550e8400-e29b-41d4-a716-446655440007",
        "name": "nginx",
        "network_id": "550e8400-e29b-41d4-a716-446655440002",
        "position": 0,
        "service_definition": "GitLab",
        "source": {
          "type": "Manual"
        },
        "tags": [],
        "updated_at": "2026-01-15T10:30:00Z",
        "virtualization": null
      }
    ],
    "source": {
      "type": "Manual"
    },
    "tags": [],
    "updated_at": "2026-01-15T10:30:00Z",
    "virtualization": null
  },
  "error": "string"
}
{
  "meta": {
    "api_version": 1,
    "server_version": "0.16.0"
  },
  "success": true,
  "code": "string",
  "error": "string",
  "params": {
    "property1": null,
    "property2": null
  }
}
{
  "meta": {
    "api_version": 1,
    "server_version": "0.16.0"
  },
  "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.

Consolidate hosts

Merges all ip_addresses, ports, and services from `other_host` into `destination_host`, then deletes `other_host`. Both hosts must be on the same network. ### Merge Behavior - **Interfaces**: Transferred to destination. If an interface with matching subnet+IP or MAC already exists on destination, bindings are remapped to use the existing interface. - **Ports**: Transferred to destination. If a port with the same number and protocol already exists, bindings are remapped to use the existing port. - **Services**: Transferred to destination with deduplication. See [upsert behavior](https://scanopy.net/docs/discovery/#upsert-behavior) for details. ### Restrictions - Cannot consolidate a host with itself. - Cannot consolidate a host that has a daemon - consolidate into it instead.