Adding Models
1. Define the model class
APIs, SDKs, integrations, and development tools
View all tags1. Define the model class
Unlike the web UI, where a user's selected branch remains active until it is changed, the desired branch must be specified with each REST API request. This is accomplished by including the X-NetBox-Branch HTTP header specifying the branch's schema ID.
NetBox includes a slew of features which enable integration with other tools and resources powering your network.
The following instructions assume you have installed NetBox in the /opt/netbox directory. Adjust instructions as necessary if you've installed NetBox in a different directory.
NetBox Cloud connectivity via AWS Private Link with VPC endpoints using private IPs for enhanced security and performance.
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.
Each circuit may have up to two terminations, designated A and Z. At either termination, a circuit may connect to a site, device interface (via a cable), or to a provider network.
A circuit represents a physical point-to-point data connection, typically used to interconnect sites across considerable distances (e.g. to deliver Internet connectivity).
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.
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 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.
Thanks for your interest in contributing to pynetbox! This introduction covers a few important things to know before you get started.
The Diode project is currently in Public Preview. Please see NetBox Labs Product and Feature Lifecycle for more details.
The Diode Agent is a lightweight network device discovery tool that uses NAPALM to streamline data entry into NetBox through the Diode ingestion service. The following is a basic set of instructions to get started using Diode Agent on a local machine.
The Diode SDK is a Python library for sending data to the Diode server over gRPC/protbuf for ingestion in to NetBox.
Requirements
reference architecture
Comprehensive guide to help determine if you need specialized cloud connectivity options for NetBox Cloud or if standard internet delivery meets your requirements.
handler: python
SENTRY_DSN
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.
Overview of features and capabilities available in the NetBox Cloud Free Plan, including limitations and upgrade options.
Before getting started
This guide will help you get started with development on pynetbox. It covers setting up your development environment and running tests.
Complete setup and configuration guide for NetBox Assurance - from installation to your first operational workflow with step-by-step instructions
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.
NetBox provides a read-only GraphQL API to complement its REST API. This API is powered by Strawberry Django.
GRAPHQL_ENABLED
NetBox
Before Starting
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 /.
Configure automatic group synchronization and role mapping between Microsoft Entra ID and NetBox Cloud for streamlined user access management.
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
Automated operational drift detection for NetBox - continuously monitor network infrastructure and maintain accurate documentation with proactive remediation capabilities
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.
Comprehensive overview of the NetBox Cloud Administrative Console interface, features, and sections including deployment, database, and monitoring panels.
Advanced network discovery and observability solution for automated network documentation and drift detection across all NetBox deployments
1.10.1/1.10.2
Much like the NetBox software itself, NetBox Enterprise uses 2 main datastores: PostgreSQL, and Redis.
Advanced installation options for NetBox Enterprise Helm deployment
System requirements and prerequisites for NetBox Enterprise Helm installation
Troubleshooting guide for NetBox Enterprise Helm installation issues
Configuration guide for customizing NetBox Enterprise Helm deployment using values-extra.yaml
Tested Versions
This section of the documentation discusses installing and configuring the NetBox application itself.
Model Types
v2.0.10 (2017-07-14)
v2.1.6 (2017-10-11)
v2.10.10 (2021-04-15)
v2.11.12 (2021-08-23)
v2.2.10 (2018-02-21)
v2.3.7 (2018-07-26)
v2.4.9 (2018-12-07)
v2.5.13 (2019-05-31)
v2.6.12 (2020-01-13)
v2.7.12 (2020-04-08)
v2.9.11 (2020-12-11)
v3.0.12 (2021-12-06)
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.3 (2025-06-26)
This guide outlines the steps necessary for planning a successful migration to NetBox. Although it is written under the context of a completely new installation, the general approach outlined here works just as well for adding new data to existing NetBox deployments.
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.
Configure and manage IP prefix lists for NetBox Cloud security, including both synchronized and non-synchronized prefix list creation and management.
NetBox supports optionally exposing native Prometheus metrics from the application. Prometheus is a popular time series metric platform used for monitoring.
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:
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.
Global Search
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.
New Tables in ServiceNow
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.
A tunnel termination connects a device or virtual machine interface to a tunnel. The tunnel must be created before any terminations may be added.
A tunnel represents a private virtual connection established among two or more endpoints across a shared infrastructure by employing protocol encapsulation. Common encapsulation techniques include Generic Routing Encapsulation (GRE), IP-in-IP, and IPSec. NetBox supports modeling both peer-to-peer and hub-and-spoke tunnel topologies.
Distribution and Installation
This plugin includes support for activating and deactivating branches via the REST API in addition to conventional creation, modification, and deletion operations.
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.
The home of documentation for NetBox Cloud, Enterprise, Integrations, SDKs and Extensions.
A wireless link represents a connection between exactly two wireless interfaces. Unlike a wireless LAN, which permit an arbitrary number of client associations, wireless links are used to model point-to-point wireless connections.