API Reference

All validation APIs live under /api/plugins/validation/. Authentication uses a bearer token.

Authentication

curl https://your-netbox/api/plugins/validation/policies/ \
  -H "Authorization: Bearer $NETBOX_TOKEN"

Endpoints

Endpoint	Methods	Description
/policies/	GET, POST	List and create policies
/policies/{id}/	GET, PUT, PATCH, DELETE	Manage a policy
/policies/{id}/clone/	POST	Clone policy with all rules and scoping
/policies/{id}/export/	POST	Export policy as YAML
/policies/import/	POST	Import policy from YAML
/policies/export-all/	POST	Export all policies
/policies/{id}/run-for-site/	POST	Create targeted run for site(s)
/policies/{id}/run-for-devices/	POST	Create targeted run for device(s)
/rules/	GET, POST	List and create rules
/rules/{id}/	GET, PUT, PATCH, DELETE	Manage a rule
/runs/	GET, POST	List and create runs
/runs/{id}/	GET	Run status and summary
/runs/{id}/execute/	POST	Execute a pending run
/runs/validate-device/	POST	Run all matching policies for a device
/results/	GET	Results (filterable by run, device, status)
/findings/	GET, POST	Findings (filterable by run, severity, status, category, site, role, search, latest)
/findings/{id}/	GET, PUT, PATCH	Update finding status
/findings/summary/	GET	Finding counts by status, severity, and category (respects all filters)
/findings/bulk-update-status/	POST	Bulk update finding status ({"ids": [...], "status": "..."})
/compliance/	GET	Compliance scores (filterable by device, policy)
/policy-packs/	GET	List available policy packs
/policy-packs/{slug}/	GET	Policy pack details with full rule list
/policy-packs/{slug}/install/	POST	Install a policy pack
/policy-packs/{slug}/uninstall/	POST	Uninstall a policy pack

Common Patterns

Create and Execute a Run

# Step 1: Create the run
curl -X POST https://your-netbox/api/plugins/validation/runs/ \
  -H "Authorization: Bearer $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"policy": 1, "trigger": "manual"}'

# Step 2: Execute it
curl -X POST https://your-netbox/api/plugins/validation/runs/1/execute/ \
  -H "Authorization: Bearer $NETBOX_TOKEN"

Create a Targeted Run

curl -X POST https://your-netbox/api/plugins/validation/runs/ \
  -H "Authorization: Bearer $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "policy": 1,
    "trigger": "api",
    "target_sites": [9],
    "target_devices": [101, 102, 103],
    "target_tags": ["production"]
  }'

Run Against a Branch

curl -X POST https://your-netbox/api/plugins/validation/runs/ \
  -H "Authorization: Bearer $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"policy": 1, "trigger": "manual", "branch_id": 5}'

Filter Results

# Failed results only
curl "https://your-netbox/api/plugins/validation/results/?status=fail" \
  -H "Authorization: Bearer $NETBOX_TOKEN"

# Results for a specific device
curl "https://your-netbox/api/plugins/validation/results/?device_id=10" \
  -H "Authorization: Bearer $NETBOX_TOKEN"

# Current findings only (latest run per policy)
curl "https://your-netbox/api/plugins/validation/findings/?latest=true" \
  -H "Authorization: Bearer $NETBOX_TOKEN"

# Current critical findings
curl "https://your-netbox/api/plugins/validation/findings/?latest=true&severity=critical" \
  -H "Authorization: Bearer $NETBOX_TOKEN"

# Search findings by text (searches title, description, remediation)
curl "https://your-netbox/api/plugins/validation/findings/?latest=true&q=cable" \
  -H "Authorization: Bearer $NETBOX_TOKEN"

# Filter findings by site or device role
curl "https://your-netbox/api/plugins/validation/findings/?latest=true&site_id=9" \
  -H "Authorization: Bearer $NETBOX_TOKEN"

# Only new findings (first occurrence)
curl "https://your-netbox/api/plugins/validation/findings/?latest=true&is_new=true" \
  -H "Authorization: Bearer $NETBOX_TOKEN"

# Compliance history for a device
curl "https://your-netbox/api/plugins/validation/compliance/?device_id=10&ordering=-measured_at" \
  -H "Authorization: Bearer $NETBOX_TOKEN"

YAML Import/Export

# Export a single policy
curl -X POST https://your-netbox/api/plugins/validation/policies/1/export/ \
  -H "Authorization: Bearer $NETBOX_TOKEN"

# Export all policies
curl -X POST https://your-netbox/api/plugins/validation/policies/export-all/ \
  -H "Authorization: Bearer $NETBOX_TOKEN"

# Import a policy from YAML
curl -X POST https://your-netbox/api/plugins/validation/policies/import/ \
  -H "Authorization: Bearer $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d @my-policy.yaml

Agentic Integration

AI agents and tools can access NetBox Validation through the Validation tools in the NetBox Labs Platform MCP Server. The MCP server provides five discrete tools to enable agents to work with NetBox Validation:

Tool	Description
run_validation	Create and execute a validation run for a policy, optionally targeting a branch or specific devices
get_compliance_analytics	Retrieve compliance scores, trends, and score-by-dimension breakdowns
get_findings_analytics	Get findings with filtering by severity, status, category, and policy
import_validation_policy	Import a validation policy from YAML
clone_validation_policy	Clone an existing policy with all rules and scoping

These tools enable agents to:

• Validate before merging: Run validation against a branch and check results before creating a change request
• Monitor compliance: Query compliance scores to identify the lowest-scoring policies or devices
• Triage findings: Retrieve and prioritize findings by severity and category
• Manage policies: Import and clone policies programmatically as part of automated workflows

Agents that prefer direct API access can use the REST API endpoints documented above with standard bearer token authentication.