Inventory Device Variables

ManageThe Inventory Device Variables API provides access to device configuration parameters and configuresettings variables for network devices. These endpoints allow you to retrieve and update device-specific configuration values, monitor pending changes, and manage parameter settings across your device variables and parameters for inventory devices, including retrieval and bulk updates.inventory.

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 management of configuration parameters and variables for individual devices in your network inventory. This API category is essential for:

Device Configuration Management: Retrieve and modify configuration parameters for specific devices, including network settings, operational parameters, and custom variables.

Change Tracking: Monitor pending configuration changes before they are applied to devices, allowing for validation and approval workflows.

Parameter Filtering: Query specific parameters by variable name, parameter name, or short name to focus on relevant configuration data.

Bulk Operations: Update multiple device variables efficiently through structured API calls.

These endpoints work together to provide complete device parameter lifecycle management - from querying current values and pending changes to applying configuration updates. The API supports advanced filtering with wildcard patterns and provides options for retrieving additional metadata like timestamps and parameter details.

---

Endpoints

GET /inventory_device_variables/

RetrieveDescription: Retrieves configuration parameters and variables for a specific device. This endpoint allows you to query device variablessettings, filter by parameter types, and check for pending configuration changes before they are applied to the device.

Use Cases:

Retrieve all configuration parameters for a specific inventorydevice device.Check Supportsfor filteringpending configuration changes before applying updates Query specific parameters by variable name or parameter names,name variableMonitor names,device configuration status and variouscompliance configuration options.

Full URL Example:

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

Parameters:

Parameter	Type	In	Required	Description
parent_id	integer	query	Yes	FilterThe setting by parent (device)device ID to retrieve variables for
parameter__variable_name	string	query	No	Comma Comma-separated list of parameterspecific variable names to retrieve (e.g., "hostname,ip_address,vlan_id")
parameter__name	string	query	No	Comma Comma-separated list of parameter names to retrievefilter by
parameter__short_name	string	query	No	Comma Comma-separated list of parameter short-short names to retrievefilter by
limit	integer	query	No	Number of results to return per page (default: 20, max: 100)
offset	integer	query	No	The initialStarting index fromfor whichpagination to(default: return the results0)
pending	boolean	query	No	Include information if the parameter haveabout pending changes toawaiting be applieddeployment
wildcard	boolean	query	No	UseAllow wildcard ('*') charactercharacters in variable namevariable_name or parameter nameparameter_name fields
force_update	boolean	query	No	Force updaterefresh device settings before gettingfrom the requesteddevice informationbefore returning data
extra	boolean	query	No	ShowInclude additional/extraadditional informationparameter ofmetadata theand parametersdetails
dates	boolean	query	No	ShowInclude datecreation informationand ofmodification the parameterstimestamps

ExamplecURL Request:Example:

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

Example Response:

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,1001,
      "parent_id": 123,
      "variable_name": "system_hostname"hostname",
      "parameter_name": "System Hostname",
      "parameter_short_name": "hostname",
      "short_name"current_value": "host"sw-core-01",
      "value"pending_value": "server01.example.com"sw-core-primary",
      "has_pending_changes": true,
      "data_type": "string",
      "pending_changes"description": false,"Device hostname for network identification",
      "last_modified"last_updated": "2024-01-15T10:30:00Z",
      "extra_info": {
        "description"created_at": "System hostname configuration"2024-01-01T09:00:00Z",
      "category"is_required": true,
      "validation_pattern": "network"
      }^[a-zA-Z0-9-]{1,63}$"
    },
    {
      "id": 2,1002,
      "parent_id": 123,
      "variable_name": "network_ip_primary"management_ip",
      "parameter_name": "ip_address"Management IP Address",
      "short_name"parameter_short_name": "ip"mgmt_ip",
      "value"current_value": "192.168.1.100"10",
      "pending_value": null,
      "has_pending_changes": false,
      "data_type": "ipv4",
      "pending_changes"description": "IP address for device management access",
      "last_updated": "2024-01-10T14:22:00Z",
      "created_at": "2024-01-01T09:00:00Z",
      "is_required": true,
      "last_modified"validation_pattern": "2024-01-15T14:20:00Z",
      ^(?:[0-9]{1,3}\\.){3}[0-9]{1,3}$"extra_info": {
        "description": "Primary IP address",
        "category": "network"
      }
    }
  ]
}

Response Codes:

Status	Description
200	SuccessfullySuccess retrieved- Returns device variables and parameters
400	Bad Request - Invalid parameters or missing required parent_id
401	Unauthorized - Invalid or missing APIauthentication token
404	Not Found - Device with specified parent_id does not foundexist

500 Internal Server Error - Unable to retrieve device variables

---

PUT /inventory_device_variables/{parent_id}/

UpdateDescription: deviceUpdates variablesconfiguration parameters and parametersvariables for a specific inventory device. AllowsThis endpoint allows you to modify device settings by providing new values for one or more parameters. Changes may be applied immediately or staged as pending changes depending on the device configuration.

Use Cases:

Update device configuration parameters (hostname, IP addresses, VLANs) Apply bulk updatesconfiguration ofchanges multiple parameters into a singledevice request.Stage configuration changes for later deployment Modify device-specific operational settings

Full URL Example:

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

Parameters:

Parameter	Type	In	Required	Description
parent_id	integer	path	Yes	The device ID to update variables for
data	string	body	Yes	JSON payload containing variableparameter updates

ExamplecURL Request:Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_variables/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/jsonjson" \
  -d '{
    "variables": [
      {
        "variable_name": "system_hostname"hostname",
        "value": "server01-updated.example.com"sw-core-primary",
        "apply_immediately": false
      },
      {
        "variable_name": "network_ip_primary"management_vlan",
        "value": "192.168.1.101"100",
        "apply_immediately": true
      }
    ]
  }'

Example Request Body:

{
  "variables": [
    {
      "variable_name": "hostname",
      "value": "sw-core-primary",
      "apply_immediately": false,
      "comment": "Updated hostname for primary core switch"
    },
    {
      "parameter_name"variable_name": "management_vlan",
      "value": "100",
      "apply_immediately": true,
      "comment": "Changed management VLAN to 100"
    },
    {
      "variable_name": "snmp_community",
      "value": "public_readonly"
    }
  ]secure_community_string",
      "apply_immediately": false,
      "validate_only"encrypted": falsetrue
    }
  ],
  "batch_comment": "Monthly configuration update",
  "schedule_deployment": "2024-01-20T02:00:00Z"
}

Example Response:

{
  "success": true,
  "updated_count": 3,
  "pending_changes": true,
  "validation_errors": [],
  "updated_variables": [
    {
      "variable_name": "system_hostname"hostname",
      "old_value"previous_value": "server01.example.com"sw-core-01",
      "new_value": "server01-updated.example.com"sw-core-primary",
      "status": "updated"pending",
      "scheduled_for": "2024-01-20T02:00:00Z"
    },
    {
      "variable_name": "network_ip_primary"management_vlan",
      "old_value"previous_value": "192.168.1.100"10",
      "new_value": "192.168.1.101"100",
      "status": "updated"applied",
      "applied_at": "2024-01-15T15:45:00Z"
    },
    {
      "parameter_name"variable_name": "snmp_community",
      "old_value"previous_value": "public"[ENCRYPTED]",
      "new_value": "public_readonly"[ENCRYPTED]",
      "status": "updated"pending",
      "scheduled_for": "2024-01-20T02:00:00Z"
    }
  ],
  "batch_id": "batch_2024011515450123",
  "total_updated": 3,
  "pending_count": 2,
  "applied_count": 1,
  "next_deployment": "2024-01-20T02:00:00Z"
}

Response Codes:

Status	Description
200	SuccessfullySuccess - Variables updated device variablessuccessfully
400	Bad Request - Invalid requestvariable data or validation errors
401	Unauthorized - Invalid or missing APIauthentication token
404	Not Found - Device with specified parent_id does not foundexist
422	Unprocessable entityEntity - InvalidVariable variablevalidation valuesfailed

500 Internal Server Error - Unable to update device variables

---

Common Use Cases

Use Case 1: Configuration Compliance Check

Query all device parameters to verify compliance with organizational standards, checking for pending changes and validating current configurations against policy requirements.

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

Use Case 2: Network Parameter Updates

Update critical network parameters like hostnames, management IPs, and VLAN configurations as part of network reorganization or device migration.

# Update hostname and management IP for device relocation
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 '{"variables":[{"variable_name":"hostname","value":"sw-new-location"},{"variable_name":"management_ip","value":"10.1.1.50"}]}'

Use Case 3: Security Configuration Management

Retrieve and update security-related parameters like SNMP communities, access control lists, and authentication settings across device inventory.

Use Case 4: Bulk Configuration Deployment

Stage multiple configuration changes for scheduled deployment during maintenance windows, allowing for coordinated network-wide updates.

Use Case 5: Parameter Monitoring and Alerting

Monitor specific device parameters for changes and compliance, integrating with monitoring systems to track configuration drift.

---

Best Practices

Parameter Filtering: Use parent_idspecific filteringparameter filters (parameter__variable_name, parameter__name) to reduce response size and improve performance when working with devices that have many configuration parameters.

Pagination:: Always specifyimplement thepagination parent_idwhen parameter to retrieve variables for specificquerying devices

Leverage wildcard searches: Use the wildcard=true parameter with asteriskextensive (*)configuration characters to find parameters with partial name matches Batch updates efficiently: Use the PUT endpoint to update multiple variables in a single request rather than individual updates Monitor pending changes: Use the pending=true parameter to track which parameters have changes waiting to be applied to the device Validate before applying: Consider using validate_only=true in update requests to check parameter validity before committing changes Handle pagination:parameters. Use limit and offset parameters forto devices withmanage large numbersresult ofsets variablesefficiently.

Change Management: Leverage the pending parameter to avoidreview timeouts

configuration changes before deployment. This allows for approval workflows and change validation processes.

ForceForced updates when neededUpdates:: Use force_update=true tosparingly ensureas you'reit workingtriggers with the latestreal-time device configurationpolling. data

Reserve this Includefor extracritical information:situations Use extra=true and dates=true parameters whenwhere you need additionalthe contextmost aboutcurrent parametersdevice state.

Error Handling: Implement robust error handling for validation failures (422) and theirdevice modificationconnectivity history

issues. Configuration updates may fail due to device-specific constraints or network connectivity problems.

Security Considerations: Be cautious when updating security-related parameters. Always verify that changes don't lock you out of device management access, especially when modifying IP addresses or authentication settings.

Batch Operations: Group related parameter updates into single API calls to maintain configuration consistency and reduce the number of device interactions required.

---