Automate IP address allocation from a NetBox prefix using the REST API

Desired outcome

Create a child prefix inside an existing parent prefix and automatically assign the first available IP address from that child prefix to a device interface, all via NetBox’s REST API.

Prerequisites

• NetBox instance running version 3.5 or later (the API schema used is stable across this range).
• API token with write permissions on the ipam endpoints (prefixes and IP addresses).
• Knowledge of the parent prefix’s numeric ID (or its slug) that will contain the new child prefix.
• A device and interface already present in NetBox DCIM where the IP will be linked (or the IDs of those objects).
• Access to a Unix‑like shell with curl and jq (or any HTTP client that can send JSON and parse responses).

Procedure

1. Define environment variables for the NetBox URL, token, and parent prefix. Replace the placeholders with your actual values.

   NETBOX_URL="https://netbox.example.com/api"
   TOKEN="YOUR_WRITE_TOKEN"
   PARENT_PREFIX_ID=42   # numeric ID of the parent prefix, e.g. 10.0.0.0/16
   

2. Create a child prefix (e.g., 10.0.1.0/24) inside the parent. The request body includes the prefix length and the parent reference.

   curl -s -X POST "$NETBOX_URL/ipam/prefixes/" \
     -H "Authorization: Token $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"prefix":"10.0.1.0/24","parent":'$PARENT_PREFIX_ID'}' | jq .
   

   Expected response: HTTP 201 Created with a JSON object containing the new prefix’s id. Note the returned id as CHILD_PREFIX_ID for the next step.

3. Retrieve the first available IP address from the newly created child prefix. NetBox provides the available-ips endpoint for this purpose.

   curl -s -X GET "$NETBOX_URL/ipam/prefixes/$CHILD_PREFIX_ID/available-ips/" \
     -H "Authorization: Token $TOKEN" \
     -H "Content-Type: application/json" | jq '.[0]'   # first item in the list
   

   Expected response: HTTP 200 OK with a JSON object like {"address":"10.0.1.1/24"}. Extract the address value (without the mask) for assignment.

4. Assign the IP address to a device interface. You need the interface ID (INTERFACE_ID) where the address should be placed.

   IP_ADDRESS="10.0.1.1"   # from previous step, without mask
   curl -s -X POST "$NETBOX_URL/ipam/ip-addresses/" \
     -H "Authorization: Token $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"address":"'$IP_ADDRESS'/32","assigned_object_type":"dcim.interface","assigned_object_id":'$INTERFACE_ID'}' | jq .
   

   Expected response: HTTP 201 Created with the IP address record, showing the assigned_object link to the interface.

Expected checks

• After creating the child prefix, run a GET request to list child prefixes of the parent and verify the new prefix appears with the correct CIDR.
• After requesting an available IP, confirm that the address is not already assigned by checking GET /ipam/ip-addresses/?address=10.0.1.1/32 returns empty or only the newly created record.
• After assignment, verify the interface’s IP list includes the new address via GET /dcim/interfaces/$INTERFACE_ID/ and that the IP record shows status: "active" (or the status you set).

Recovery options

If any step fails or you need to undo changes:

1. To delete the assigned IP address: DELETE $NETBOX_URL/ipam/ip-addresses// where IP_ID is from the assignment response.
2. To delete the child prefix (only if it has no remaining IP allocations): DELETE $NETBOX_URL/ipam/prefixes//. NetBox will refuse the deletion if any IP addresses remain inside the prefix, preventing orphaned records.
3. Re‑run the availability check to confirm the address is now free again.

Limitations and practical verification

The API does not automatically prevent overlapping prefixes; you must ensure the child prefix stays within the parent’s address space. A quick verification is to compare the numeric start and end of the child prefix with those of the parent using a tool like ipcalc or a simple Python snippet:

python3 -c "import ipaddress; p=ipaddress.ip_network('10.0.0.0/16'); c=ipaddress.ip_network('10.0.1.0/24'); print('within:', c.subnet_of(p))"

If the output is True, the hierarchy is valid. Additionally, you can check the NetBox UI under IPAM → Prefixes to see the tree view and confirm the child appears indented under the parent.
Large batches of prefix creations or IP assignments can cause temporary spikes in database write load. Monitor the NetBox server’s CPU and DB latency during automation runs, and consider throttling requests (e.g., one per second) if you observe degradation.