API Core Classes¶

This page documents the core classes that form pyNetBox's API structure.

Overview¶

PyNetBox uses a layered architecture to interact with NetBox:

Api - The main entry point that creates connections to NetBox
App - Represents NetBox applications (dcim, ipam, circuits, etc.)
Endpoint - Provides CRUD operations for specific API endpoints

import pynetbox

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

# Access an app (App class)
nb.dcim  # Returns an App instance

# Access an endpoint (Endpoint class)
nb.dcim.devices  # Returns an Endpoint instance

# Use endpoint methods
devices = nb.dcim.devices.all()

Api Class¶

The Api class is the main entry point for interacting with NetBox. It manages the HTTP session, authentication, and provides access to NetBox applications.

`pynetbox.core.api.Api` ¶

The API object is the point of entry to pynetbox.

After instantiating the Api() with the appropriate named arguments you can specify which app and endpoint you wish to interact with.

Valid attributes currently are:

circuits
core (NetBox 3.5+)
dcim
extras
ipam
tenancy
users
virtualization
vpn (NetBox 3.7+)
wireless

Calling any of these attributes will return an App object which exposes endpoints as attributes.

Additional Attributes¶

http_session(requests.Session): Override the default session with your own. This is used to control a number of HTTP behaviors such as SSL verification, custom headers, retires, and timeouts. See custom sessions for more info.

Parameters¶

url (str): The base URL to the instance of NetBox you wish to connect to.
token (str): Your NetBox token.
threading (bool, optional): Set to True to use threading in .all() and .filter() requests.

Raises¶

AttributeError: If app doesn't exist.

Examples¶

import pynetbox
nb = pynetbox.api(
    'http://localhost:8000',
    token='d6f4e314a5b5fefd164995169f28ae32d987704f'
)
list(nb.dcim.devices.all())
# [test1-leaf1, test1-leaf2, test1-leaf3]

Source code in pynetbox/core/api.py

class Api:
    """The API object is the point of entry to pynetbox.

    After instantiating the Api() with the appropriate named arguments
    you can specify which app and endpoint you wish to interact with.

    Valid attributes currently are:

    * circuits
    * core (NetBox 3.5+)
    * dcim
    * extras
    * ipam
    * tenancy
    * users
    * virtualization
    * vpn (NetBox 3.7+)
    * wireless

    Calling any of these attributes will return an `App` object which exposes endpoints as attributes.

    ## Additional Attributes

    * **http_session(requests.Session)**: Override the default session with your own. This is used to control
      a number of HTTP behaviors such as SSL verification, custom headers,
      retires, and timeouts.
      See [custom sessions](advanced.md#custom-sessions) for more info.

    ## Parameters

    * **url** (str): The base URL to the instance of NetBox you wish to connect to.
    * **token** (str): Your NetBox token.
    * **threading** (bool, optional): Set to True to use threading in `.all()` and `.filter()` requests.

    ## Raises

    * **AttributeError**: If app doesn't exist.

    ## Examples

    ```python
    import pynetbox
    nb = pynetbox.api(
        'http://localhost:8000',
        token='d6f4e314a5b5fefd164995169f28ae32d987704f'
    )
    list(nb.dcim.devices.all())
    # [test1-leaf1, test1-leaf2, test1-leaf3]
    ```
    """

    def __init__(
        self,
        url,
        token=None,
        threading=False,
        strict_filters=False,
    ):
        """Initialize the API client.

        Args:
            url (str): The base URL to the instance of NetBox you wish to connect to.
            token (str, optional): Your NetBox API token. If not provided, authentication will be required for each request.
            threading (bool, optional): Set to True to use threading in `.all()` and `.filter()` requests, defaults to False.
            strict_filters (bool, optional): Set to True to check GET call filters against OpenAPI specifications (intentionally not done in NetBox API), defaults to False.
        """
        base_url = "{}/api".format(url if url[-1] != "/" else url[:-1])
        self.token = token
        self.base_url = base_url
        self.http_session = requests.Session()
        self.threading = threading
        self.strict_filters = strict_filters

        # Initialize NetBox apps
        self.circuits = App(self, "circuits")
        self.core = App(self, "core")
        self.dcim = App(self, "dcim")
        self.extras = App(self, "extras")
        self.ipam = App(self, "ipam")
        self.tenancy = App(self, "tenancy")
        self.users = App(self, "users")
        self.virtualization = App(self, "virtualization")
        self.vpn = App(self, "vpn")
        self.wireless = App(self, "wireless")
        self.plugins = PluginsApp(self)

    @property
    def version(self):
        """Gets the API version of NetBox.

        Can be used to check the NetBox API version if there are
        version-dependent features or syntaxes in the API.

        ## Returns
        Version number as a string.

        ## Example

        ```python
        import pynetbox
        nb = pynetbox.api(
            'http://localhost:8000',
            token='d6f4e314a5b5fefd164995169f28ae32d987704f'
        )
        nb.version
        # '3.1'
        ```
        """
        version = Request(
            base=self.base_url,
            token=self.token,
            http_session=self.http_session,
        ).get_version()
        return version

    def openapi(self):
        """Returns the OpenAPI spec.

        Quick helper function to pull down the entire OpenAPI spec.
        It is stored in memory to avoid repeated calls on NetBox API.

        ## Returns
        dict: The OpenAPI specification as a dictionary.

        ## Example

        ```python
        import pynetbox
        nb = pynetbox.api(
            'http://localhost:8000',
            token='d6f4e314a5b5fefd164995169f28ae32d987704f'
        )
        nb.openapi()
        # {...}
        ```
        """
        if not (openapi := getattr(self, "_openapi", None)):
            openapi = self._openapi = Request(
                base=self.base_url,
                http_session=self.http_session,
            ).get_openapi()

        return openapi

    def status(self):
        """Gets the status information from NetBox.

        ## Returns
        Dictionary containing NetBox status information.

        ## Raises
        `RequestError`: If the request is not successful.

        ## Example

        ```python
        from pprint import pprint
        pprint(nb.status())
        {
            'django-version': '3.1.3',
            'installed-apps': {
                'cacheops': '5.0.1',
                'debug_toolbar': '3.1.1',
                'django_filters': '2.4.0',
                'django_prometheus': '2.1.0',
                'django_rq': '2.4.0',
                'django_tables2': '2.3.3',
                'drf_yasg': '1.20.0',
                'mptt': '0.11.0',
                'rest_framework': '3.12.2',
                'taggit': '1.3.0',
                'timezone_field': '4.0'
            },
            'netbox-version': '2.10.2',
            'plugins': {},
            'python-version': '3.7.3',
            'rq-workers-running': 1
        }
        ```
        """
        status = Request(
            base=self.base_url,
            token=self.token,
            http_session=self.http_session,
        ).get_status()
        return status

    def create_token(self, username, password):
        """Creates an API token using a valid NetBox username and password.
        Saves the created token automatically in the API object.

        ## Parameters
        * **username** (str): NetBox username
        * **password** (str): NetBox password

        ## Returns
        `Record`: The token as a Record object.

        ## Raises
        `RequestError`: If the request is not successful.

        ## Example

        ```python
        import pynetbox
        nb = pynetbox.api("https://netbox-server")
        token = nb.create_token("admin", "netboxpassword")
        nb.token
        # '96d02e13e3f1fdcd8b4c089094c0191dcb045bef'

        from pprint import pprint
        pprint(dict(token))
        {
            'created': '2021-11-27T11:26:49.360185+02:00',
            'description': '',
            'display': '045bef (admin)',
            'expires': None,
            'id': 2,
            'key': '96d02e13e3f1fdcd8b4c089094c0191dcb045bef',
            'url': 'https://netbox-server/api/users/tokens/2/',
            'user': {
                'display': 'admin',
                'id': 1,
                'url': 'https://netbox-server/api/users/users/1/',
                'username': 'admin'
            },
            'write_enabled': True
        }
        ```
        """
        resp = Request(
            base="{}/users/tokens/provision/".format(self.base_url),
            http_session=self.http_session,
        ).post(data={"username": username, "password": password})
        # Save the newly created API token, otherwise populating the Record
        # object details will fail
        self.token = resp["key"]
        return Record(resp, self, None)

    @contextlib.contextmanager
    def activate_branch(self, branch):
        """Context manager to activate the branch by setting the schema ID in the headers.

        **Note**: The NetBox branching plugin must be installed and enabled in your NetBox instance for this functionality to work.

        ## Parameters
        * **branch** (Record): The NetBox branch to activate

        ## Raises
        `ValueError`: If the branch is not a valid NetBox branch.

        ## Example

        ```python
        import pynetbox
        nb = pynetbox.api("https://netbox-server")
        branch = nb.plugins.branching.branches.create(name="testbranch")
        with nb.activate_branch(branch):
            sites = nb.dcim.sites.all()
            # All operations within this block will use the branch's schema
        ```
        """
        if not isinstance(branch, Record) or "schema_id" not in dict(branch):
            raise ValueError(
                f"The specified branch is not a valid NetBox branch: {branch}."
            )

        self.http_session.headers["X-NetBox-Branch"] = branch.schema_id

        try:
            yield
        finally:
            self.http_session.headers.pop("X-NetBox-Branch", None)

`version` `property` `readonly` ¶

Gets the API version of NetBox.

Can be used to check the NetBox API version if there are version-dependent features or syntaxes in the API.

Returns¶

Version number as a string.

Example¶

import pynetbox
nb = pynetbox.api(
    'http://localhost:8000',
    token='d6f4e314a5b5fefd164995169f28ae32d987704f'
)
nb.version
# '3.1'

`init(self, url, token=None, threading=False, strict_filters=False)` `special` ¶

Initialize the API client.

Parameters:

Name	Type	Description	Default
`url`	`str`	The base URL to the instance of NetBox you wish to connect to.	required
`token`	`str`	Your NetBox API token. If not provided, authentication will be required for each request.	`None`
`threading`	`bool`	Set to True to use threading in `.all()` and `.filter()` requests, defaults to False.	`False`
`strict_filters`	`bool`	Set to True to check GET call filters against OpenAPI specifications (intentionally not done in NetBox API), defaults to False.	`False`

Source code in pynetbox/core/api.py

def __init__(
    self,
    url,
    token=None,
    threading=False,
    strict_filters=False,
):
    """Initialize the API client.

    Args:
        url (str): The base URL to the instance of NetBox you wish to connect to.
        token (str, optional): Your NetBox API token. If not provided, authentication will be required for each request.
        threading (bool, optional): Set to True to use threading in `.all()` and `.filter()` requests, defaults to False.
        strict_filters (bool, optional): Set to True to check GET call filters against OpenAPI specifications (intentionally not done in NetBox API), defaults to False.
    """
    base_url = "{}/api".format(url if url[-1] != "/" else url[:-1])
    self.token = token
    self.base_url = base_url
    self.http_session = requests.Session()
    self.threading = threading
    self.strict_filters = strict_filters

    # Initialize NetBox apps
    self.circuits = App(self, "circuits")
    self.core = App(self, "core")
    self.dcim = App(self, "dcim")
    self.extras = App(self, "extras")
    self.ipam = App(self, "ipam")
    self.tenancy = App(self, "tenancy")
    self.users = App(self, "users")
    self.virtualization = App(self, "virtualization")
    self.vpn = App(self, "vpn")
    self.wireless = App(self, "wireless")
    self.plugins = PluginsApp(self)

`activate_branch(self, branch)` ¶

Context manager to activate the branch by setting the schema ID in the headers.

Note: The NetBox branching plugin must be installed and enabled in your NetBox instance for this functionality to work.

Parameters¶

branch (Record): The NetBox branch to activate

Raises¶

ValueError: If the branch is not a valid NetBox branch.

Example¶

import pynetbox
nb = pynetbox.api("https://netbox-server")
branch = nb.plugins.branching.branches.create(name="testbranch")
with nb.activate_branch(branch):
    sites = nb.dcim.sites.all()
    # All operations within this block will use the branch's schema

Source code in pynetbox/core/api.py

@contextlib.contextmanager
def activate_branch(self, branch):
    """Context manager to activate the branch by setting the schema ID in the headers.

    **Note**: The NetBox branching plugin must be installed and enabled in your NetBox instance for this functionality to work.

    ## Parameters
    * **branch** (Record): The NetBox branch to activate

    ## Raises
    `ValueError`: If the branch is not a valid NetBox branch.

    ## Example

    ```python
    import pynetbox
    nb = pynetbox.api("https://netbox-server")
    branch = nb.plugins.branching.branches.create(name="testbranch")
    with nb.activate_branch(branch):
        sites = nb.dcim.sites.all()
        # All operations within this block will use the branch's schema
    ```
    """
    if not isinstance(branch, Record) or "schema_id" not in dict(branch):
        raise ValueError(
            f"The specified branch is not a valid NetBox branch: {branch}."
        )

    self.http_session.headers["X-NetBox-Branch"] = branch.schema_id

    try:
        yield
    finally:
        self.http_session.headers.pop("X-NetBox-Branch", None)

`create_token(self, username, password)` ¶

Creates an API token using a valid NetBox username and password. Saves the created token automatically in the API object.

Parameters¶

username (str): NetBox username
password (str): NetBox password

Returns¶

Record: The token as a Record object.

Raises¶

RequestError: If the request is not successful.

Example¶

import pynetbox
nb = pynetbox.api("https://netbox-server")
token = nb.create_token("admin", "netboxpassword")
nb.token
# '96d02e13e3f1fdcd8b4c089094c0191dcb045bef'

from pprint import pprint
pprint(dict(token))
{
    'created': '2021-11-27T11:26:49.360185+02:00',
    'description': '',
    'display': '045bef (admin)',
    'expires': None,
    'id': 2,
    'key': '96d02e13e3f1fdcd8b4c089094c0191dcb045bef',
    'url': 'https://netbox-server/api/users/tokens/2/',
    'user': {
        'display': 'admin',
        'id': 1,
        'url': 'https://netbox-server/api/users/users/1/',
        'username': 'admin'
    },
    'write_enabled': True
}

Source code in pynetbox/core/api.py

def create_token(self, username, password):
    """Creates an API token using a valid NetBox username and password.
    Saves the created token automatically in the API object.

    ## Parameters
    * **username** (str): NetBox username
    * **password** (str): NetBox password

    ## Returns
    `Record`: The token as a Record object.

    ## Raises
    `RequestError`: If the request is not successful.

    ## Example

    ```python
    import pynetbox
    nb = pynetbox.api("https://netbox-server")
    token = nb.create_token("admin", "netboxpassword")
    nb.token
    # '96d02e13e3f1fdcd8b4c089094c0191dcb045bef'

    from pprint import pprint
    pprint(dict(token))
    {
        'created': '2021-11-27T11:26:49.360185+02:00',
        'description': '',
        'display': '045bef (admin)',
        'expires': None,
        'id': 2,
        'key': '96d02e13e3f1fdcd8b4c089094c0191dcb045bef',
        'url': 'https://netbox-server/api/users/tokens/2/',
        'user': {
            'display': 'admin',
            'id': 1,
            'url': 'https://netbox-server/api/users/users/1/',
            'username': 'admin'
        },
        'write_enabled': True
    }
    ```
    """
    resp = Request(
        base="{}/users/tokens/provision/".format(self.base_url),
        http_session=self.http_session,
    ).post(data={"username": username, "password": password})
    # Save the newly created API token, otherwise populating the Record
    # object details will fail
    self.token = resp["key"]
    return Record(resp, self, None)

`openapi(self)` ¶

Returns the OpenAPI spec.

Quick helper function to pull down the entire OpenAPI spec. It is stored in memory to avoid repeated calls on NetBox API.

Returns¶

dict: The OpenAPI specification as a dictionary.

Example¶

import pynetbox
nb = pynetbox.api(
    'http://localhost:8000',
    token='d6f4e314a5b5fefd164995169f28ae32d987704f'
)
nb.openapi()
# {...}

Source code in pynetbox/core/api.py

def openapi(self):
    """Returns the OpenAPI spec.

    Quick helper function to pull down the entire OpenAPI spec.
    It is stored in memory to avoid repeated calls on NetBox API.

    ## Returns
    dict: The OpenAPI specification as a dictionary.

    ## Example

    ```python
    import pynetbox
    nb = pynetbox.api(
        'http://localhost:8000',
        token='d6f4e314a5b5fefd164995169f28ae32d987704f'
    )
    nb.openapi()
    # {...}
    ```
    """
    if not (openapi := getattr(self, "_openapi", None)):
        openapi = self._openapi = Request(
            base=self.base_url,
            http_session=self.http_session,
        ).get_openapi()

    return openapi

`status(self)` ¶

Gets the status information from NetBox.

Returns¶

Dictionary containing NetBox status information.

Raises¶

RequestError: If the request is not successful.

Example¶

from pprint import pprint
pprint(nb.status())
{
    'django-version': '3.1.3',
    'installed-apps': {
        'cacheops': '5.0.1',
        'debug_toolbar': '3.1.1',
        'django_filters': '2.4.0',
        'django_prometheus': '2.1.0',
        'django_rq': '2.4.0',
        'django_tables2': '2.3.3',
        'drf_yasg': '1.20.0',
        'mptt': '0.11.0',
        'rest_framework': '3.12.2',
        'taggit': '1.3.0',
        'timezone_field': '4.0'
    },
    'netbox-version': '2.10.2',
    'plugins': {},
    'python-version': '3.7.3',
    'rq-workers-running': 1
}

Source code in pynetbox/core/api.py

def status(self):
    """Gets the status information from NetBox.

    ## Returns
    Dictionary containing NetBox status information.

    ## Raises
    `RequestError`: If the request is not successful.

    ## Example

    ```python
    from pprint import pprint
    pprint(nb.status())
    {
        'django-version': '3.1.3',
        'installed-apps': {
            'cacheops': '5.0.1',
            'debug_toolbar': '3.1.1',
            'django_filters': '2.4.0',
            'django_prometheus': '2.1.0',
            'django_rq': '2.4.0',
            'django_tables2': '2.3.3',
            'drf_yasg': '1.20.0',
            'mptt': '0.11.0',
            'rest_framework': '3.12.2',
            'taggit': '1.3.0',
            'timezone_field': '4.0'
        },
        'netbox-version': '2.10.2',
        'plugins': {},
        'python-version': '3.7.3',
        'rq-workers-running': 1
    }
    ```
    """
    status = Request(
        base=self.base_url,
        token=self.token,
        http_session=self.http_session,
    ).get_status()
    return status

App Class¶

The App class represents a NetBox application (such as dcim, ipam, circuits). When you access an attribute on the Api object, it returns an App instance. Accessing attributes on an App returns Endpoint objects.

`pynetbox.core.app.App` ¶

Represents apps in NetBox.

Calls to attributes are returned as Endpoint objects.

Returns¶

Endpoint matching requested attribute.

Raises¶

RequestError if requested endpoint doesn't exist.

Source code in pynetbox/core/app.py

class App:
    """Represents apps in NetBox.

    Calls to attributes are returned as Endpoint objects.

    ## Returns
    Endpoint matching requested attribute.

    ## Raises
    RequestError if requested endpoint doesn't exist.
    """

    def __init__(self, api, name):
        self.api = api
        self.name = name
        self._setmodel()

    models = {
        "circuits": circuits,
        "core": core,
        "dcim": dcim,
        "extras": extras,
        "ipam": ipam,
        "users": users,
        "virtualization": virtualization,
        "wireless": wireless,
    }

    def _setmodel(self):
        self.model = App.models[self.name] if self.name in App.models else None

    def __getstate__(self):
        return {"api": self.api, "name": self.name}

    def __setstate__(self, d):
        self.__dict__.update(d)
        self._setmodel()

    def __getattr__(self, name):
        return Endpoint(self.api, self, name, model=self.model)

    def config(self):
        """Returns config response from app.

        ## Returns
        Raw response from NetBox's config endpoint.

        ## Raises
        RequestError if called for an invalid endpoint.

        ## Examples

        ```python
        pprint.pprint(nb.users.config())
        {
            'tables': {
                'DeviceTable': {
                    'columns': [
                        'name',
                        'status',
                        'tenant',
                        'role',
                        'site',
                        'primary_ip',
                        'tags'
                    ]
                }
            }
        }
        ```
        """
        config = Request(
            base="{}/{}/config/".format(
                self.api.base_url,
                self.name,
            ),
            token=self.api.token,
            http_session=self.api.http_session,
        ).get()
        return config

`config(self)` ¶

Returns config response from app.

Returns¶

Raw response from NetBox's config endpoint.

Raises¶

RequestError if called for an invalid endpoint.

Examples¶

pprint.pprint(nb.users.config())
{
    'tables': {
        'DeviceTable': {
            'columns': [
                'name',
                'status',
                'tenant',
                'role',
                'site',
                'primary_ip',
                'tags'
            ]
        }
    }
}

Source code in pynetbox/core/app.py

def config(self):
    """Returns config response from app.

    ## Returns
    Raw response from NetBox's config endpoint.

    ## Raises
    RequestError if called for an invalid endpoint.

    ## Examples

    ```python
    pprint.pprint(nb.users.config())
    {
        'tables': {
            'DeviceTable': {
                'columns': [
                    'name',
                    'status',
                    'tenant',
                    'role',
                    'site',
                    'primary_ip',
                    'tags'
                ]
            }
        }
    }
    ```
    """
    config = Request(
        base="{}/{}/config/".format(
            self.api.base_url,
            self.name,
        ),
        token=self.api.token,
        http_session=self.api.http_session,
    ).get()
    return config

Relationship to Endpoints¶

When you access an attribute on an App object, it returns an Endpoint instance:

# nb.dcim is an App instance
# nb.dcim.devices is an Endpoint instance
devices_endpoint = nb.dcim.devices

# Endpoint provides CRUD methods
all_devices = devices_endpoint.all()
device = devices_endpoint.get(1)
new_device = devices_endpoint.create(name='test', site=1, device_type=1, device_role=1)

See the Endpoint documentation for details on available methods.

API Core Classes¶

Overview¶

Api Class¶

pynetbox.core.api.Api ¶

Additional Attributes¶

Parameters¶

Raises¶

Examples¶

version property readonly ¶

Returns¶

Example¶

__init__(self, url, token=None, threading=False, strict_filters=False) special ¶

activate_branch(self, branch) ¶

Parameters¶

Raises¶

Example¶

create_token(self, username, password) ¶

Parameters¶

Returns¶

Raises¶

Example¶

openapi(self) ¶

Returns¶

Example¶

status(self) ¶

Returns¶

Raises¶

Example¶

App Class¶

pynetbox.core.app.App ¶

Returns¶

Raises¶

config(self) ¶

Returns¶

Raises¶

Examples¶

Relationship to Endpoints¶

`pynetbox.core.api.Api` ¶

`version` `property` `readonly` ¶

`init(self, url, token=None, threading=False, strict_filters=False)` `special` ¶

`activate_branch(self, branch)` ¶

`create_token(self, username, password)` ¶

`openapi(self)` ¶

`status(self)` ¶

`pynetbox.core.app.App` ¶

`config(self)` ¶