name: netbox-integration-best-practices
description: Best practices for building integrations with NetBox REST and GraphQL APIs. Use when building NetBox API integrations, reviewing integration code, troubleshooting NetBox performance issues, planning automation architecture, writing scripts that interact with NetBox, using pynetbox, configuring Diode for data ingestion, or implementing NetBox webhooks.
license: Apache-2.0
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
REST API Rules
GraphQL Rules
Performance Rules
Data Modeling Rules
Integration Rules
External References
Official Documentation
Essential Tools
Community
Reference Documentation
By