ScanopyScanopy
Hosts

Create a new host

Creates a host with optional interfaces, 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>
description?string|null
hidden?boolean
hostname?string|null
interfaces?

Interfaces to create with this host (client provides UUIDs)

ports?

Ports to create with this host (client provides UUIDs)

services?

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

virtualization?null|

Response Body

application/json

application/json

application/json

curl -X POST "https://loading/api/v1/hosts" \  -H "Content-Type: application/json" \  -d '{    "description": "Primary web server",    "hidden": false,    "hostname": "web-server-01.local",    "interfaces": [      {        "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",            "interface_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": "Remote Desktop",        "tags": [],        "virtualization": null      }    ],    "tags": [],    "virtualization": null  }'
{
  "meta": {
    "api_version": 1,
    "server_version": "0.13.5"
  },
  "success": true,
  "data": {
    "created_at": "2026-01-15T10:30:00Z",
    "description": "Primary web server",
    "hidden": false,
    "hostname": "web-server-01.local",
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "interfaces": [
      {
        "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:12:34",
        "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": [],
    "source": {
      "type": "Manual"
    },
    "tags": [],
    "updated_at": "2026-01-15T10:30:00Z",
    "virtualization": null
  },
  "error": "string"
}
{
  "success": true,
  "error": "string"
}
{
  "success": true,
  "error": "string"
}

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 interfaces, 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.