Skip to content
Python client API for Netbox
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
netboxapi Fix mappers comparaison Feb 12, 2019
tests Fix mappers comparaison Feb 12, 2019
.gitignore Initial commit Mar 27, 2017
.travis.yml Add python 3.7 in travis and tox Jul 5, 2018 Initial commit Mar 27, 2017 Initial commit Mar 27, 2017 Fix travis status url Jun 22, 2019
setup.cfg Bump version: 1.1.6 → 1.1.7 Feb 12, 2019 Bump version: 1.1.6 → 1.1.7 Feb 12, 2019
tox.ini Add python 3.7 in travis and tox Jul 5, 2018

Python Netbox API

Build Status Coverage Status

Python client API for Netbox, using requests.


Netbox API

Import NetboxAPI:

from netboxapi import NetboxAPI

Initialize a new NetboxAPI object:

netbox_api = NetboxAPI(url="")

# or if you enabled the authentication
netbox_api = NetboxAPI(
    url="", username="user", password="password"

# or if you have generated a token
netbox_api = NetboxAPI(
    url="", token="token"

# but the following is useless, as the token will not be used
netbox_api = NetboxAPI(
    url="", username="user", password="password",

Then use multiple available methods to interact with the api:

>>> netbox_api.get("dcim/sites/1/racks/")
    "id": 1,
    "name": "Some rack",

>>>"dcim/device-roles/", json={"name": "test", …},)
    "id": 1,
    "name": "test",

>>> netbox_api.patch("dcim/device-roles/", json={"slug": "test"},)
    "id": 1,
    "name": "test",
    "slug": "test",

>>> netbox_api.put("dcim/device-roles/1/", json={"name": "test", …},)
    "id": 1,
    "name": "test",
    "slug": "test",

>>> netbox_api.delete("dcim/sites/1/")
<<Response [204]>>

Netbox Mapper

NetboxMapper is available to interact with Netbox objects. Received json from the netbox API is converted into mapper objects, by setting its attributes accordingly to the dict. To use it, first import NetboxMapper:

from netboxapi import NetboxAPI, NetboxMapper

Initialize a new NetboxMapper object:

netbox_api = NetboxAPI(
    url="", username="user", password="password"
netbox_mapper = NetboxMapper(netbox_api, app_name="dcim", model="sites")


Then get all objects of the model:

>>> sites = list(netbox_mapper.get())
[<NetboxMapper>, <NetboxMapper>, …]

>>> print(sites[0].id)
>>> print(sites[0].name)
"Some site"

Or get a specific site by its id:

>>> netbox_mapper.get(1)

It is possible to get a subresourses of an object, and/or specify a query:

>>> netbox_mapper.get("1", "racks", q="name_to_filter")

Any kwargs (here q=) is used as a GET parameter for the request.

Pagination is transparently handled, but it is possible to specify how many items are wanted per page by setting the GET parameter limit, to limit the number of requests done to Netbox in case of long iterations.

Foreign keys

Foreign keys are handle automatically by the mapper.

>>> site = next(netbox_mapper.get())
>>> print(
"Some region"

When accessing to site.region, a query will be done to fetch the foreign object. It will then be saved in cache to avoid unnecessary queries for next accesses.

To refresh an object and its foreign keys, just do:

>>> site = next(site.get())


Use the kwargs of a mapper to send a post request and create a new object:

>>>"A site", slug="a_site", region="Some region")
<NetboxMapper>  # corresponding to the new created object

If a mapper is sent as parameter, post() will automatically take its id. However, it will not update the foreign object.


Use put() in a child mapper to update the resource upstream by reflecting the changes made in the object attributes:

>>> child_mapper = netbox_mapper.get(1)
>>> = "another name"
>>> child_mapper.put()
<requests>  # requests object containing the netbox response


PATCH is not supported in mappers, as it does not make really sense (to me) with the mapper logic.


Delete an object upstream by calling delete():

>>> netbox_mapper.delete(1)
<requests>  # requests object containing the netbox response

# OR

>>> child_mapper = netbox_mapper.get(1)
>>> child_mapper.delete()
<requests>  # requests object containing the netbox response

But trying to delete another object of the same model from a child mapper is not possible:

>>> child_mapper = netbox_mapper.get(1)
>>> child_mapper.delete(2)
Exception ForbiddenAsChildError


  • python 3.4 (it certainly works with prior versions, just not tested)


Tool under the BSD license. Do not hesitate to report bugs, ask me some questions or do some pull request if you want to!

You can’t perform that action at this time.