Inventory Device Variables

Endpoints Summary

The Inventory Device Variables API provides access to device configuration parameters and settings for network devices. These endpoints allow you to retrieve current variable values, monitor pending changes, and update device configurations programmatically. Essential for device management, configuration automation, and monitoring system state across your network infrastructure.

Base URL: https://control.zequenze.com/api/v1

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Variables API enables comprehensive management of device configuration parameters within the Zequenze control platform. This API category focuses on the variables and settings that define device behavior, performance characteristics, and operational parameters.

Key Concepts:

• Device Variables: Configuration parameters that control device behavior (e.g., IP addresses, SNMP community strings, timeout values)
• Pending Changes: Modifications that have been staged but not yet applied to the device
• Variable Types: Different categories of parameters (network, system, monitoring, etc.)
• Force Update: Real-time retrieval of current device state vs. cached values

Common Integration Scenarios:

• Configuration Management: Retrieve current device settings for backup or audit purposes
• Bulk Updates: Apply configuration changes across multiple devices programmatically
• Change Tracking: Monitor pending changes before deployment to production devices
• Compliance Monitoring: Verify device configurations match organizational standards
• Automation Workflows: Integrate device variable management into CI/CD pipelines

These endpoints work together to provide complete lifecycle management of device configurations, from initial discovery through ongoing maintenance and updates.

Endpoints

GET /inventory_device_variables/

Description: Retrieves device configuration variables and their current values for a specified device. This endpoint supports extensive filtering options to target specific parameters and can optionally force real-time updates from devices rather than returning cached values.

Use Cases:

• Audit device configurations for compliance verification
• Backup current device settings before making changes
• Monitor specific parameters across multiple devices
• Check for pending configuration changes before deployment

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_variables/?parent_id=123&parameter__variable_name=snmp_community,mgmt_ip&extra=true&pending=true

Parameters:

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_variables/?parent_id=123&parameter__variable_name=snmp_community,mgmt_ip&extra=true&pending=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 15,
  "next": "https://control.zequenze.com/api/v1/inventory_device_variables/?limit=10&offset=10&parent_id=123",
  "previous": null,
  "results": [
    {
      "id": 1247,
      "name": "SNMP Community String",
      "variable_name": "snmp_community",
      "value": "public",
      "type": "string",
      "short_name": "SNMP Comm",
      "extra": true,
      "extra_value": "v2c protocol",
      "pending": false
    },
    {
      "id": 1248,
      "name": "Management IP Address",
      "variable_name": "mgmt_ip",
      "value": "192.168.1.100",
      "type": "ipv4",
      "short_name": "Mgmt IP",
      "extra": false,
      "extra_value": null,
      "pending": true
    },
    {
      "id": 1249,
      "name": "Device Hostname",
      "variable_name": "hostname",
      "value": "core-switch-01",
      "type": "string",
      "short_name": "Hostname",
      "extra": false,
      "extra_value": null,
      "pending": false
    }
  ]
}

Response Codes:

PUT /inventory_device_variables/{parent_id}/

Description: Updates device configuration variables for a specified device. This endpoint accepts bulk variable updates and stages them as pending changes that can be applied to the device. The update operation supports both individual parameter changes and batch modifications.

Use Cases:

• Apply new IP address configurations to devices
• Update SNMP settings across multiple network devices
• Modify device-specific parameters like timeout values or polling intervals
• Stage configuration changes for later deployment during maintenance windows

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_variables/123/

Parameters:

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_variables/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "variable_name": "mgmt_ip",
    "value": "192.168.1.150"
  }'

Example Request Body:

{
  "variable_name": "snmp_community",
  "value": "monitoring123"
}

Example Response:

{
  "id": 1247,
  "name": "SNMP Community String",
  "variable_name": "snmp_community",
  "value": "monitoring123",
  "type": "string",
  "short_name": "SNMP Comm",
  "extra": true,
  "extra_value": "v2c protocol",
  "pending": true
}

Response Codes:

Common Use Cases

Use Case 1: Configuration Audit and Compliance

Retrieve all device variables to verify configurations meet organizational standards, then generate compliance reports highlighting any deviations.

# Get all variables for compliance check
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_variables/?parent_id=123&extra=true&dates=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 2: Bulk IP Address Updates

Update management IP addresses across multiple devices during network restructuring, staging changes to be applied during maintenance windows.

# Update management IP address
curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_variables/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"variable_name": "mgmt_ip", "value": "10.0.1.100"}'

Use Case 3: Monitoring Pending Changes

Check for uncommitted configuration changes before deploying updates to production devices, ensuring change control processes are followed.

# Check for pending changes
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_variables/?parent_id=123&pending=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 4: Real-time Configuration Verification

Force real-time retrieval of device variables to verify that applied changes are active on the device, bypassing cached values.

# Force update from device
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_variables/?parent_id=123&force_update=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 5: Selective Parameter Management

Retrieve and update only specific configuration parameters using wildcard filtering, useful for managing specific aspects like SNMP settings across device fleets.

# Get only SNMP-related variables
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_variables/?parent_id=123&parameter__variable_name=snmp_*&wildcard=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Best Practices

• Use Parent ID Validation: Always verify the parent_id exists and you have appropriate permissions before making requests to avoid unnecessary API calls.

• Implement Change Staging: Utilize the pending changes functionality to stage configuration updates during business hours and apply them during maintenance windows.

• Leverage Filtering: Use specific parameter filtering (variable_name, name, short_name) to reduce response sizes and improve performance when working with devices that have many variables.

• Handle Pagination Properly: For devices with extensive configurations, implement proper pagination handling using limit and offset parameters to avoid timeouts.

• Cache Management: Use the force_update parameter judiciously as it can impact performance; prefer cached values for routine operations and force updates only when real-time accuracy is critical.

• Error Recovery: Implement robust error handling for 404 responses when devices may be offline or have been removed, and for 422 responses when variable constraints are violated.

• Batch Operations: When updating multiple variables, consider the order of operations and potential dependencies between variables to avoid configuration conflicts.

• Security Considerations: Treat device variables as sensitive data; some may contain credentials or security-related configurations that should be handled with appropriate care.