116 docs tagged with "API"

1. Define the model class

NetBox includes a slew of features which enable integration with other tools and resources powering your network.

The registry is an in-memory data structure which houses various application-wide parameters, such as the list of enabled plugins. It is not exposed to the user and is not intended to be modified by any code outside of NetBox core.

Delivery via Private Link between a customer's existing AWS account and the NetBox Labs AWS account, with VPC endpoints using private IPs. This option has fast turn-up times and standard Internet delivery can optionally be disabled.

NetBox plugins can defer certain operations by enqueuing background jobs, which are executed asynchronously by background workers. This is helpful for decoupling long-running processes from the user-facing request-response cycle.

The NetBox branching plugin allows you to create and work with branches in NetBox, similar to version control systems. This enables you to make changes in isolation and merge them back to the main branch when ready.

All connections between device components in NetBox are represented using cables. A cable represents a direct physical connection between two sets of endpoints (A and B), such as a console port and a patch panel port, or between two network interfaces. Cables may be connected to the following objects:

v0.6.0

Every time an object in NetBox is created, updated, or deleted, a serialized copy of that object taken both before and after the change is saved to the database, along with metadata including the current time and the user associated with the change. These records form a persistent record of changes both for each individual object as well as NetBox as a whole. The global change log can be viewed by navigating to Other > Change Log.

One of the critical aspects of operating a network is ensuring that every network node is configured correctly. By leveraging configuration templates and context data, NetBox can render complete configuration files for each device on your network.

Configuration templates can be used to render device configurations from context data. Templates are written in the Jinja2 language and can be associated with devices roles, platforms, and/or individual devices.

Configuration context data (or "config contexts" for short) is a powerful feature that enables users to define arbitrary data that applies to device and virtual machines based on certain characteristics. For example, suppose you want to define syslog servers for devices assigned to sites within a particular region. In NetBox, you can create a config context instance containing this data and apply it to the desired region. All devices within this region will now include this data when fetched via an API.

Each model in NetBox is represented in the database as a discrete table, and each attribute of a model exists as a column within its table. For example, sites are stored in the dcimsite table, which has columns named name, facility, physicaladdress, and so on. As new attributes are added to objects throughout the development of NetBox, tables are expanded to include new rows.

NetBox administrators can extend NetBox's built-in data model by adding custom fields to most object types. See the custom fields documentation for more information.

Custom links allow users to display arbitrary hyperlinks to external content within NetBox object views. These are helpful for cross-referencing related records in systems outside NetBox. For example, you might create a custom link on the device view which links to the current device in a Network Monitoring System (NMS).

Custom scripting was introduced to provide a way for users to execute custom logic from within the NetBox UI. Custom scripts enable the user to directly and conveniently manipulate NetBox data in a prescribed fashion. They can be used to accomplish myriad tasks, such as:

Custom sessions can be used to modify the default HTTP behavior. Below are a few examples, most of them from here.

While NetBox strives to meet the needs of every network, the needs of users to cater to their own unique environments cannot be ignored. NetBox was built with this in mind, and can be customized in many ways to better suit your particular needs.

Each NetBox user can customize his or her personal dashboard by adding and removing widgets and by manipulating the size and position of each. Plugins can register their own dashboard widgets to complement those already available natively.

Data sources can be defined to reference data which exists on systems of record outside NetBox, such as a git repository or Amazon S3 bucket. Plugins can register their own backend classes to introduce support for additional resource types. This is done by subclassing NetBox's DataBackend class.

Creating Models

Thanks for your interest in contributing to pynetbox! This introduction covers a few important things to know before you get started.

DEBUG

Diode is a data ingestion service for NetBox that greatly simplifies and enhances the process of adding and updating data in NetBox, ensuring your network source of truth is always accurate and up to date. Our guiding principle in designing Diode has been to make it as easy as possible to get data into NetBox, removing as much burden as possible from the user while shifting that effort to technology.

Diode SDK Go is a Go library for interacting with the Diode ingestion service utilizing gRPC.

Diode SDK Python is a Python library for interacting with the Diode ingestion service utilizing gRPC.

Internet Delivery (Single Region) is the standard product offering for NetBox Cloud. It comes with extensive security features (see below) and is suitable for the majority of use cases and environments.

handler: python

Plugins can register their own custom event types for use with NetBox event rules. This is accomplished by calling the register() method on an instance of the EventType class. This can be done anywhere within the plugin. An example is provided below.

The exception classes listed here may be raised by a plugin to alter NetBox's default behavior in various scenarios.

NetBox allows users to define custom templates that can be used when exporting objects. To create an export template, navigate to Customization > Export Templates.

Export templates are used to render arbitrary data from a set of NetBox objects. For example, you might want to automatically generate a network monitoring service configuration from a list of device objects. See the export templates documentation for more information.

Below is a list of tasks to consider when adding a new field to a core model.

Installation Issues

Filter sets define the mechanisms available for filtering or searching through a set of objects in NetBox. For instance, sites can be filtered by their parent region or group, status, facility ID, and so on. The same filter set is used consistently for a model whether the request is made via the UI or REST API. (Note that the GraphQL API uses a separate filter class.) NetBox employs the django-filters2 library to define filter sets.

Form Classes

This guide will help you get started with development on pynetbox. It covers setting up your development environment and running tests.

Setting up a Development Environment

This guide will help you set up and start using Diode to ingest data into NetBox.

You can view an on-demand Webinar Getting Started with Network Test Automation: NetBox + pyATS hosted by NetBox Labs.

This cheat sheet serves as a convenient reference for NetBox contributors who already somewhat familiar with using git. For a general introduction to the tooling and workflows involved, please see GitHub's guide Getting started with git.

This guide explains how to configure single sign-on (SSO) support for NetBox using Google OAuth2 as an authentication backend.

Defining the Schema Class

NetBox provides a read-only GraphQL API to complement its REST API. This API is powered by Strawberry Django.

GRAPHQL_ENABLED

Upgrade your Single Sign-On experience with Group Mapping for Microsoft Entra ID SSO – a smarter, more secure way to manage user access. The Group Mapping feature for Entra ID Single Sign-On, streamlines the synchronization of group memberships from Microsoft Entra ID to groups in NetBox Cloud, allowing you to align your user access efficiently and accurately.

NetBox

Before Starting

Beginning with NetBox v4.0, NetBox will leverage Django's automatic translation to support languages other than English. This page details the areas of the project which require special attention to ensure functioning translation support. Briefly, these include:

This document summarizes the system-level changes made to a Linux host when installing a NetBox Enterprise Embedded Cluster, particularly in relation to directories, files, and runtime configurations affected under /.

Migrating from NetBox open source to NetBox Labs Enterprise is a simple and efficient process. Because NetBox Enterprise is built on the same open source platform, database imports can be completed quickly, enabling a smooth transition.

This document serves as a handbook for maintainers of plugins that were written prior to the release of NetBox v4.0. It serves to capture all the changes recommended to ensure a plugin is compatible with NetBox v4.0 and later releases.

ADMINS

Menus

NetBox is the world's leading source of truth for network infrastructure, featuring an extensive and complex data model. But sometimes it can be challenging to orchestrate changes, especially when working within a large team. This plugin introduces a new paradigm for NetBox to help overcome these challenges: branching.

Configuration File

Thanks for your interest in contributing to NetBox! This introduction covers a few important things to know before you get started.

Comprehensive installation guides and configuration files for deploying NetBox Enterprise on Kubernetes using Helm

Tested Versions

NetBox Ansible Collection - Quick Start

Model Types

v2.10.10 (2021-04-15)

v2.11.12 (2021-08-23)

v2.3.7 (2018-07-26)

v2.4.9 (2018-12-07)

v2.6.12 (2020-01-13)

v2.8.9 (2020-08-04)

v2.9.11 (2020-12-11)

v3.1.11 (2022-04-05)

v3.2.9 (2022-08-16)

v3.3.10 (2022-12-13)

v3.4.10 (2023-04-27)

v3.5.9 (2023-08-28)

v3.6.9 (2023-12-28)

v3.7.8 (2024-05-06)

v4.0.11 (2024-09-03)

v4.1.11 (2025-01-06)

v4.2.9 (2025-04-30)

v4.3.4 (2025-07-15)

This guide explains how to configure single sign-on (SSO) support for NetBox using Okta as an authentication backend.

Just getting started with plugins? Check out our NetBox Plugin Tutorial on GitHub! This in-depth guide will walk you through the process of creating an entire plugin from scratch. It even includes a companion demo plugin repo to ensure you can jump in at any step along the way. This will get you up and running with plugins in no time!

This section covers the mechanisms which are available to populate data in NetBox.

Table of Contents

Python API client library for NetBox.

TL;DR

This document outlines the steps required to prepare and publish a new release of pynetbox.

This documentation describes the process of packaging and publishing a new NetBox release. There are three types of releases:

NetBox releases are numbered as major, minor, and patch releases. For example, version 3.1.0 is a minor release, and v3.1.5 is a patch release. Briefly, these can be described as follows:

Replicating the Database

handler: python

handler: python

Plugins can declare custom endpoints on NetBox's REST API to retrieve or manipulate models or other data. These behave very similarly to views, except that instead of rendering arbitrary content using a template, data is returned in JSON format using a serializer.

Filtering Objects

What is a REST API?

When filtering lists of objects in NetBox, users can save applied filters for future use. This is handy for complex filter strategies involving multiple discrete filters. For example, you might want to find all planned devices within a region that have a specific platform. Once you've applied the desired filters to the object list, simply create a saved filter with name and optional description. This filter can then be applied directly for future queries via both the UI and REST API.

NetBox v3.4 introduced a new global search mechanism, which employs the extras.CachedValue model to store discrete field values from many models in a single table.

Global Search

Plugins can define and register their own models to extend NetBox's core search functionality. Typically, a plugin will include a file named search.py, which holds all search indexes for its models (see the example below).

In addition to Django's built-in signals, NetBox defines some of its own, listed below.

NetBox generally follows the Django style guide, which is itself based on PEP 8. ruff is used for linting (with certain exceptions).

Device

Several models in NetBox support the automatic synchronization of local data from a designated remote source. For example, configuration templates defined in NetBox can source their content from text files stored in a remote git repository. This is accomplished using the core data source and data file models.

BASE_PATH

This object represents the saved configuration of an object table in NetBox. Table configs can be crafted, saved, and shared among users to apply specific views within object lists. Each table config can specify which table columns to display, the order in which to display them, and which columns are used for sorting.

NetBox employs the django-tables2 library for rendering dynamic object tables. These tables display lists of objects, and can be sorted and filtered by various parameters.

New Tables in ServiceNow

Templates are used to render HTML content generated from a set of context data. NetBox provides a set of built-in templates suitable for use in plugin views. Plugin authors can extend these templates to minimize the work needed to create custom templates while ensuring that the content they produce matches NetBox's layout and style. These templates are all written in the Django Template Language (DTL).

NetBox includes a Python management shell within which objects can be directly queried, created, modified, and deleted. To enter the shell, run the following command:

NetBox Enterprise Installs

NetBox coordinates all translation work using the Transifex platform. Signing up for a Transifex account is free.

Distribution and Installation

The users.UserConfig model holds individual preferences for each user in the form of JSON data. This page serves as a manifest of all recognized user preferences in NetBox.

This plugin includes support for activating and deactivating branches via the REST API in addition to conventional creation, modification, and deletion operations.

Writing Basic Views

Code Structure

NetBox can be configured via Event Rules to transmit outgoing webhooks to remote systems in response to internal object changes. The receiver can act on the data in these webhook messages to perform related tasks.