Sign in

v62

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

List all hosts

Returns all hosts the authenticated user has access to, with their ip_addresses, ports, services and interfaces included — pass include_children=false to omit those and get a much smaller payload. Supports pagination via limit and offset query parameters, and ordering via group_by, order_by, and order_direction.

get/api/v1/hosts

Query parameters

network_idstring uuid nullable

Filter by network ID

idsstring[] nullable

Filter by specific entity IDs (for selective loading)

tag_idsstring[] nullable

Filter by tag IDs (returns hosts that have ANY of the specified tags)

searchstring nullable

Free-text search. Case-insensitive substring match against the host's name, hostname and description, and against its IP addresses and the names of services running on it.

group_by'created_at' | 'name' | 'hostname' | 'updated_at' | 'virtualized_by' | 'network_id' | 'interface_ip' | 'last_seen_at'

Fields that hosts can be ordered/grouped by.

Primary ordering field (used for grouping). Always sorts ASC to keep groups together.

order_by'created_at' | 'name' | 'hostname' | 'updated_at' | 'virtualized_by' | 'network_id' | 'interface_ip' | 'last_seen_at'

Fields that hosts can be ordered/grouped by.

Secondary ordering field (sorting within groups or standalone sort).

order_direction'asc' | 'desc'

Direction for ORDER BY clauses.

Direction for order_by field (group_by always uses ASC).

limitinteger nullable

Maximum number of results to return (1-1000, default: 50). Use 0 for no limit.

offsetinteger nullable

Number of results to skip. Default: 0.

atstring date-time nullable

As-of timestamp (ISO 8601). When set, returns SCD2 state as of this instant (snapshot view) instead of live state.

staleboolean nullable

true returns only hosts discovery hasn't observed within their network's staleness window; false returns only those it has. Omit for both. Evaluated per row against the host's own network's window.

include_childrenboolean nullable

false returns hosts with empty ip_addresses/ports/services/ interfaces. The children dominate the payload, so callers that only need host identity — name pickers, id→name lookups, counts — should pass false. Defaults to true, so existing callers are unaffected.

Response

List of hosts with their children

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.654949Z",
              "first_discovery_id": null,
              "id": "cdaa0fcd-d19d-48a9-9049-cd2526d9d826",
              "ip_address_id": "550e8400-e29b-41d4-a716-446655440005",
              "last_discovery_id": null,
              "last_seen_at": "2026-07-29T15:23:06.654949Z",
              "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.654949Z",
              "valid_from": "2026-07-29T15:23:06.654949Z",
              "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,
    "pagination": {
      "has_more": true,
      "limit": 50,
      "offset": 0,
      "total_count": 142
    },
    "server_version": "0.17.7"
  }
}