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
User API key (Bearer scp_u_...). Create in Platform > API Keys.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Request type for creating a host with its associated ip_addresses, ports, and services.
Server assigns host_id, network_id, and source to all children.
Client must provide UUIDs for all entities, enabling services to reference
ip_addresses/ports by ID in the same request.
Response Body
application/json
application/json
application/json
curl -X POST "https://example.com/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": "Ollama", "tags": [], "virtualization_metadata": null, "virtualization_service_id": null } ], "tags": [], "virtualization_metadata": null, "virtualization_service_id": null }'{
"meta": {
"api_version": 1,
"server_version": "0.17.13"
},
"success": true,
"data": {
"chassis_id_source": "Unspecified",
"created_at": "2026-01-15T10:30:00Z",
"credential_assignments": [],
"description": "Primary web server",
"display_name": "web-server-01",
"firmware_revision": null,
"firmware_revision_source": "Unspecified",
"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",
"mac_address_source": "ArpReply",
"neighbor": null,
"neighbor_seen_at": 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",
"mac_address_source": "ArpReply",
"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",
"management_url_source": "Unspecified",
"manufacturer_source": "Unspecified",
"model_source": "Unspecified",
"name": "web-server-01",
"name_source": "Manual",
"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
}
],
"serial_number_source": "Unspecified",
"services": [
{
"bindings": [
{
"created_at": "2026-08-28T15:33:32.412433Z",
"first_discovery_id": null,
"id": "46c768fc-45d3-4293-8c4c-20a06d0409c4",
"ip_address_id": "550e8400-e29b-41d4-a716-446655440005",
"last_discovery_id": null,
"last_seen_at": "2026-08-28T15:33:32.412433Z",
"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-08-28T15:33:32.412433Z",
"valid_from": "2026-08-28T15:33:32.412433Z",
"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": "Ollama",
"source": {
"type": "Manual"
},
"tags": [],
"updated_at": "2026-01-15T10:30:00Z",
"valid_from": "2026-01-15T10:30:00Z",
"valid_to": null,
"virtualization_metadata": null,
"virtualization_service_id": null
}
],
"software_revision": null,
"software_revision_source": "Unspecified",
"source": {
"type": "Manual"
},
"sys_contact_source": "Unspecified",
"sys_descr_source": "Unspecified",
"sys_location_source": "Unspecified",
"sys_name_source": "Unspecified",
"sys_object_id_source": "Unspecified",
"tags": [],
"updated_at": "2026-01-15T10:30:00Z",
"virtualization_metadata": null,
"virtualization_service_id": null
},
"error": "string"
}{
"meta": {
"api_version": 1,
"server_version": "0.17.13"
},
"success": true,
"code": "string",
"error": "string",
"params": {
"property1": null,
"property2": null
}
}{
"meta": {
"api_version": 1,
"server_version": "0.17.13"
},
"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 scannable IPs. Where that interface has a MAC the daemon ARPs the target, which sees a live host even when every port is firewalled; on a MAC-less interface (a point-to-point tunnel) it falls back to a TCP probe. When no interface covers any of the host's addresses the request is refused with the specific reason. A loopback address is not a scannable IP — it is reached locally and is excluded from the target set. 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.