Endpoint

class pynetbox.core.endpoint.Endpoint(api, app, name, model=None)

Represent actions available on endpoints in the Netbox API.

Takes name and app passed from App() and builds the correct url to make queries to and the proper Response object to return results in.

Parameters:
  • api (obj) – Takes Api created at instantiation.
  • app (obj) – Takes App.
  • name (str) – Name of endpoint passed to App().
  • model (obj,optional) – Custom model for given app.

Note

In order to call NetBox endpoints with dashes in their names you should convert the dash to an underscore. (E.g. querying the ip-addresses endpoint is done with nb.ipam.ip_addresses.all().)

all()

Queries the ‘ListView’ of a given endpoint.

Returns all objects from an endpoint.

Returns:List of Record objects.
Examples:
>>> nb.dcim.devices.all()
[test1-a3-oobsw2, test1-a3-oobsw3, test1-a3-oobsw4]
>>>
choices()

Returns all choices from the endpoint.

The returned dict is also saved in the endpoint object (in _choices attribute) so that later calls will return the same data without recurring requests to NetBox. When using .choices() in long-running applications, consider restarting them whenever NetBox is upgraded, to prevent using stale choices data.

Returns:Dict containing the available choices.
Examples:
>>> from pprint import pprint
>>> pprint(nb.ipam.ip_addresses.choices())
{'role': [{'display_name': 'Secondary', 'value': 20},
          {'display_name': 'VIP', 'value': 40},
          {'display_name': 'VRRP', 'value': 41},
          {'display_name': 'Loopback', 'value': 10},
          {'display_name': 'GLBP', 'value': 43},
          {'display_name': 'CARP', 'value': 44},
          {'display_name': 'HSRP', 'value': 42},
          {'display_name': 'Anycast', 'value': 30}],
 'status': [{'display_name': 'Active', 'value': 1},
            {'display_name': 'Reserved', 'value': 2},
            {'display_name': 'Deprecated', 'value': 3},
            {'display_name': 'DHCP', 'value': 5}]}
>>>
count(*args, **kwargs)

Returns the count of objects in a query.

Takes named arguments that match the usable filters on a given endpoint. If an argument is passed then it’s used as a freeform search argument if the endpoint supports it. If no arguments are passed the count for all objects on an endpoint are returned.

Parameters:
  • *args (str,optional) – Freeform search string that’s accepted on given endpoint.
  • **kwargs (str,optional) – Any search argument the endpoint accepts can be added as a keyword arg.
Returns:

Integer with count of objects returns by query.

Examples:

To return a count of objects matching a named argument filter.

>>> nb.dcim.devices.count(site='tst1')
5827
>>>

To return a count of objects on an entire endpoint.

>>> nb.dcim.devices.count()
87382
>>>
create(*args, **kwargs)

Creates an object on an endpoint.

Allows for the creation of new objects on an endpoint. Named arguments are converted to json properties, and a single object is created. NetBox’s bulk creation capabilities can be used by passing a list of dictionaries as the first argument.

Parameters:
  • *args (list) – A list of dictionaries containing the properties of the objects to be created.
  • **kwargs (str) – key/value strings representing properties on a json object.
Returns:

A list or single Record object depending on whether a bulk creation was requested.

Examples:

Creating an object on the devices endpoint you can lookup a device_role’s name with:

>>> netbox.dcim.devices.create(
...    name='test',
...    device_role=1,
... )
>>>

Use bulk creation by passing a list of dictionaries:

>>> nb.dcim.devices.create([
...     {
...         "name": "test1-core3",
...         "device_role": 3,
...         "site": 1,
...         "device_type": 1,
...         "status": 1
...     },
...     {
...         "name": "test1-core4",
...         "device_role": 3,
...         "site": 1,
...         "device_type": 1,
...         "status": 1
...     }
... ])
filter(*args, **kwargs)

Queries the ‘ListView’ of a given endpoint.

Takes named arguments that match the usable filters on a given endpoint. If an argument is passed then it’s used as a freeform search argument if the endpoint supports it.

Parameters:
  • *args (str,optional) – Freeform search string that’s accepted on given endpoint.
  • **kwargs (str,optional) – Any search argument the endpoint accepts can be added as a keyword arg.
Returns:

A list of Record objects.

Examples:

To return a list of objects matching a named argument filter.

>>> nb.dcim.devices.filter(role='leaf-switch')
[test1-a3-tor1b, test1-a3-tor1c, test1-a3-tor1d, test1-a3-tor2a]
>>>

Using a freeform query along with a named argument.

>>> nb.dcim.devices.filter('a3', role='leaf-switch')
[test1-a3-tor1b, test1-a3-tor1c, test1-a3-tor1d, test1-a3-tor2a]
>>>

Chaining multiple named arguments.

>>> nb.dcim.devices.filter(role='leaf-switch', status=True)
[test1-leaf2]
>>>

Passing a list as a named argument adds multiple filters of the same value.

>>> nb.dcim.devices.filter(role=['leaf-switch', 'spine-switch'])
[test1-a3-spine1, test1-a3-spine2, test1-a3-leaf1]
>>>
get(*args, **kwargs)

Queries the DetailsView of a given endpoint.

Parameters:
  • key (int,optional) – id for the item to be retrieved.
  • **kwargs (str,optional) – Accepts the same keyword args as filter(). Any search argument the endpoint accepts can be added as a keyword arg.
Returns:

A single Record object or None

Raises:

ValueError – if kwarg search return more than one value.

Examples:

Referencing with a kwarg that only returns one value.

>>> nb.dcim.devices.get(name='test1-a3-tor1b')
test1-a3-tor1b
>>>

Referencing with an id.

>>> nb.dcim.devices.get(1)
test1-edge1
>>>
class pynetbox.core.endpoint.DetailEndpoint(parent_obj, name, custom_return=None)

Enables read/write Operations on detail endpoints.

Endpoints like available-ips that are detail routes off traditional endpoints are handled with this class.

create(data=None)

The write operation for a detail endpoint.

Creates objects on a detail endpoint in NetBox.

Parameters:data (dict/list,optional) – A dictionary containing the key/value pair of the items you’re creating on the parent object. Defaults to empty dict which will create a single item with default values.
Returns:A dictionary or list of dictionaries its created in NetBox.
list(**kwargs)

The view operation for a detail endpoint

Returns the response from NetBox for a detail endpoint.

Args **kwargs:key/value pairs that get converted into url parameters when passed to the endpoint. E.g. .list(method='get_facts') would be converted to .../?method=get_facts.
Returns:A dictionary or list of dictionaries retrieved from NetBox.