openclaw/skills/netbox/SKILL.md

name	description	homepage	metadata
netbox	Query and manage network infrastructure using the NetBox REST API. Search devices, IP addresses, prefixes, and manage IP allocations.	https://docs.netbox.dev/en/stable/	openclaw emoji requires 🌐 bins env curl jq NETBOX_URL NETBOX_TOKEN

NetBox Skill

Query and manage network infrastructure using the NetBox REST API.

Setup

Set environment variables:

export NETBOX_URL="http://netbox.example.com:8080"
export NETBOX_TOKEN="your-api-token"

Common Variables

All commands use these headers:

AUTH="Authorization: Token $NETBOX_TOKEN"
CT="Content-Type: application/json"

---

IPAM Operations

Search IP Addresses

Search by address:

curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/ip-addresses/?address=10.0.0.1" | jq '.results[] | {id, address, status: .status.value, dns_name, description}'

Search by partial address (contains):

curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/ip-addresses/?address__ic=10.0.0" | jq '.results[] | {id, address, status: .status.value}'

Search by DNS name:

curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/ip-addresses/?dns_name__ic=myserver" | jq '.results[] | {id, address, dns_name}'

List IPs assigned to a device:

curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/ip-addresses/?device=mydevice" | jq '.results[] | {address, interface: .assigned_object.name}'

Search Prefixes

List all prefixes:

curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/prefixes/?limit=50" | jq '.results[] | {id, prefix, status: .status.value, site: .site.name, vlan: .vlan.vid}'

Search prefix by network:

curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/prefixes/?prefix=10.0.0.0/24" | jq '.results[] | {id, prefix, status: .status.value, description}'

Search prefixes containing an IP:

curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/prefixes/?contains=10.0.0.50" | jq '.results[] | {prefix, site: .site.name}'

Search prefixes within a parent:

curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/prefixes/?within=10.0.0.0/16" | jq '.results[] | {prefix, status: .status.value}'

Search by site:

curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/prefixes/?site=dc1" | jq '.results[] | {prefix, vlan: .vlan.vid, role: .role.name}'

Get IP Availability in a Prefix

Get available IPs in a prefix (requires prefix ID):

# First get the prefix ID
PREFIX_ID=$(curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/prefixes/?prefix=10.0.0.0/24" | jq -r '.results[0].id')

# Then get available IPs
curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/prefixes/$PREFIX_ID/available-ips/" | jq '.[0:10]'

Get prefix utilization:

curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/prefixes/?prefix=10.0.0.0/24" | jq '.results[] | {prefix, description, children: .children, utilization: "\(.mark_utilized)%"}'

Create/Reserve IP Address

Create a new IP address:

curl -s -X POST -H "$AUTH" -H "$CT" "$NETBOX_URL/api/ipam/ip-addresses/" \
  -d '{
    "address": "10.0.0.100/24",
    "status": "active",
    "dns_name": "myserver.example.com",
    "description": "Web server primary IP"
  }' | jq '{id, address, status: .status.value}'

Reserve next available IP in a prefix:

# First get the prefix ID
PREFIX_ID=$(curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/prefixes/?prefix=10.0.0.0/24" | jq -r '.results[0].id')

# Create next available IP
curl -s -X POST -H "$AUTH" -H "$CT" "$NETBOX_URL/api/ipam/prefixes/$PREFIX_ID/available-ips/" \
  -d '{
    "description": "Reserved for new server",
    "status": "reserved"
  }' | jq '{id, address, status: .status.value}'

Reserve multiple IPs at once:

curl -s -X POST -H "$AUTH" -H "$CT" "$NETBOX_URL/api/ipam/prefixes/$PREFIX_ID/available-ips/" \
  -d '[
    {"description": "Server 1", "status": "reserved"},
    {"description": "Server 2", "status": "reserved"}
  ]' | jq '.[] | {address, description}'

Update IP Address

curl -s -X PATCH -H "$AUTH" -H "$CT" "$NETBOX_URL/api/ipam/ip-addresses/{id}/" \
  -d '{
    "status": "active",
    "dns_name": "newname.example.com"
  }' | jq '{id, address, status: .status.value, dns_name}'

Delete IP Address

curl -s -X DELETE -H "$AUTH" "$NETBOX_URL/api/ipam/ip-addresses/{id}/"

---

DCIM Operations

Search Devices

List devices:

curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/devices/?limit=50" | jq '.results[] | {id, name, status: .status.value, site: .site.name, role: .role.name}'

Search by name:

curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/devices/?name__ic=server" | jq '.results[] | {id, name, status: .status.value, primary_ip: .primary_ip.address}'

Search by site:

curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/devices/?site=dc1" | jq '.results[] | {name, rack: .rack.name, position: .position}'

Search by role:

curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/devices/?role=server" | jq '.results[] | {name, device_type: .device_type.model}'

Search by serial number:

curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/devices/?serial=ABC123" | jq '.results[] | {name, serial, asset_tag}'

Get device details:

curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/devices/{id}/" | jq '{name, status: .status.value, site: .site.name, rack: .rack.name, position, primary_ip4: .primary_ip4.address, primary_ip6: .primary_ip6.address}'

List Device Interfaces

curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/interfaces/?device=mydevice" | jq '.results[] | {id, name, type: .type.value, enabled, mac_address}'

Search Sites

curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/sites/" | jq '.results[] | {id, name, slug, status: .status.value, region: .region.name}'

Search Racks

curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/racks/?site=dc1" | jq '.results[] | {id, name, u_height, status: .status.value}'

---

VLANs

List VLANs

curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/vlans/" | jq '.results[] | {id, vid, name, status: .status.value, site: .site.name}'

Search VLAN by ID

curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/vlans/?vid=100" | jq '.results[] | {vid, name, description}'

---

Virtualization

List Virtual Machines

curl -s -H "$AUTH" "$NETBOX_URL/api/virtualization/virtual-machines/" | jq '.results[] | {id, name, status: .status.value, cluster: .cluster.name, vcpus, memory, disk}'

Search VM by name

curl -s -H "$AUTH" "$NETBOX_URL/api/virtualization/virtual-machines/?name__ic=web" | jq '.results[] | {name, primary_ip: .primary_ip.address}'

---

Tips

Pagination

NetBox returns paginated results. Use limit and offset:

curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/devices/?limit=100&offset=200" | jq '.results'

Filtering

Common filter suffixes:

• __ic - case-insensitive contains
• __nic - case-insensitive not contains
• __ie - case-insensitive exact
• __isw - case-insensitive starts with
• __iew - case-insensitive ends with

Status Values

Common status values:

• IP addresses: active, reserved, deprecated, dhcp, slaac
• Devices: active, planned, staged, failed, offline, decommissioning, inventory
• Prefixes: active, reserved, deprecated, container

Get All Results (scripting)

# Loop through paginated results
OFFSET=0
LIMIT=100
while true; do
  RESULT=$(curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/devices/?limit=$LIMIT&offset=$OFFSET")
  echo "$RESULT" | jq -r '.results[] | .name'
  NEXT=$(echo "$RESULT" | jq -r '.next')
  [ "$NEXT" = "null" ] && break
  OFFSET=$((OFFSET + LIMIT))
done

Export to CSV

curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/ip-addresses/?limit=1000" | \
  jq -r '.results[] | [.address, .dns_name, .status.value, .description] | @csv'

Examples

Find which device has a specific IP

IP="10.0.0.50"
curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/ip-addresses/?address=$IP" | \
  jq '.results[] | {address, device: .assigned_object.device.name, interface: .assigned_object.name}'

List all IPs in a subnet with their assignments

curl -s -H "$AUTH" "$NETBOX_URL/api/ipam/ip-addresses/?parent=10.0.0.0/24" | \
  jq '.results[] | {address, dns_name, device: .assigned_object.device.name // "unassigned"}'

Get rack utilization

curl -s -H "$AUTH" "$NETBOX_URL/api/dcim/racks/?site=dc1" | \
  jq '.results[] | {name, u_height, utilized: "\(.u_utilized // 0)/\(.u_height)"}'