The REST API empowers you to automate, integrate, and manage network data with a modern, standards-based approach. Here’s how you can start using it to connect, automate, and extend your platform:

1. Authentication:
   • Generate an API token tied to your user account with appropriate permissions.
   • Include the token in your API requests for secure access. Example using an HTTP header:

     Authorization: Token <your_token_here>

   • Optionally, cookie-based authentication is available for browser-based sessions.
2. Core Operations:

   Interact with objects programmatically through standard HTTP verbs:

   HTTP Verb	Purpose
   GET	Retrieve objects or object lists
   POST	Create a new object
   PUT	Replace an object entirely
   PATCH	Update specific fields of an object
   DELETE	Remove an object
   OPTIONS	Show available methods and parameters

3. Making a Request:
   • Construct an HTTP request using your preferred language or script.
   • Example with curl for creating a prefix:

     curl -X POST \
       -H "Authorization: Token <your_token_here>" \
       -H "Content-Type: application/json" \
       http://your-netbox-instance/api/ipam/prefixes/ \
       --data '{"prefix": "192.0.2.0/24", "site": 1}'

4. Filtering and Pagination:
   • Use query parameters to filter, sort, and paginate large datasets.
   • For example: ?site=main&role=production
5. Exploring the API:
   • Discover available endpoints via the built-in API browser at /api/ on your instance.
   • Interactive Swagger/OpenAPI documentation can be found at /api/schema/swagger-ui/.
6. Client Libraries:
   • Use libraries such as pynetbox (Python) or go-netbox (Go) for fast and maintainable integrations.

Understanding the API operations lets you automate and interact with your network data efficiently. Here’s a step-by-step guide for performing common tasks with the REST API:

1. Retrieve Objects (GET):
   • Fetch a list of resources or a specific item by sending a GET request to the relevant endpoint.
     

     curl -X GET -H "Authorization: Token <your_token>" \
       http://your-netbox-instance/api/ipam/ip-addresses/

   • To retrieve a single object, include its unique ID:

     curl -X GET -H "Authorization: Token <your_token>" \
       http://your-netbox-instance/api/ipam/ip-addresses/1001/

2. Create Objects (POST):
   • Add a new object by posting its attributes as JSON.

     curl -X POST -H "Authorization: Token <your_token>" \
       -H "Content-Type: application/json" \
       http://your-netbox-instance/api/ipam/prefixes/ \
       --data '{"prefix": "10.20.0.0/24", "site": 1}'

3. Modify Objects (PUT/PATCH):
   • Update an object entirely with PUT (replace all fields), or update specific fields with PATCH.
     PUT Example:

     curl -X PUT -H "Authorization: Token <your_token>" \
       -H "Content-Type: application/json" \
       http://your-netbox-instance/api/ipam/ip-addresses/1001/ \
       --data '{"address": "10.20.0.5/24", "status": "active"}'

     PATCH Example:

     curl -X PATCH -H "Authorization: Token <your_token>" \
       -H "Content-Type: application/json" \
       http://your-netbox-instance/api/ipam/ip-addresses/1001/ \
       --data '{"description": "DNS monitoring"}'

4. Delete Objects (DELETE):
   • Remove an object by sending a DELETE request to its endpoint.

     curl -X DELETE -H "Authorization: Token <your_token>" \
       http://your-netbox-instance/api/ipam/ip-addresses/1001/

5. Check Supported Operations (OPTIONS):
   • Discover available actions and parameters on any endpoint with the OPTIONS method.

     curl -X OPTIONS -H "Authorization: Token <your_token>" \
       http://your-netbox-instance/api/ipam/prefixes/

6. Inspect Responses:
   • Responses are returned as JSON. Each object contains a unique ID and may have nested fields for related objects.
   • Example response for a single IP address:

     {
       "id": 2954,
       "address": "10.20.0.5/24",
       "description": "Example IP address",
       "status": {
         "value": "active",
         "label": "Active"
       },
       "custom_fields": {},
       "tags": []
     }

NetBox provides flexible ways to tailor and enrich your data model, workflows, and integrations—without impacting the core application. Here’s how you can enhance NetBox to meet your organization’s unique requirements:

1. Add Custom Fields:
   • Define additional metadata for most objects by creating custom fields.
     Steps:
     • Go to Customization > Custom Fields in the NetBox UI.
     • Choose the field type, such as text, integer, boolean, date, URL, JSON, selection, or object reference.
     • Assign the field to relevant object types (like devices, IP addresses, racks).
     • Set options like default values, required/not required, grouping, and display weight.
   • These fields instantly appear in the web UI and API for the assigned objects.
2. Leverage Plugins:
   • Extend NetBox with reusable modules that introduce new models, views, endpoints, and workflows.
     Steps:
     • Install a NetBox-compatible plugin or build your own as a Django app.
     • Enable it via the PLUGINS list in the NetBox configuration.
     • Customize plugin behavior with per-plugin configuration in PLUGINS_CONFIG.
     • Explore added navigation items, pages, or API endpoints under /plugins/.
   • Community plugins allow rapid extension of the platform—integrations, diagrams, reports, and more.
3. Create Custom Scripts & Reports:
   • Use custom Python scripts for complex workflows, automation tasks, or data imports inside NetBox.
   • Build reports to perform validations, audits, or health checks on infrastructure data.
   • Both are accessible from the web UI and are version-controlled for repeatable automation.
4. Export Templates & Custom Links:
   • Define custom export templates using Jinja2 for tailored data outputs or documentation.
   • Add custom links to object pages, enabling seamless navigation or integration with external tools.
5. Build Integrations with Webhooks & Event Rules:
   • Configure webhooks to notify or trigger actions in external systems when data changes occur.
   • Use event rules to automate responses to events such as object creation, modification, or deletion.
6. Extensible Discovery Agent Integrations:
   • Deploy the NetBox Discovery Agent to automate asset and device discovery.
   • Extend with custom “Workers” in Python to add support for third-party systems (e.g., VMware vCenter, Cisco Catalyst).
7. Create Custom Objects:
   • Define entirely new object types to represent data not modeled in NetBox by default—all without writing core code.

Leverage these methods and references to ensure your NetBox integrations, automations, and extensions are secure, efficient, and maintainable:

1. Secure Your API Access:
   • Use token-based authentication and assign the minimum required permissions to each token.
   • Regularly rotate tokens and restrict access based on user and client IP.
   • Avoid exposing API tokens in version-controlled scripts or public repositories.
2. Automate Responsibly:
   • Use pagination parameters for large data sets to avoid overloading the API and server.
   • Implement error handling and validate responses before acting on them.
   • For mass updates or imports, consider using batch processing or throttling requests to ensure reliable operation.
3. Document Your Integrations:
   • Maintain clear internal and project documentation for custom scripts, plugins, and API workflows.
   • Reference the interactive API documentation and built-in browser tools at /api/ and /api/schema/swagger-ui/ for endpoint references and payload examples.
4. Leverage Official Client Libraries:
   • Use libraries such as pynetbox for Python and go-netbox for Go to simplify development and minimize boilerplate code.
   • These libraries help enforce API schema and error handling best practices.
5. Test Customizations Before Production:
   • Always test custom scripts, plugins, and configurations in a staging environment.
   • Use version control to manage changes and roll back if needed.
6. Stay Informed with Official Resources:
   • Regularly consult the NetBox documentation for up-to-date guides, API references, and extensibility options.
   • Explore the plugin index, user community forums, and GitHub repositories for example code and support.
   • Review release notes for enhancements and breaking changes related to REST API and extensibility features.
7. Promote Reusability & Modularity:
   • Modularize scripts and plugins, avoid hard-coding values, and build reusable components where possible.
   • Make use of custom fields, export templates, and webhooks for flexible integrations that evolve alongside your network.