NetBox IPAM: Prefixes, VRFs, and API-Driven Address Planning

Start with the outage, not the API

A network engineer receives a ticket: a new server rack needs an IPv4 subnet, but the address plan spreadsheet shows the block as free while the CMDB shows it assigned to a decommissioned load balancer. Choosing the wrong block causes an IP conflict and an outage. NetBox can prevent this by acting as the authoritative source of truth for intended IP space, but only if the team models prefixes and VRFs deliberately and understands what NetBox does and does not do with that data.

Prefix containment and VRF scope

NetBox IPAM organizes addresses hierarchically. A prefix is a CIDR block such as 10.10.0.0/16. Prefixes can nest inside parent prefixes, and NetBox rejects a new prefix that does not fit inside its parent. A VRF, or virtual routing and forwarding context, separates overlapping address space so the same private subnet can exist in different routing domains without conflict. NetBox enforces IP uniqueness within a VRF, which means two interfaces cannot use 10.10.20.10/24 in the same VRF, but can in different VRFs.

Prefixes also carry a role, such as infrastructure, customer, or loopback, and a status such as active or reserved. These built-in fields cover most addressing metadata. For anything else, NetBox offers custom fields, which attach key-value data to objects without schema changes. Custom fields are flexible but not relational, so using them for foreign-key-like relationships complicates filtering and reporting.

Worked example: create a prefix and assign an IP

Run these commands from a host with network access to NetBox and the curl command installed. You need an API token with write permission for the ipam application. Replace every placeholder surrounded by ${} with values from your instance. Field names and nesting can differ between NetBox major versions, so confirm your release with GET /api/status/ before adapting this example.

# Check version and API availability
curl -s -H "Authorization: Token ${API_TOKEN}" \
  "${NETBOX_URL}/api/status/"

# Confirm the prefix does not already exist in the target VRF
curl -s -H "Authorization: Token ${API_TOKEN}" \
  "${NETBOX_URL}/api/ipam/prefixes/?vrf=${VRF_ID}&prefix=${PARENT_PREFIX}"

# Create the prefix
curl -s -X POST -H "Authorization: Token ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "prefix": "10.10.20.0/24",
    "vrf": ${VRF_ID},
    "site": ${SITE_ID},
    "role": ${ROLE_ID},
    "status": "active",
    "custom_fields": {
      "owner": "platform-team",
      "circuit_id": "CIRC-1234"
    }
  }' \
  "${NETBOX_URL}/api/ipam/prefixes/"

# Assign an IP address from that prefix
curl -s -X POST -H "Authorization: Token ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "10.10.20.10/24",
    "vrf": ${VRF_ID},
    "status": "active"
  }' \
  "${NETBOX_URL}/api/ipam/ip-addresses/"

Expected checks: the prefix POST should return HTTP 201 and include the new prefix ID. The IP POST should also return HTTP 201. Verify both with a follow-up GET request using the returned IDs. If either call returns 400 or 409, inspect the response body for containment or uniqueness violations.

Rollback

Because these calls change state, reverse them in the opposite order if the assignment was a mistake. Delete the IP address first, then the prefix, because NetBox will not allow deletion of a prefix that still contains child objects or assigned addresses.

curl -s -X DELETE -H "Authorization: Token ${API_TOKEN}" \
  "${NETBOX_URL}/api/ipam/ip-addresses/${IP_ADDRESS_ID}/"

curl -s -X DELETE -H "Authorization: Token ${API_TOKEN}" \
  "${NETBOX_URL}/api/ipam/prefixes/${PREFIX_ID}/"

Trade-offs and limits

NetBox records intended state. Creating a prefix or IP address in NetBox does not configure a router, switch, or server. A separate automation system must read NetBox and push configuration to devices.

Bulk API writes generate one object-change log entry per object and can trigger webhook deliveries for each change. On a large instance, a single bulk import can slow the web UI and overwhelm subscribed automation. Custom fields help avoid schema migrations, but overusing them turns NetBox into a poorly indexed document store. Prefer built-in fields for status, role, and VRF, and reserve custom fields for genuinely sparse metadata.

Verify before you trust it

After writing, call GET /api/ipam/prefixes/${PREFIX_ID}/ and confirm the returned prefix, VRF, and custom fields match what you sent. In the NetBox UI, open the prefix and check the change log for the create event, including user and timestamp. For ongoing automation, compare the external system's address list against GET /api/ipam/prefixes/ on a schedule rather than assuming the two systems stay in sync.

Closing

Pick one VRF and one custom field to pilot. Use read-only API calls first to export NetBox data into your CMDB or configuration management tool. Once the data model is stable, add write automation with the rollback steps above. Treat NetBox as the source of truth for intended addressing, not as a device configurator, and your address plan will stop contradicting itself.