NetBox Integration Best Practices Skill

This skill provides best practices guidance for building integrations and automations with NetBox REST and GraphQL APIs.

Target Audience

• Engineers building integrations atop NetBox APIs
• Teams planning new automations with Claude
• Developers learning NetBox API best practices

Scope: This skill covers API integration patterns. It does NOT cover plugin development, custom scripts, or NetBox administration.

NetBox Version Requirements

Primary target: NetBox 4.4+ with 4.5+ for v2 token features.

When to Apply This Skill

Apply these practices when:

• Building new NetBox API integrations
• Reviewing existing integration code
• Troubleshooting performance issues
• Planning automation architecture
• Writing scripts that interact with NetBox

Priority Levels

Quick Reference

Authentication

• Use v2 tokens on NetBox 4.5+: Bearer nbt_<key>.<token>
• Migrate from v1 before NetBox 4.7 (deprecation planned)

REST API

• Always paginate: ?limit=100 (max 1000)
• Use PATCH for partial updates, not PUT
• Use ?brief=True for list operations
• Exclude config_context: ?exclude=config_context (major performance impact)
• Avoid ?q= search filter at scale; use specific filters
• Bulk operations use list endpoints with JSON arrays (not separate endpoints)

GraphQL

• Use the query optimizer: netbox-graphql-query-optimizer
• Always paginate every list query
• Paginate at every level of nesting
• Beware offset pagination at scale: Deep offsets are slow; use ID range filtering in 4.5.x, cursor-based in 4.6.0+ (#21110)
• Request only needed fields
• Keep depth ≤3, never exceed 5

Performance

• Exclude config_context from device lists
• Use brief mode for large lists
• Parallelize independent requests

Data Ingestion (Diode)

• For high-volume data ingestion, use Diode instead of direct API
• Specify dependencies by name, not ID—Diode resolves or creates them
• No dependency order needed—Diode handles object creation order
• Use pip install netboxlabs-diode-sdk for Python
• Use REST/GraphQL API for reading; use Diode for writing/populating

Rules by Category

Authentication Rules

REST API Rules

GraphQL Rules

Performance Rules

Data Modeling Rules

Integration Rules

External References

Official Documentation

• NetBox Documentation
• REST API Guide
• GraphQL API Guide

Essential Tools

• pynetbox - Official Python client
• netbox-graphql-query-optimizer - Query analysis (essential for GraphQL)
• Diode - Data ingestion service (for high-volume writes)
• Diode Python SDK - Python client for Diode

Community

• NetBox GitHub
• NetBox Discussions

Reference Documentation