pynetbox Documentation

In pynetbox, Endpoint objects are automatically created when you access an attribute on an App instance. These objects provide the interface for performing CRUD (Create, Read, Update, Delete) operations against NetBox API endpoints.

Common methods available on an Endpoint include:

• .all(): Retrieve all records at the endpoint.
• .get(id): Retrieve a single record by its ID.
• .filter(**kwargs): Retrieve records matching specific criteria.
• .create(**kwargs): Create a new record.
• .update(id, **kwargs): Update an existing record.
• .delete(id): Delete an existing record.

import pynetbox

b = pynetbox.api('http://localhost:8000', token='your-token')

# Accessing an attribute on an App returns an Endpoint
devices = b.dcim.devices

# Perform CRUD operations
all_devices = devices.all()
device = devices.get(1)
filtered = devices.filter(site='headquarters')
new_device = devices.create(name='test', site=1, device_type=1, role=1)

For NetBox 4.6+, you can use cursor-based pagination via the pagination="cursor" argument. This is significantly more performant for very large result sets as it avoids the cost of scanning offsets.

Behavior and Trade-offs:

• Automatic Fallback: If the NetBox server is older than 4.6, pynetbox transparently falls back to offset-based pagination.
• No Total Count: NetBox omits the count in cursor mode. Calling len(record_set) will trigger a separate, additional count request.
• Fixed Ordering: Results are always ordered by id. You cannot combine cursor pagination with an explicit ordering filter.
• Sequential Only: Cursor pagination is inherently sequential and cannot be combined with threading. If pagination="cursor" is set, queries will be sequential even if threading=True is passed.

import pynetbox

nb = pynetbox.api(
    'http://localhost:8000',
    token='your-token',
    pagination="cursor",
)

# .all() and .filter() now page using the server's `start` cursor
devices = nb.dcim.devices.all()

The pynetbox object structure mirrors the NetBox application structure. Each NetBox app is an attribute of the API object. Dashes in NetBox endpoint names are converted to underscores in Python.

Core Namespaces:

• nb.circuits: Circuit management
• nb.core: Core objects (data sources, jobs, object changes)
• nb.dcim: Data Center Infrastructure Management
• nb.extras: Tags, custom fields, webhooks, etc.
• nb.ipam: IP Address Management
• nb.tenancy: Tenants and contacts
• nb.users: Users and permissions
• nb.virtualization: Virtual machines and clusters
• nb.vpn: VPN tunnels and terminations
• nb.wireless: Wireless LANs and links

Plugin Endpoints: Endpoints provided by NetBox plugins are accessed via the plugins namespace. For example, a plugin named my-plugin with an endpoint /api/plugins/my-plugin/objects/ is accessed as nb.plugins.my_plugin.objects.

pynetbox uses a hierarchical, layered architecture where each layer wraps the one below it to provide a structured way to navigate the NetBox API:

1. Api: The main entry point. It manages the HTTP session, authentication token, and global configuration.
2. App: Represents a NetBox application (e.g., dcim, ipam). Accessing an attribute on an Api instance returns an App.
3. Endpoint: Represents an individual NetBox API endpoint. Accessing an attribute on an App returns an Endpoint.

This allows you to navigate the API using standard Python attribute access (e.g., nb.dcim.devices).

import pynetbox

# Create an API connection (Api)
nb = pynetbox.api('http://localhost:8000', token='your-token')

# Access an app (App)
nb.dcim

# Access an endpoint (Endpoint)
nb.dcim.devices

# Call an endpoint method (returns Record / RecordSet)
devices = nb.dcim.devices.all()

You can replace the default requests.Session by assigning a new session object to nb.http_session. This allows you to customize headers, SSL verification, and timeouts.

Common Tasks:

• Custom Headers: Assign a requests.Session with pre-configured headers.
• Disable SSL: Set session.verify = False on your custom session.
• Timeouts: To set a default timeout for all requests, you must mount a custom requests.adapters.HTTPAdapter to the session.

import pynetbox
import requests
from requests.adapters import HTTPAdapter

# Example: Custom Headers
session = requests.Session()
session.headers = {'mycustomheader': 'test'}
nb = pynetbox.api('http://localhost:8000', token='your-token')
nb.http_session = session

# Example: Custom Timeouts via Adapter
class TimeoutHTTPAdapter(HTTPAdapter):
    def __init__(self, *args, **kwargs):
        self.timeout = kwargs.pop('timeout', 5)
        super().__init__(*args, **kwargs)

    def send(self, request, **kwargs):
        kwargs['timeout'] = self.timeout
        return super().send(request, **kwargs)

adapter = TimeoutHTTPAdapter(timeout=10)
session = requests.Session()
session.mount('http://', adapter)
session.mount('https://', adapter)

nb = pynetbox.api('http://localhost:8000', token='your-token')
nb.http_session = session