Inventory Device Serial Variables

ManageThe Inventory Device Serial Variables API provides endpoints for managing and retrieving configuration parameters and variables associated with specific devices in your inventory. These endpoints allow you to query device-specific settings by serial number and update device serialconfigurations variables and parameters for inventory devices.programmatically.

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 is designed for managing device-specific configuration parameters and variables in your network inventory system. This API category focuses on device-level settings that are tied to specific serial numbers, allowing for granular control over individual device configurations.

Key Concepts:

Device Serial Variables: Configuration parameters and settings associated with specific device serial numbers Parameter Filtering: Advanced filtering capabilities to retrieve specific configuration variables by name, short name, or variable name Pending Settings: Track and manage configuration changes that are pending deployment to devices Wildcard Support: Use pattern matching to query multiple related parameters efficiently

Common Use Cases:

Retrieving current configuration settings for a specific device Bulk updating device parameters across multiple variables Monitoring pending configuration changes before deployment Auditing device-specific settings for compliance purposes Automating device configuration management workflows

The API supports both read and write operations, enabling comprehensive device configuration management through programmatic interfaces.

---

Endpoints

GET /inventory_device_serial_variables/

RetrieveDescription: deviceRetrieves serialconfiguration variables and parameters filteredfor bydevices devicebased on serial number.number filtering. This endpoint allowsis youessential tofor fetchquerying current device settings, monitoring configuration variablesstates, and theirretrieving specific parameter values for inventory management.

Use Cases:

Audit all configuration parameters for a specific device Retrieve pending configuration changes before deployment Query specific parameter values across multiple devices inMonitor yourdevice inventory.settings for compliance verification

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_variables/?parent__serial_number=SN123456789&parameter__variable_name=hostname,ip_address&limit=50

Parameters:

Parameter	Type	In	Required	Description
parent__serial_number	string	query	Yes	Filter settings by devicethe parent device's serial numbernumber. This is the primary identifier for targeting specific devices.
parameter__variable_name	string	query	No	Comma-separated list of parameter variable names to retrieve (e.g., "hostname,ip_address,vlan_id")
parameter__name	string	query	No	Comma-separated list of parameter display names to retrieve (e.g., "Device Hostname,IP Address")
parameter__short_name	string	query	No	Comma-separated list of parameter short names tofor retrieveabbreviated parameter identification
limit	integer	query	No	Number of results to return per page (default: 20, max: 100)
offset	integer	query	No	InitialStarting index for paginatedpagination results(default: 0)
pending	boolean	query	No	ShowSet ifto devicetrue hasto show only parameters with pending settingschanges awaiting deployment
wildcard	boolean	query	No	Enable wildcard ('*') pattern matching forin variable/parametervariable_name namesor parameter_name fields
extra	boolean	query	No	Include additional metadata and extended parameter information in the response

ExamplecURL Request:Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_serial_variables/?parent__serial_number=ABC123456SN123456789&parameter__variable_name=firmware_version,device_namehostname,ip_address&extra=truetrue" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 2,15,
  "next": null,"https://control.zequenze.com/api/v1/inventory_device_serial_variables/?limit=10&offset=10&parent__serial_number=SN123456789",
  "previous": null,
  "results": [
    {
      "id": 1,1001,
      "parent_serial_number": "ABC123456"SN123456789",
      "parameter": {
        "variable_name": "firmware_version"hostname",
        "name": "FirmwareDevice Version"Hostname",
        "short_name": "fw_ver"host",
        "data_type": "string",
        "description"category": "Current firmware version"network"
      },
      "value"current_value": "2.1.4"switch-floor-2-rack-1",
      "pending"pending_value": false,"switch-floor-2-rack-1-updated",
      "last_updated"is_pending": true,
      "last_modified": "2024-01-15T10:15T14:30:00Z",
      "modified_by": "admin@company.com"
    },
    {
      "id": 2,1002,
      "parent_serial_number": "ABC123456"SN123456789",
      "parameter": {
        "variable_name": "device_name"ip_address",
        "name": "DeviceManagement Name"IP Address",
        "short_name": "name"mgmt_ip",
        "data_type": "string"ipv4",
        "description"category": "Human readable device name"network"
      },
      "value"current_value": "Production Router 01"192.168.1.100",
      "pending"pending_value": true,null,
      "last_updated"is_pending": false,
      "last_modified": "2024-01-15T11:45:10T09:15:00Z",
      "modified_by": "network@company.com"
    }
  ]
}

Response Codes:

Status	Description
200	SuccessfullySuccess retrieved- Returns device variables and parameters
400	InvalidBad parametersRequest or- missingMissing required serialparent__serial_number numberparameter
401	Unauthorized - invalidInvalid or missing Bearerauthentication token
404	Not Found - Device with specified serial number not found

---

PUT /inventory_device_serial_variables/{parent__serial_number}/

UpdateDescription: deviceUpdates serialconfiguration variables and parameters for a specific device.device identified by its serial number. This endpoint allows bulk updating of multiple device parameters in a single request, making it efficient for configuration variablesmanagement and deployment workflows.

Use Cases:

Deploy pending configuration changes to a device Bulk update multiple device parameters forsimultaneously inventoryApply devices.standardized configuration templates to devices Rollback device configurations to previous states

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_variables/SN123456789/

Parameters:

Parameter	Type	In	Required	Description
parent__serial_number	string	path	Yes	Serial number of the targetdevice deviceto update (included in the URL path)
data	string	body	Yes	JSON stringpayload containing variablethe parameter updates and configuration changes

ExamplecURL Request:Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_serial_variables/ABC123456/SN123456789/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/jsonjson" \
  -d '{
    "variables"parameters": [
      {
        "variable_name": "device_name"hostname",
        "value": "Updated Router Name"switch-floor-2-rack-1-new"
      },
      {
        "variable_name": "location"ip_address", 
        "value": "Data Center A - Rack 15"192.168.1.101"
      },
      {
        "variable_name": "maintenance_window"vlan_id",
        "value": "Sunday 02:00-04:00 UTC"100"
      }
    ],
    "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:

{
  "updated"success": true,
  "updated_parameters": 3,
  "results"device_serial_number": "SN123456789",
  "changes": [
    {
      "variable_name": "device_name"hostname",
      "value"previous_value": "Updatedswitch-floor-2-rack-1",
      Router"new_value": Name""switch-floor-2-rack-1-new",
      "status": "updated",
      "pending": true
    },
    {
      "variable_name": "location"ip_address",
      "value"previous_value": "Data192.168.1.100",
      Center"new_value": A - Rack 15""192.168.1.101", 
      "status": "updated",
      "pending": true
    },
    {
      "variable_name": "maintenance_window"snmp_community",
      "value"previous_value": "Sunday[hidden]",
      02:00-04:00"new_value": UTC""[hidden]",
      "status": "updated",
      "pending": true
    }
  ],
  "message"deployment_status": "Devicepending",
  variables"backup_created": updatedtrue,
  successfully""backup_id": "backup_20240115_143000",
  "timestamp": "2024-01-15T14:30:00Z",
  "modified_by": "api_user@company.com"
}

Response Codes:

Status	Description
200	VariablesSuccess - Parameters updated successfully
400	Bad Request - Invalid dataparameter formatvalues or missingmalformed required fieldsrequest
401	Unauthorized - invalidInvalid or missing Bearerauthentication token
404	Not Found - Device with specified serial number not found
422	Unprocessable Entity - Validation errors in variableparameter datavalues

---

Common Use Cases

Use Case 1: Device Configuration Audit

Query all configuration parameters for a specific device to perform compliance auditing and verify current settings against organizational standards.

https://control.zequenze.com/api/v1/inventory_device_serial_variables/?parent__serial_number=SN123456789&extra=true

Use Case 2: Network Parameter Updates

Update critical network parameters (hostname, IP address, VLAN) for a device during network reorganization or maintenance windows.

Use Case 3: Pending Changes Review

Monitor devices with pending configuration changes before deploying updates to production environments.

https://control.zequenze.com/api/v1/inventory_device_serial_variables/?parent__serial_number=SN123456789&pending=true

Use Case 4: Bulk Parameter Retrieval

Retrieve specific configuration parameters across multiple API calls for reporting and monitoring dashboards.

Use Case 5: Configuration Template Deployment

Apply standardized configuration templates to new devices by updating multiple parameters simultaneously through the PUT endpoint.

---

Best Practices

• Pagination: Use specific filters: When retrieving variables, use parameter__variable_name or parameter__name filters to limit results to only the variables you need

Enable wildcard matching: Set wildcard=true when using pattern matching with asterisks (*) in variable names Check pending status: Use the pending parameter to identify devices with configuration changes that haven't been applied yet Batch updates efficiently: When updating multiple variables, include them all in a single PUT request rather than making individual calls Handle pagination: For devices with many variables, use limit and offset parameters to managefor large result sets to improve performance and reduce response times ValidateParameter Filtering: Leverage parameter filtering (variable_name, name, short_name) to retrieve only the data types:you Ensureneed, variablereducing valuesbandwidth match the expected data type defined in the parameter configurationusage MonitorPending updateChanges: status: After updates,Always check thefor pending fieldchanges before making updates to trackavoid conflicts or overwriting uncommitted configurations Validation: Use the validation flags in PUT requests to catch configuration errors before deployment Backup Strategy: Enable backup_current when making significant configuration changes are applied to allow for quick rollbacks Error Handling: Implement proper error handling for 422 validation errors, especially when updating critical network parameters Rate Limiting: Space out API calls appropriately when processing multiple devices to avoid hitting rate limits Security: Never log sensitive parameter values (passwords, SNMP communities) in your application logs Wildcard Usage: Use wildcards sparingly and with specific patterns to avoid retrieving excessive amounts of data

---