IPAM

GET /ipam/addresses

List IP addresses

Returns a paginated list of IP addresses with optional role, device, DNS, and DHCP filtering

Query Parameters:

  • site_id (integer) – NetBox site ID

  • roles (array) – Filter by network roles (management, storage, public, guest)

  • device_id (integer) – Filter by NetBox device ID

  • search (string) – Search term

  • status (string) – IP status filter (active, reserved, deprecated, dhcp)

  • has_dns (boolean) – Filter IPs with DNS records

  • has_dhcp (boolean) – Filter IPs with DHCP reservations

  • page (integer) – Page number, 1-based (default: 1)

  • page_size (integer) – Page size (default: 50, max: 500)

  • sort (string) – Sort column: ip, dns_name, device, role, vlan, status, mac, created_at

  • order (string) – Sort order: asc, desc (default: asc)

Status Codes:
Response JSON Object:

  • page (integer) – Current page number (1-based)

  • page_size (integer) – Page size used

  • results[].address (string) – IP address with CIDR (e.g., “192.168.11.5/24”)

  • results[].cloud_stack_id (string) – CloudStack UUID (karios_cs_ip_id custom field)

  • results[].created_at (string) – Creation timestamp

  • results[].description (string) – Metadata

  • results[].device (any) – Device & Interface Information (physical devices)

  • results[].dhcp_reservation (any) – DDI Status

  • results[].dns_name (string) – DNS Information

  • results[].dns_records (any) – DNS record status

  • results[].dns_zone (string) – DNS zone (e.g., “umb.com”, “storage.umb.com”)

  • results[].gateway (string) – Default gateway

  • results[].id (integer) – Basic IP Information

  • results[].interface (any) – Interface (virtual bridge or physical)

  • results[].ip (string) – IP address only (e.g., “192.168.11.5”)

  • results[].mac_address (string) – MAC address

  • results[].netmask (string) – Subnet mask

  • results[].prefix_cidr (string) – Prefix CIDR (e.g., “192.168.11.0/24”)

  • results[].prefix_id (integer) – NetBox prefix ID

  • results[].ptr (boolean) – PTR record exists

  • results[].role (string) – Network Context

  • results[].status (string) – IP status (active, reserved, deprecated, dhcp)

  • results[].updated_at (string) – Last update timestamp

  • results[].virtual_bridge (any) – Virtual bridge details (if applicable)

  • results[].virtual_machine (any) – Virtual Machine Information (CloudStack VMs)

  • results[].vlan (any) – VLAN information

  • results[].vm_interface (any) – VMInterface this IP is assigned to

  • results[].vrf (any) – VRF information (if used)

  • total (integer) – Total matching records (before pagination)

GET /ipam/addresses/counts

Count IP addresses

Returns total and per-role IP address counts for a site

Query Parameters:

  • site_id (integer) – NetBox site ID (optional when NETBOX_SITE_NAME env var is set)

  • roles (array) – Restrict counts to specific network roles

Status Codes:
Response JSON Object:

  • by_role (object)

  • total (integer)

POST /ipam/allocate

Allocate IP address

Allocates the next available IP from a network role prefix, optionally creating DNS and DHCP records

Request JSON Object:

  • create_dns (boolean) – Create Technitium DNS A record

  • device_id (integer) – Optional: NetBox device ID — if provided, site_id is resolved automatically

  • dns_name (string) – DNS name (required if CreateDNS=true)

  • dns_zone (string) – DNS zone for A/PTR records (e.g. “karios.local”); resolved from site domain_name if empty

  • interface_id (integer) – Optional: NetBox interface ID to assign IP to

  • mac_address (string) – MAC address (optional, auto-generated if not provided)

  • network_role (string) – “management” or “storage” ONLY

  • parent_interface (string) – Optional: Physical interface name (e.g., “eth0”) for virtual bridge creation (legacy)

  • parent_interface_mac (string) – Optional: MAC of physical interface — preferred over name; resolved via GetInterfaceByDeviceAndMAC

  • prefix_id (integer) – Optional: NetBox prefix ID — use the value from GET /api/v2/ipam/vlans to bypass role lookup

  • purpose (string) – “Hypervisor mgmt”, “Storage network”, etc.

  • site_id (integer) – Optional when device_id is provided — derived from device’s site automatically

  • vlan_filter (integer) – Optional: NetBox VLAN ID — fallback when prefix_id is not provided

Status Codes:
Response JSON Object:

  • allocated_outside (string) – Note if allocated outside VIP range

  • cidr (string) – Full CIDR (e.g., “192.168.11.22/24”)

  • dhcp_reserved (boolean) – DHCP reservation created in Technitium

  • dns_created (boolean) – DNS A record created in Technitium

  • dns_servers[] (string)

  • excluded_vip_range (string) – VIP range that was excluded

  • gateway (string) – Gateway IP for network

  • ip (string) – Allocated IP address (e.g., “192.168.11.22”)

  • mac_address (string) – MAC address (user-provided or auto-generated)

  • netbox_ip_id (integer) – NetBox IP address object ID

  • netmask (string) – Netmask (e.g., “255.255.255.0”)

  • prefix_id (integer) – NetBox prefix ID

  • virtual_bridge (any) – Virtual bridge info if created

GET /ipam/ranges

List IP ranges

Returns a list of IP ranges (e.g. VIP or DHCP ranges) enriched with parent prefix context

Query Parameters:

  • site_id (integer) – NetBox site ID

  • roles (array) – Filter by parent prefix network roles

  • status (string) – Range status filter (active, reserved, deprecated)

  • limit (integer) – Maximum number of results to return

  • offset (integer) – Number of results to skip

Status Codes:
Response JSON Object:

  • count (integer)

  • results[].description (string) – Human-readable label (e.g. “VIP Range”, “DHCP Range”)

  • results[].end_address (string) – Range end (e.g. “192.168.11.21”)

  • results[].id (integer) – NetBox IP range ID

  • results[].parent_prefix_cidr (string) – e.g. “192.168.11.0/24”

  • results[].parent_prefix_id (integer) – Parent prefix context (association via IP math — no FK in NetBox)

  • results[].parent_role (string) – management | storage | guest | public | bmc

  • results[].parent_vlan_id (integer) – VLAN ID (0 if none)

  • results[].parent_vlan_vid (integer) – VLAN tag number (0 if none)

  • results[].site_id (integer)

  • results[].size (integer) – Number of IPs in range (inclusive)

  • results[].start_address (string) – Range start (e.g. “192.168.11.2”)

  • results[].status (string) – active | reserved | deprecated

POST /ipam/release

Release IP address

Releases an allocated IP address from NetBox and optionally removes associated DNS and DHCP records

Request JSON Object:

  • delete_dhcp (boolean) – Delete DHCP reservation from Technitium

  • delete_dns (boolean) – Delete DNS record from Technitium

  • dns_name (string) – DNS name to delete

  • ip (string) – IP address to release

  • mac_address (string) – MAC address for DHCP reservation deletion

  • netbox_ip_id (integer) – NetBox IP address ID

Status Codes:
Response JSON Object:

  • dhcp_deleted (boolean) – DHCP reservation deleted

  • dns_deleted (boolean) – DNS record deleted

  • ip (string) – Released IP address

  • netbox_ip_id (integer) – NetBox IP address ID

GET /ipam/scopes

List prefixes (scopes)

Returns a paginated list of IP prefixes enriched with DHCP scope details and utilization statistics

Query Parameters:

  • site_id (integer) – NetBox site ID

  • roles (array) – Filter by network roles (management, storage, public, guest)

  • status (string) – Prefix status filter (active, reserved, deprecated)

  • vlan_id (integer) – Filter by VLAN ID

  • family (integer) – IP family (4 or 6)

  • page (integer) – Page number, 1-based (default: 1)

  • page_size (integer) – Page size (default: 50, max: 500)

  • sort (string) – Sort column: prefix, vlan, role, status, gateway

  • order (string) – Sort order: asc, desc (default: asc)

Status Codes:
Response JSON Object:

  • page (integer) – Current page number (1-based)

  • page_size (integer) – Page size used

  • results[].allocatable_ips (integer) – Allocatable IPs (total - VIP count)

  • results[].allocated_ips (integer) – Number of allocated IPs

  • results[].available_ips (integer) – Number of available IPs (allocatable - allocated)

  • results[].created_at (string) – Creation timestamp

  • results[].description (string) – Prefix description

  • results[].dhcp_scope (any) – DHCP Scope Information

  • results[].dns_zone (string) – DNS zone/domain for this prefix

  • results[].family (integer) – IP family (4 or 6)

  • results[].gateway (string) – Default gateway for this prefix

  • results[].id (integer) – Basic Prefix Information

  • results[].prefix (string) – CIDR notation (e.g., “192.168.10.0/24”)

  • results[].role (string) – Network Context

  • results[].site_id (integer) – Metadata

  • results[].status (string) – Prefix status (active, reserved, deprecated)

  • results[].total_ips (integer) – IP Utilization

  • results[].updated_at (string) – Last update timestamp

  • results[].utilization (number) – Utilization % of allocatable IPs (0-100)

  • results[].vip_count (integer) – Number of VIP/reserved IPs

  • results[].vip_range_end (string) – End of VIP/reserved range

  • results[].vip_range_start (string) – VIP Range (Reserved IPs)

  • results[].vlan (any) – VLAN information

  • results[].vrf (any) – VRF information (if used)

  • total (integer) – Total matching records (before pagination)

GET /ipam/scopes/counts

Count prefixes (scopes)

Returns total and per-role prefix (scope) counts for a site

Query Parameters:

  • site_id (integer) – NetBox site ID (optional when NETBOX_SITE_NAME env var is set)

  • roles (array) – Restrict counts to specific network roles

Status Codes:
Response JSON Object:

  • by_role (object)

  • total (integer)

GET /ipam/vlans

List VLANs

Returns a paginated list of VLANs enriched with associated prefix, gateway, and DHCP scope information

Query Parameters:

  • site_id (integer) – NetBox site ID

  • roles (array) – Filter by network roles (management, storage, public, guest)

  • status (string) – VLAN status filter (active, reserved, deprecated)

  • page (integer) – Page number, 1-based (default: 1)

  • page_size (integer) – Page size (default: 50, max: 500)

Status Codes:
Response JSON Object:

  • page (integer) – Current page number (1-based)

  • page_size (integer) – Page size used

  • results[].dhcp_scope_name (string) – DHCP Integration — read from VLAN custom field “dhcp_scope_name”

  • results[].dns_zone (string) – DNS zone from prefix or site custom field

  • results[].gateway (string) – Gateway IP from prefix custom field

  • results[].id (integer) – Basic VLAN Information

  • results[].name (string) – VLAN name (e.g., “VLAN 120 - Management”)

  • results[].prefix_cidr (string) – Prefix CIDR (e.g., “192.168.11.0/24”)

  • results[].prefix_id (integer) – Associated Prefix — enriched from NetBox (one prefix per VLAN per site)

  • results[].role (string) – Network role slug (management, storage, public, guest)

  • results[].site_id (integer) – Site context

  • results[].status (string) – VLAN status (active, reserved, deprecated)

  • results[].vid (integer) – VLAN tag number (e.g., 120)

  • total (integer) – Total matching records (before pagination)

GET /ipam/vlans/counts

Count VLANs

Returns total and per-role VLAN counts for a site

Query Parameters:

  • site_id (integer) – NetBox site ID (optional when NETBOX_SITE_NAME env var is set)

  • roles (array) – Restrict counts to specific network roles

Status Codes:
Response JSON Object:

  • by_role (object)

  • total (integer)

POST /network/public-ip-pools/list

List public-IP prefix pools with free counts

Request JSON Object:

  • prefix_ids[] (integer)

  • role_id (integer)