🇺🇸English

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

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

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

Community

• NetBox GitHub
• NetBox Discussions

Reference Documentation

Weekly Installs

65

Repository

netboxlabs/netb…ractices

GitHub Stars

22

First Seen

Jan 25, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

gemini-cli54

codex53

github-copilot52

opencode52

amp50

kimi-cli50