Why Automate NetBox at all ?
If you followed my last post, you now know how to confidently navigate NetBox's GUI. Creating sites, racks, devices, prefixes, and IP addresses through the web interface. For a small lab or a new deployment, that's perfectly fine.
But here's the reality of production network environments: you might have hundreds of devices to onboard, thousands of IP addresses to track, and a team of people who all need NetBox to reflect the truth of what's actually running in your infrastructure right now. Navigating a web form for each record quickly becomes impractical. Even worse, manual data entry can lead to human error such as a typo in an IP address, an incorrect VLAN assignment, or a device that was never added because someone forgot.
This is where automation changes everything. When NetBox is automated, it stops being a wiki that you have to remember to update and starts becoming a living, accurate source of truth that updates itself as part of your normal workflows. Devices get added when they're provisioned. IPs get allocated when servers are built. Status fields change as part of your change management process and not three days later when someone remembers.
In this article we look at automation approaches you can use with your running NetBox instance. Each one solves a different problem, and by the end you'll know exactly which tool to reach for in any situation.
The Big Picture - What is available
| Tool |
Category |
Best for |
| REST API |
Direct HTTP |
Foundation for everything; ad-hoc queries and testing |
| pynetbox |
Python SDK |
Scripts, bulk operations, scheduled reporting |
| Ansible |
Config Management |
Playbook-driven workflows, dynamic inventory |
| GraphQL API |
Query Language |
Complex nested queries with minimal round-trips |
The REST API — Your Universal Entry Point
What it is
Every piece of functionality in NetBox is exposed through a RESTful HTTP API. When you click 'Add Device' in the GUI, the web interface is ultimately making the same API calls that you can make directly from a terminal, a script, or any tool that can send HTTP requests. The REST API is the common denominator that everything else in this article builds on.
NetBox's REST API is exceptionally well-designed. Every object type such as devices, interfaces, IP addresses, prefixes, VLANs and cables has its own endpoint following a consistent URL pattern. It supports filtering, pagination, sorting, and partial updates out of the box. There's even an interactive browser at /api/ where you can explore and test endpoints live in your browser.
Why You'd Use It
The REST API is the right choice when you need something quick and language-agnostic. If you want to verify a device exists before running a script, pull a list of IPs for a specific prefix, or test a filter's return before integrating it into your code. Curl and the REST API get you there in seconds. It's also the integration point for tools and platforms that don't have a dedicated NetBox library: monitoring systems, ticketing tools, CMDBs, and custom internal applications all speak HTTP.
💡
Understanding the REST API directly makes you a better user of every other tool in this list. When something isn't working in Ansible or pynetbox, knowing how to test the underlying API call directly is invaluable for debugging.
Authentication
NetBox uses token-based authentication. Generate a token in the GUI under Admin → API Tokens, then pass it in an Authorization header on every request.
Verify your token works
curl -s \
-H "Authorization: Token <API-token>" \
http://<your-netbox>:8080/api/ | python3 -m json.tool
Expected Output
{
"circuits": "http://<your-netbox>:8080/api/circuits/",
"core": "http://<your-netbox>:8080/api/core/",
"dcim": "http://<your-netbox>:8080/api/dcim/",
"extras": "http://<your-netbox>:8080/api/extras/",
"ipam": "http://<your-netbox>:8080/api/ipam/",
"plugins": "http://<your-netbox>:8080/api/plugins/",
"status": "http://<your-netbox>:8080/api/status/",
"tenancy": "http://<your-netbox>:8080/api/tenancy/",
"users": "http://<your-netbox>:8080/api/users/",
"virtualization": "<your-netbox>:8080/api/virtualization/",
"vpn": "http://<your-netbox>:8080/api/vpn/",
"wireless": "http://<your-netbox>:8080/api/wireless/"
}
Use Case 1 — Query All Active Devices in a Site
curl -s \
-H "Authorization: Token <API-token>" \
http://<your-netbox>:8080/api/dcim/sites/ | python3 -m json.tool
Expected Output
{
"count": 3,
"next": null,
"previous": null,
"results": [
{
"id": 1,
"url": "http://<netbox>:8080/api/dcim/sites/1/",
"display_url":"http://"<netbox>:8080/dcim/sites/1/",
"display": "DC-Auckland",
"name": "DC-Auckland",
"slug": "dc-auckland",
"status": {
"value": "active",
"label": "Active"
},
"region": null,
"group": null,
"tenant": null,
"facility": "",
"time_zone": "Pacific/Auckland",
"description": "Primary data centre Auckland",
"physical_address": "Auckland, New Zealand",
"shipping_address": "",
"latitude": null,
"longitude": null,
"owner": null,
"comments": "",
"asns": [
{
"id": 1,
"url": "http://<netbox>:8080/api/ipam/asns/1/",
"display": "AS65000",
"asn": 65000,
"description": "DC-Auckland ASN"
}
],
"tags": [],
"custom_fields": {},
"created": "2026-05-24T23:14:48.341970Z",
"last_updated": "2026-05-24T23:14:48.341987Z",
"circuit_count": 0,
"device_count": 1,
"prefix_count": 0,
"rack_count": 1,
"virtualmachine_count": 0,
"vlan_count": 3
},
Use Case 2 — Create an IP Address Record
curl -s -X POST \
-H "Authorization: Token <API-token>" \
-H "Content-Type: application/json" \
-d '{
"address": "192.168.10.50/24",
"status": "active",
"description": "Web server uplink - Rack A3"
}' \
http://<your-netbox>:8080/api/ipam/ip-addresses/
Expected Output
{"id":9,"url":"http://<netbox>:8080/api/ipam/ip-addresses/9/","display_url":"http://<netbox> :8080/ipam/ip-addresses/9/","display":"192.168.10.50/24","family":{"value":4,"label":"IPv4"}," address":"192.168.10.50/24","vrf":null,"tenant":null,"status":{"value":"active","label":"Active"}," role":null,"assigned_object_type":null,"assigned_object_id":null,"assigned_object":null,"nat_inside":null,"nat_outside":[],"dns_name":"","description":"Web server uplink - Rack A3","owner":null,"comments":"","tags":[],"custom_fields":{},"created":"2026-06-07T22:43:47.758249Z","last_updated":"2026
GUI Verification
Use Case 3 — Partial Update with PATCH
I'm using the IP address above to update its status from Active to Reserved.
export NB="http://<your-netbox>:8080"
export TOKEN="<API-token>"
curl -s -X PATCH \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-d '{"status": "reserved"}' \
$NB/api/ipam/ip-addresses/9/ | python3 -m json.tool
💡
In this example, we use variables to achieve a cleaner appearance.
Expected Output
{
"id": 9,
"url": "http://<netbox>:8080/api/ipam/ip-addresses/9/",
"display_url": "http://<netbox>:8080/ipam/ip-addresses/9/",
"display": "192.168.10.50/24",
"family": {
"value": 4,
"label": "IPv4"
},
"address": "192.168.10.50/24",
"vrf": null,
"tenant": null,
"status": {
"value": "reserved",
"label": "Reserved"
},
"role": null,
"assigned_object_type": null,
"assigned_object_id": null,
"assigned_object": null,
"nat_inside": null,
"nat_outside": [],
"dns_name": "",
"description": "Web server uplink - Rack A3",
"owner": null,
"comments": "",
"tags": [],
"custom_fields": {},
"created": "2026-06-07T22:43:47.758249Z",
"last_updated": "2026-06-07T23:00:09.572431Z"
}
Key Concepts
Pagination: Results come back in pages. Use ?limit=100&offset;=100 to walk through large sets. The count field tells you the total.
Filtering: Append ?field=value to almost any endpoint. Filterable fields are documented in the API browser.
Depth: Add ?depth=1 to expand related objects from IDs into full nested objects.
API Browser: Visit https://your-netbox/api/ — it's fully interactive and documents every endpoint with live try-it-out functionality.
pynetbox — The Python SDK
What It Is
pynetbox is the official Python client library for NetBox. Rather than constructing raw HTTP requests and parsing JSON by hand, pynetbox gives you Python objects that feel natural to work with. nb.dcim.devices.filter(site="sydney-dc1") is far more readable than a curl command and it handles pagination, authentication headers, and error responses automatically.
Why You'd Use It
The true strength of pynetbox shines in bulk operations and scripting. Need to import 500 IP addresses from a spreadsheet? A 25-line Python script can manage that. Looking for a nightly inventory report? Pynetbox seamlessly integrates with csv, pandas, and other Python tools. It also effectively manages idempotency, allowing you to verify if a record exists before creating it, update records in place, and develop scripts that can be safely executed multiple times without causing duplicates. This is crucial in real-world environments where scripts are rerun and initial attempts may not always succeed.
Install
pip install pynetbox
Connect to Netbox
import pynetbox
import requests
# Setup
nb = pynetbox.api(
"http://<your-netbox>:8080",
token="<API-token>"
)
# Disable SSL verification (not needed for HTTP but good habit for lab)
session = requests.Session()
session.verify = False
nb.http_session = session
# Now make a call to verify the connection works
status = nb.status()
print(status)
Expected Output
{'django-version': '6.0.5', 'hostname': '4ba0dd1e9137', 'installed_apps': {'django_filters': '25.2', 'django_prometheus': '2.4.0', 'django_rq': '4.1.0', 'django_tables2': '2.8.0', 'drf_spectacular': '0.29.0', 'drf_spectacular_sidecar': '2026.5.1', 'mptt': '0.18.0', 'rest_framework': '3.17.1', 'social_django': '5.9.0', 'taggit': '6.1.0', 'timezone_field': '7.2.1'}, 'netbox-version': '4.6.1', 'netbox-full-version': '4.6.1-Docker-5.0.1', 'plugins': {}, 'python-version': '3.14.4', 'rq-workers-running': 1}
Use Case 1 — Generate a Full Device Inventory Report
One of the most common tasks in any network team: pulling a current device list into a spreadsheet for audits, compliance reports, or sharing with stakeholders who don't have NetBox access. pynetbox handles pagination automatically and simply y iterate through the data.
#Export all active devices to a dated CSV
import pynetbox
import csv
from datetime import datetime
nb = pynetbox.api("http://<netbox>:8080", token="<API-token>")
# Pull all active devices — pynetbox handles pagination automatically
devices = nb.dcim.devices.filter(status="active")
filename = f"netbox_inventory_{datetime.today().strftime('%Y-%m-%d')}.csv"
with open(filename, "w", newline="") as f:
writer = csv.writer(f)
writer.writerow(["Name", "Site", "Rack", "Role", "Model", "Platform", "Primary IP", "Status"])
for device in devices:
writer.writerow([
device.name,
str(device.site) if device.site else "",
str(device.rack) if device.rack else "",
str(device.device_role),
str(device.device_type),
str(device.platform) if device.platform else "",
str(device.primary_ip) if device.primary_ip else "No IP",
device.status.value,
])
print(f"Inventory exported to {filename}")
Expected Output
# The output after successful execution
Inventory exported to netbox_inventory_2026-06-08.csv
# The information in the csv
cat netbox_inventory_2026-06-08.csv
Name,Site,Rack,Role,Model,Platform,Primary IP,Status
core-rtr-01,DC-Auckland,AKL-RACK-01,Core Router,cisco_xrv9000,Cisco IOS-XR,10.10.10.3/24,active
core-rtr-02,DC-Sydney,SYD-RACK-01,Core Router,vMX,Juniper Junos,10.10.10.4/24,active
pe-rtr-01,DC-Queenstown,Queen-RACK-01,PE Router,7750 SR-1,Nokia SROS,10.10.10.1/24,active
pe-rtr-02,DC-Queenstown,Queen-RACK-01,PE Router,7750 SR-1,Nokia SROS,10.10.10.2/32,active
Use Case 2 — Auto-Assign the Next Available IP from a Prefix
This is where pynetbox really shines for IPAM automation. Instead of looking up the next free IP manually, your provisioning script calls NetBox directly and gets one allocated : no spreadsheet, no guesswork, no collisions.
import pynetbox
nb = pynetbox.api("http://<netbox>:8080", token="<API-token>")
def allocate_next_ip(prefix_cidr, description, dns_name=None):
"""Find and allocate the next available IP in a given prefix."""
prefix = nb.ipam.prefixes.get(prefix=prefix_cidr)
if not prefix:
raise ValueError(f"Prefix {prefix_cidr} not found in NetBox")
available = prefix.available_ips.list()
if not available:
raise RuntimeError(f"No available IPs remaining in {prefix_cidr}")
new_ip = nb.ipam.ip_addresses.create(
address=available[0]["address"],
status="active",
description=description,
dns_name=dns_name or "",
)
print(f"[+] Allocated {new_ip.address} — {description}")
return new_ip
# Example usage
ip = allocate_next_ip(
prefix_cidr="10.10.10.0/24",
description="New app server - provisioned by automation",
dns_name="app-server-04.internal"
)
Expected Output
[+] Allocated 10.10.10.5/24 — New app server - provisioned by automation
💡
Note : pynetbox excels when migrating from a spreadsheet-based IPAM, it saves days of manual work.
Ansible — Playbook-Driven Network Automation
What It Is
Ansible is the industry-standard open-source automation framework for configuration management, application deployment, and task orchestration. It uses human-readable YAML 'playbooks' to specify desired actions and communicates with devices and APIs over SSH or HTTP, eliminating the need for an agent on managed hosts. The netbox.netbox Ansible collection offers specialized modules for managing NetBox objects and includes a dynamic inventory plugin that converts your live NetBox data into an Ansible inventory.
Why You'd Use It
Ansible and NetBox complement each other by addressing different aspects of infrastructure management. NetBox maintains the intended state of your infrastructure, while Ansible ensures that the actual devices align with this state. The dynamic inventory plugin is especially effective, as it allows Ansible to query NetBox in real-time, creating a host list from live data instead of relying on a static list. This ensures your inventory is always up-to-date, automatically organized by site, device role, platform, and other attributes. When you add a device to NetBox, Ansible automatically recognizes it the next time a playbook is executed, eliminating the need for manual inventory updates.
Install Ansible and the NetBox collection
pip install ansible pynetbox
ansible-galaxy collection install netbox.netbox
Use Case 1 — Dynamic Inventory Setup
plugin: netbox.netbox.nb_inventory
api_endpoint: http://<netbox>:8080
token: nbt_vgoJvumHKFno.StatmKZYfkeHm6lQqmUWmAR88vEQMNE4urjTA7a4
validate_certs: false
# Group devices by these attributes
group_by:
- device_roles
- sites
- platforms
- tags
# Only pull active devices
query_filters:
- status: "active"
# Map NetBox primary IP to Ansible's connection address
compose:
ansible_host: primary_ip.address | ansible.netcommon.ipaddr('address')
Expected Output
ansible-inventory -i netbox_inventory.yml --graph
@all:
|--@ungrouped:
|--@sites_dc-auckland:
| |--core-rtr-01
|--@sites_dc-queenstown:
| |--pe-rtr-01
| |--pe-rtr-02
|--@sites_dc-sydney:
| |--core-rtr-02
|--@device_roles_core-router:
| |--core-rtr-01
| |--core-rtr-02
|--@platforms_cisco-ios-xr:
| |--core-rtr-01
|--@tags_bgp-peer:
| |--core-rtr-01
| |--core-rtr-02
| |--pe-rtr-01
| |--pe-rtr-02
|--@tags_lab:
| |--core-rtr-01
| |--core-rtr-02
| |--pe-rtr-01
| |--pe-rtr-02
|--@tags_mpls-enabled:
| |--core-rtr-01
| |--core-rtr-02
| |--pe-rtr-01
| |--pe-rtr-02
|--@platforms_juniper-junos:
| |--core-rtr-02
|--@device_roles_pe-router:
| |--pe-rtr-01
| |--pe-rtr-02
|--@platforms_nokia-sros:
| |--pe-rtr-01
| |--pe-rtr-02
ansible-inventory -i netbox_inventory.yml --list
{
"_meta": {
"hostvars": {
"core-rtr-01": {
"ansible_host": "10.10.10.3",
"custom_fields": {
"automation_enabled": true,
"bgp_asn": 65000,
"config_backup_path": "/backups/auckland/core-rtr-01/",
"mgmt_vrf": "VRF-MGMT",
"ntp_last_deployed": null,
"support_contract": "PLATINUM",
"warranty_expiry": "2028-06-30"
},
"device_roles": [
"core-router"
],
"device_types": [
"cisco_xrv9000"
],
"is_virtual": false,
"local_context_data": [
null
],
"locations": [],
"manufacturers": [
"cisco"
],
"platforms": [
"cisco-ios-xr"
],
"primary_ip4": "10.10.10.3",
"racks": [
"AKL-RACK-01"
],
"regions": [],
"serial": "",
"services": [],
"site_groups": [],
"sites": [
"dc-auckland"
],
"status": {
"label": "Active",
"value": "active"
},
"tags": [
"bgp-peer",
"lab",
"mpls-enabled"
]
},
"core-rtr-02": {
"ansible_host": "10.10.10.4",
"custom_fields": {
"automation_enabled": true,
"bgp_asn": 65001,
"config_backup_path": "/backups/auckland/core-rtr-02/",
"mgmt_vrf": "VRF-MGMT",
"ntp_last_deployed": null,
"support_contract": null,
"warranty_expiry": null
},
"device_roles": [
"core-router"
],
"device_types": [
"vmx"
],
"is_virtual": false,
"local_context_data": [
null
],
"locations": [],
"manufacturers": [
"juniper"
],
"platforms": [
"juniper-junos"
],
"primary_ip4": "10.10.10.4",
"racks": [
"SYD-RACK-01"
],
"regions": [],
"serial": "",
"services": [],
"site_groups": [],
"sites": [
"dc-sydney"
],
"status": {
"label": "Active",
"value": "active"
},
"tags": [
"bgp-peer",
"lab",
"mpls-enabled"
]
},
................... Truncated
GraphQL — Ask for Exactly What You Need
What It Is
In addition to the REST API, NetBox offers a GraphQL endpoint at /graphql/. GraphQL is a query language for APIs that allows you to specify the exact data structure you need in a single request. Instead of accessing multiple REST endpoints and combining results in code, you can write a single query that navigates related objects and retrieves only the fields you require
Why You'd Use It
The core benefit of GraphQL over REST is efficiency in complex queries. Consider a common task: you need a list of all active devices with each device's interfaces and the IPs assigned to those interfaces.Using REST, you would need at least three separate requests: one for devices, followed by individual requests for each device's interfaces, and then additional requests for the IPs assigned to those interfaces.With GraphQL, it's a single query. This matters most when building dashboards, audit reports, or integration pipelines that need rich nested data.
GraphQL minimizes the need for transformation code since the response matches the requested structure. The interactive playground at /graphql/ provides live schema documentation, allowing you to explore and test queries effortlessly without coding.
Use Case 1 — Device with Interfaces and IPs in One Request
This single query would require at least three separate REST API calls to replicate. The equivalent in REST would require:
GET /api/dcim/devices/ — get devices
GET /api/dcim/interfaces/?device=x — per device, get interfaces
GET /api/ipam/ip-addresses/?interface=x — per interface, get IPs
import requests
import json
NETBOX_URL = "http://<netbox>:8080/graphql/"
TOKEN = "nbt_vgoJvumHKFno.StatmKZYfkeHm6lQqmUWmAR88vEQMNE4urjTA7a4"
HEADERS = {
"Authorization": f"Token {TOKEN}",
"Content-Type": "application/json",
}
# GraphQL query to filter for dc-sydney only
query = """
{
device_list(filters: {site: {slug: {i_exact: "dc-sydney"}}}) {
name
status
device_type {
model
}
role {
name
}
rack {
name
}
primary_ip4 {
address
dns_name
}
interfaces {
name
enabled
ip_addresses {
address
status
}
}
}
}
"""
response = requests.post(
NETBOX_URL,
headers=HEADERS,
json={"query": query},
verify=False
)
data = response.json()
# Check for GraphQL errors
# GraphQL always returns HTTP 200 even when something goes wrong and errors come back inside the JSON body itself, not as HTTP status codes.
if "errors" in data:
print("[!] GraphQL errors:")
for error in data["errors"]:
print(f" {error['message']}")
exit(1)
devices = data["data"]["device_list"]
if not devices:
print("[!] No devices found")
exit(0)
print(f"Found {len(devices)} device(s)\n")
print("=" * 65)
for device in devices:
print(f"Device : {device['name']}")
print(f"Status : {device['status']}")
print(f"Model : {device['device_type']['model']}")
print(f"Role : {device['role']['name']}")
print(f"Rack : {device['rack']['name'] if device['rack'] else 'N/A'}")
if device["primary_ip4"]:
print(f"Primary IP: {device['primary_ip4']['address']}")
dns = device["primary_ip4"].get("dns_name", "")
if dns:
print(f"DNS Name : {dns}")
else:
print(f"Primary IP: None")
interfaces = device.get("interfaces", [])
if interfaces:
print(f"Interfaces: {len(interfaces)} found")
for intf in interfaces:
enabled = "up" if intf["enabled"] else "down"
ips = intf.get("ip_addresses", [])
if ips:
for ip in ips:
print(f" └─ {intf['name']:<20} [{enabled}] {ip['address']} ({ip['status']})")
else:
print(f" └─ {intf['name']:<20} [{enabled}] no IP")
else:
print(f"Interfaces: None")
print("=" * 65)
Expected Output
Found 1 device(s)
===============================================================
Device : core-rtr-02
Status : active
Model : vMX
Role : Core Router
Rack : SYD-RACK-01
Primary IP: 10.10.10.4/24
Interfaces: 4 found
└─ ge-0/0/0 [up] no IP
└─ ge-0/0/1 [up] no IP
└─ fxp0 [up] 192.168.20.1/24 (active)
└─ lo0 [up] 10.10.10.4/24 (active)
===============================================================
Here's a practical decision guide. In real environments, these tools often complement each other and the key is determining which one takes the lead for a specific task.
What are you trying to do ?
REST API (curl) - One-off query, quick test, or debugging?
pynetbox - Python scripting, bulk import, or scheduled reporting?
Ansible - Managing device configs alongside NetBox records?
GraphQL API - Complex queries joining devices, IPs, interfaces in one call
Conclusion
NetBox's value depends on the accuracy of its data. Achieving data accuracy on a large scale requires automation.
This article highlights an important point: NetBox is not merely a GUI with an API attached. It is an API that includes a GUI. Every click you made in my previous post has a programmatic equivalent. When your tools talk directly to NetBox , reading from it, writing to it, and reacting to changes in it. The data stays current without depending on human intervention to keep it updated.
