Contents:

TL;DR

Instantiate the Api. Use the methods available on Endpoint to return Record objects.

API

class pynetbox.core.api.Api(url, token=None, private_key=None, private_key_file=None, threading=False)

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:

  • dcim

  • ipam

  • circuits

  • secrets (on NetBox 2.11 and older)

  • tenancy

  • extras

  • virtualization

  • users (since NetBox 2.9)

  • wireless (since NetBox 3.1)

Calling any of these attributes will return App 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.

  • private_key_file (str,optional) – The path to your private key file. (Usable only on NetBox 2.11 and older)

  • private_key (str,optional) – Your private key. (Usable only on NetBox 2.11 and older)

  • threading (bool,optional) – Set to True to use threading in .all() and .filter() requests.

Raises

  • ValueError – If private_key and private_key_file are both specified.

  • 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]
create_token(username, password)

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

Requires NetBox 3.0.0 or newer.

Returns

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}
>>>
openapi()

Returns the OpenAPI spec.

Quick helper function to pull down the entire OpenAPI spec.

Returns

dict

Example

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

Gets the status information from NetBox.

Available in NetBox 2.10.0 or newer.

Returns

Dictionary as returned by NetBox.

Raises

RequestError if the request is not successful.

Example

>>> 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}
>>>
property version

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'
>>>

App

class pynetbox.core.app.App(api, name)

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.

choices()

Returns _choices response from App

Note

This method is deprecated and only works with NetBox version 2.7.x or older. The choices() method in Endpoint is compatible with all NetBox versions.

Returns

Raw response from NetBox’s _choices endpoint.

config()

Returns config response from app

Returns

Raw response from NetBox’s config endpoint.

Raises

RequestError if called for an invalid endpoint.

Example

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

Returns _custom_field_choices response from app

Note

This method only works with NetBox version 2.9.x or older. NetBox 2.10.0 introduced the /extras/custom-fields/ endpoint that can be used f.ex. like nb.extras.custom_fields.all().

Returns

Raw response from NetBox’s _custom_field_choices endpoint.

Raises

RequestError if called for an invalid endpoint.

Example

>>> nb.extras.custom_choices()
{'Testfield1': {'Testvalue2': 2, 'Testvalue1': 1},
 'Testfield2': {'Othervalue2': 4, 'Othervalue1': 3}}

Indices and tables