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

Feature	Version Required
REST API	All versions
GraphQL API	2.9+
v2 Tokens	4.5+ (use these!)
v1 Token Deprecation	4.7+ (migrate before this)

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

Level	Description	Action
CRITICAL	Security vulnerabilities, data loss, severe performance	Must fix immediately
HIGH	Significant performance/reliability impact	Should fix soon
MEDIUM	Notable improvements, best practices	Plan to address
LOW	Minor improvements, optional	Consider when convenient

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

Branching (Plugin)

Requires netbox-branching plugin.

Lifecycle: Create → Wait (PROVISIONING→READY) → Work → Sync → Merge
Context header: X-NetBox-Branch: {schema_id} (8-char ID, not name)
Async operations: sync/merge/revert return Job objects—poll for completion
Dry-run: All async ops accept {"commit": false} for validation

Rules by Category

Authentication Rules

Rule	Impact	Description
auth-use-v2-tokens	CRITICAL	Use v2 tokens on NetBox 4.5+
auth-provisioning-endpoint	MEDIUM	Use provisioning endpoint for automated token creation

REST API Rules

Rule	Impact	Description
rest-list-endpoint-bulk-ops	CRITICAL	Use list endpoints for bulk operations
rest-pagination-required	HIGH	Always paginate list requests
rest-patch-vs-put	HIGH	Use PATCH for partial updates
rest-brief-mode	HIGH	Use ?brief=True for lists
rest-field-selection	HIGH	Use ?fields= to select fields
rest-exclude-config-context	HIGH	Exclude config_context from device lists
rest-avoid-search-filter-at-scale	HIGH	Avoid q= with large datasets
rest-filtering-expressions	MEDIUM	Use lookup expressions
rest-custom-field-filters	MEDIUM	Filter by custom fields
rest-nested-serializers	LOW	Understand nested serializers
rest-ordering-results	LOW	Use ordering parameter
rest-options-discovery	LOW	Use OPTIONS for discovery

GraphQL Rules

Rule	Impact	Description
graphql-use-query-optimizer	CRITICAL	Use query optimizer
graphql-always-paginate	CRITICAL	Paginate every list query
graphql-pagination-at-each-level	HIGH	Paginate nested lists
graphql-select-only-needed	HIGH	Request only needed fields
graphql-calibrate-optimizer	HIGH	Calibrate against production
graphql-max-depth	HIGH	Keep depth ≤3
graphql-prefer-filters	MEDIUM	Filter server-side
graphql-vs-rest-decision	MEDIUM	Choose appropriate API
graphql-complexity-budgets	LOW	Establish complexity budgets

Performance Rules

Rule	Impact	Description
perf-exclude-config-context	HIGH	Exclude config_context
perf-brief-mode-lists	HIGH	Use brief mode for lists

Data Modeling Rules

Rule	Impact	Description
data-dependency-order	CRITICAL	Create objects in dependency order
data-site-hierarchy	MEDIUM	Understand site hierarchy
data-ipam-hierarchy	MEDIUM	Understand IPAM hierarchy
data-custom-fields	MEDIUM	Use custom fields properly
data-tags-usage	MEDIUM	Use tags for classification
data-tenant-isolation	MEDIUM	Use tenants for separation
data-natural-keys	MEDIUM	Use natural keys

Integration Rules

Rule	Impact	Description
integ-diode-ingestion	HIGH	Use Diode for high-volume data ingestion
integ-pynetbox-client	HIGH	Use pynetbox for Python
integ-branch-api-workflow	HIGH	Complete branching lifecycle (plugin)
integ-branch-context-header	HIGH	Branch context with X-NetBox-Branch header (plugin)
integ-branch-async-operations	MEDIUM	Job polling for sync/merge/revert (plugin)
integ-webhook-configuration	MEDIUM	Configure webhooks
integ-change-tracking	LOW	Query object changes

External References

Official Documentation

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
NetBox Branching - Change management plugin (optional)

Community

Reference Documentation

Document	Purpose
HUMAN.md	Human-readable guide for engineers
netbox-integration-guidelines.md	Comprehensive technical reference

netbox-integration-best-practices

Safety Notice

Copy this and send it to your AI assistant to learn