Skip to main content

Inventory Device Serial Variables

The Inventory Device Serial Variables API provides endpointsaccess forto managing and retrievingdevice-specific configuration parameters and variables associated with specificfor devices in your inventory. These endpoints allow you to query device-specific settings by serial numberretrieve and update variable settings associated with specific device configurationsserial programmatically.numbers, enabling centralized device configuration management and monitoring of pending changes.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Serial Variables API iscategory designedmanages configuration variables and parameters for managingindividual device-specific configuration parameters and variablesdevices in your network inventory system. ThisEach APIdevice, categoryidentified focusesby onits device-level settings that are tied to specificunique serial numbers,number, allowingcan forhave granularmultiple controlconfigurable overparameters individualsuch deviceas configurations.network settings, operational thresholds, feature flags, and custom variables.

Key Concepts:

  • Device Serial Variables:Variables: Configuration parameters andtied settings associated withto specific device serial numbers
  • ParameterVariable Filtering:Names: AdvancedUnique filteringidentifiers capabilities to retrieve specificfor configuration variablesparameters by(e.g., name,"network_timeout", short"max_connections")
name, orParameter variableNames: nameHuman-readable names for configuration options Pending Settings:Status: TrackIndicates and managewhether configuration changes that are pending deploymentwaiting to devicesbe applied to the device WildcardExtra Support:Information: UseAdditional patternmetadata matchingor computed values related to query multiple related parameters efficiently

Common Use Cases:Scenarios:

  • Retrieving current configuration settings for a specific device before maintenance
  • Bulk updating device parameterssettings across multiple variablesparameters
  • Monitoring which devices have pending configuration changes before deployment
  • AuditingFiltering device-devices by specific settingsparameter fortypes complianceor purposesvalues
  • Automating deviceImplementing configuration managementtemplates workflowsand standardized settings

TheThis API supports bothwildcard readsearching for flexible parameter queries and writeprovides operations,pagination enablingfor comprehensivehandling large numbers of device configurationvariables management through programmatic interfaces.efficiently.

Endpoints

GET /inventory_device_serial_variables/

Description: Retrieves a list of configuration variables and parameters for devices based on serial number filtering.and optional filtering criteria. This endpoint is essential for queryingviewing current device settings,configurations, monitoringchecking configurationfor states,pending changes, and retrievingfiltering specific parameter valuestypes foracross inventoryyour management.device inventory.

Use Cases:

  • AuditGet all configuration parametersvariables for a specific device before performing updates
  • RetrieveMonitor devices with pending configuration changes beforethat deploymentneed to be applied
  • QueryFilter specific parameter valuestypes (e.g., network settings) across multiple devices
  • MonitorAudit devicecurrent settingsconfiguration states for compliance verificationreporting

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_variables/?parent__serial_number=SN123456789DEV-2024-001&parameter__variable_name=hostname,ip_addressnetwork_timeout,max_connections&pending=true&limit=5020

Parameters:

Parameter Type In Required Description
parent__serial_number string query Yes Filter settings by the parent device'sdevice serial number. This isidentifies the primary identifier for targeting specific devices.device whose variables you want to retrieve
parameter__variable_name string query No Comma-separated list of parameterspecific variable names to retrieve (e.g., "hostname,ip_address,vlan_id"network_timeout,device_mode")
parameter__name string query No Comma-separated list of human-readable parameter display names to retrievefilter (e.g., "Device Hostname,IP Address")by
parameter__short_name string query No Comma-separated list of parameter short names for abbreviated parameterconcise identification
limit integer query No Number of results to return per page (default:default 20,varies, max:typically 50-100)
offset integer query No Starting index for pagination (default: 0)0-based)
pending boolean query No Set to trueFilter to show only parametersvariables with pending changes awaiting(true) deploymentor applied changes (false)
wildcard boolean query No Enable wildcard (*) pattern matching in variable_name or parameter_name fields
extra boolean query No Include additional metadata and extendedcomputed values for each parameter information in the response

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_serial_variables/?parent__serial_number=SN123456789DEV-2024-001&parameter__variable_name=hostname,ip_addressnetwork_timeout,max_connections&extra=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 15,3,
  "next": "https://control.zequenze.com/api/v1/inventory_device_serial_variables/?limit=10&offset=10&parent__serial_number=SN123456789",null,
  "previous": null,
  "results": [
    {
      "id": 1001,
      "parent_serial_number"name": "SN123456789"Network Timeout",
      "parameter": {
      "variable_name": "hostname"network_timeout",
      "name"value": "Device30",
      Hostname""type": "integer",
      "short_name": "host"net_timeout",
      "data_type": "string",
        "category": "network"
      },
      "current_value": "switch-floor-2-rack-1",
      "pending_value": "switch-floor-2-rack-1-updated",
      "is_pending"extra": true,
      "last_modified"extra_value": "2024-01-15T14:30:00Z"seconds",
      "modified_by"pending": "admin@company.com"false
    },
    {
      "id": 1002,
      "parent_serial_number"name": "SN123456789"Maximum Connections",
      "parameter": {
      "variable_name": "ip_address"max_connections",
      "name"value": "Management100",
      IP"type": Address""integer",
      "short_name": "mgmt_ip"max_conn",
      "data_type"extra": "ipv4",false,
      "category": "network"
      },
      "current_value": "192.168.1.100",
      "pending_value"extra_value": null,
      "is_pending"pending": false,true
    },
    {
      "last_modified"id": 1003,
      "name": "2024-01-10T09:15:00Z"Device Mode",
      "modified_by"variable_name": "network@company.com"device_mode",
      "value": "production",
      "type": "string",
      "short_name": "mode",
      "extra": true,
      "extra_value": "enum:production,staging,development",
      "pending": false
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns the filtered device variables and parameters
400 Bad Request - MissingInvalid query parameters or missing required parent__serial_numberserial parameternumber
401 Unauthorized - Invalid or missing authenticationBearer token
404 Not Found - Device with specified serial number does not foundexist

PUT /inventory_device_serial_variables/{parent__serial_number}/

Description: Updates configuration variables and parameters for a specific device identified by its serial number. This endpoint allows bulk updatingupdates of multiple device parameters in a single request, makingautomatically itmarking efficientchanges foras configurationpending managementuntil andthey deploymentcan workflows.be synchronized with the physical device.

Use Cases:

  • Deploy pendingApply configuration changestemplates to anewly deviceprovisioned devices
  • BulkUpdate updatenetwork settings across multiple device parameters simultaneously
  • Apply standardizedImplement configuration templateschanges toas devicespart of maintenance workflows
  • RollbackSynchronize device configurationssettings towith previouscentralized statesconfiguration policies

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_variables/SN123456789/DEV-2024-001/

Parameters:

Parameter Type In Required Description
parent__serial_number string path Yes SerialThe serial number of the device to update (included in the URL path)
data string body Yes JSON payload containing the parametervariable updates andto configuration changesapply

Request Body Format:

{
  "variables": [
    {
      "variable_name": "network_timeout",
      "value": "45"
    },
    {
      "variable_name": "max_connections",
      "value": "150"
    }
  ]
}

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_serial_variables/SN123456789/DEV-2024-001/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters"variables": [
      {
        "variable_name": "hostname"network_timeout",
        "value": "switch-floor-2-rack-1-new"45"
      },
      {
        "variable_name": "ip_address"device_mode",
        "value": "192.168.1.101"
      },
      {
        "variable_name": "vlan_id",
        "value": "100"staging"
      }
    ],
    "deploy_immediately": false,
    "notes": "Monthly configuration update batch"
  }'

Example Request Body:

{
  "parameters": [
    {
      "variable_name": "hostname",
      "value": "switch-floor-2-rack-1-new",
      "validate": true
    },
    {
      "variable_name": "ip_address", 
      "value": "192.168.1.101",
      "validate": true
    },
    {
      "variable_name": "snmp_community",
      "value": "new_community_string",
      "validate": false
    }
  ],
  "deploy_immediately": false,
  "backup_current": true,
  "notes": "Monthly configuration update - Network segment reorganization"
}

Example Response:

{
  "success"id": true,1001,
  "updated_parameters": 3,
  "device_serial_number"name": "SN123456789"Network Timeout",
  "changes": [
    {
  "variable_name": "hostname"network_timeout",
  "previous_value"value": "switch-floor-2-rack-1"45",
  "new_value"type": "switch-floor-2-rack-1-new"integer",
  "status"short_name": "pending"
    },
    {
      "variable_name": "ip_address"net_timeout",
  "previous_value": "192.168.1.100",
      "new_value": "192.168.1.101", 
      "status": "pending"
    },
    {
      "variable_name": "snmp_community",
      "previous_value": "[hidden]",
      "new_value": "[hidden]",
      "status": "pending"
    }
  ],
  "deployment_status": "pending",
  "backup_created"extra": true,
  "backup_id"extra_value": "backup_20240115_143000"seconds",
  "timestamp"pending": "2024-01-15T14:30:00Z",
  "modified_by": "api_user@company.com"true
}

Response Codes:

Status Description
200 Success - ParametersVariables updated successfully
400 Bad Request - Invalid parameterdata valuesformat or malformedvariable requestnames
401 Unauthorized - Invalid or missing authenticationBearer token
404 Not Found - Device with specified serial number does not foundexist
422 UnprocessableValidation EntityError - Validation errors inInvalid parameter values or constraints

Common Use Cases

Use Case 1: Device Configuration Audit

QueryRetrieve all configuration parametersvariables for a specific device to perform compliance auditing and verify current settings againstbefore organizationalperforming standards.maintenance or troubleshooting.

# Get all variables for device
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_serial_variables/?parent__serial_number=SN123456789DEV-2024-001&extra=truetrue" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 2: NetworkBulk ParameterConfiguration UpdatesUpdate

Update criticalmultiple networknetwork-related parameters (hostname, IP address, VLAN) for a device duringin preparation for a network reorganizationinfrastructure orchange.

maintenance
# windows.Update network configuration
curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_serial_variables/DEV-2024-001/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"variables": [{"variable_name": "network_timeout", "value": "60"}, {"variable_name": "retry_attempts", "value": "5"}]}'

Use Case 3: Pending Changes ReviewMonitoring

MonitorIdentify all devices with pending configuration changes beforethat deploying updatesneed to productionbe environments.synchronized.

# Find devices with pending changes
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_serial_variables/?parent__serial_number=SN123456789DEV-2024-001&pending=truetrue" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 4: Bulk Parameter RetrievalType Filtering

Retrieve only specific types of configuration parameters acrossusing multiplewildcard APImatching.

calls
# forGet reportingall andnetwork-related monitoringparameters
dashboards.curl -X GET "https://control.zequenze.com/api/v1/inventory_device_serial_variables/?parent__serial_number=DEV-2024-001&parameter__variable_name=network_*&wildcard=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 5: Configuration Template DeploymentApplication

Apply a standardized configuration templatestemplate to newa devicesnewly byprovisioned updatingdevice.

multiple
# parametersApply simultaneouslyproduction throughconfiguration thetemplate
curl -X PUT endpoint."https://control.zequenze.com/api/v1/inventory_device_serial_variables/DEV-2024-NEW/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"variables": [{"variable_name": "device_mode", "value": "production"}, {"variable_name": "log_level", "value": "warn"}, {"variable_name": "max_connections", "value": "200"}]}'

Best Practices

  • Pagination:Always specify the device serial number: UseThe limitparent__serial_number parameter is required for all GET requests and offsetshould parametersbe the exact serial number as registered in the inventory system.

Use pagination for large result sets: toWhen improvequerying performancedevices with many variables, implement pagination using limit and reduceoffset response times

Parameter Filtering: Leverage parameter filtering (variable_name, name, short_name) to retrieve only the data you need, reducing bandwidth usage Pending Changes: Always check for pending changes before making updatesparameters to avoid conflictstimeout orissues overwritingand uncommittedimprove configurationsperformance.

Validation:Handle pending status appropriately: UseAfter updating variables, they may remain in a "pending" state until synchronized with the validationphysical flagsdevice. inMonitor PUTthe requestspending tofield catchand configurationimplement errorsappropriate beforeretry deploymentlogic for critical updates.

BackupValidate Strategy:variable types and constraints: EnableBefore backup_currentsending whenupdates, makingensure significantvalues configurationmatch changesthe toexpected allowtype for(string, quickinteger, rollbacksboolean) and any constraints indicated in the extra_value field.

ErrorUse Handling:wildcard filtering judiciously: Wildcard searches can be powerful but may impact performance. Use specific parameter names when possible, and enable wildcards only when necessary.

Implement proper error handling: forCheck 422response codes and handle validation errors,errors especially(422) whenby updatingreviewing criticalthe networkerror parametersdetails and correcting invalid parameter values.

RateCache Limiting:frequently accessed variables: Space out API calls appropriately when processing multiple devices to avoid hitting rate limits

Security: Never log sensitive parameter values (passwords, SNMP communities) inIf your application logsfrequently reads the same device variables, implement caching strategies while respecting the pending status for real-time accuracy.

WildcardBatch Usage:related updates: UseWhen wildcardsupdating sparinglymultiple related parameters, use a single PUT request rather than multiple individual requests to ensure consistency and withreduce specificAPI patternsload.

to avoid retrieving excessive amounts of data
Back to top