Inventory Device Setting

The Device Setting endpoints allow you to retrieve, update, and manage configuration parameters for devices in your inventory. These endpoints are essential for monitoring device configurations, updating settings, and tracking parameter changes across your managed devices.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Setting API provides comprehensive management of device configuration parameters within the Zequenze platform. These endpoints enable you to:

Retrieve device settings - Query configuration parameters for specific devices or groups of devices
Update configurations - Modify device settings through full or partial updates
Track changes - Monitor setting modifications with timestamps and pending status indicators
Filter parameters - Search settings by parameter names, variable names, or device relationships

Device settings in Zequenze represent configurable parameters that can be applied to managed devices. Each setting includes metadata about the parameter type, whether it's required, read-only status, and if it should be tracked as a metric. The system maintains a history of changes and indicates when settings are pending application to the actual device.

Common use cases include bulk configuration updates, compliance monitoring, parameter validation before deployment, and automated device provisioning workflows.

Endpoints

GET /inventory_device_setting/

Description: Retrieves a paginated list of device settings filtered by various criteria. This endpoint is primarily used to query configuration parameters for specific devices or to search for settings based on parameter characteristics. It's essential for configuration audits, bulk operations preparation, and monitoring device parameter states.

Use Cases:

Retrieve all configuration parameters for a specific device before making changes
Search for settings by parameter name across multiple devices
Monitor pending configuration changes that haven't been applied yet
Generate configuration reports for compliance auditing

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_setting/?parent_id=123&parameter__name=wifi_ssid&limit=50&offset=0

Parameters:

Parameter	Type	In	Required	Description
parent_id	integer	query	Yes	The device ID to filter settings for. This identifies which device's settings you want to retrieve
parameter_id	string	query	No	Filter by specific parameter ID if you need settings for a particular parameter type
parameter__variable_name	string	query	No	Filter by parameter variable name (e.g., "wifi_password", "admin_user")
parameter__name	string	query	No	Filter by human-readable parameter name (e.g., "WiFi Password", "Administrator Username")
parameter__short_name	string	query	No	Filter by parameter short name or slug identifier
limit	integer	query	No	Number of results per page (default: 20, max: 100)
offset	integer	query	No	Starting index for pagination (default: 0)
pending	boolean	query	No	Filter for settings that are pending application to the device (true/false)

cURL Example:

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

Example Response:

{
  "count": 25,
  "next": "https://control.zequenze.com/api/v1/inventory_device_setting/?limit=20&offset=20&parent_id=123",
  "previous": null,
  "results": [
    {
      "id": 1547,
      "parent_id": "123",
      "parent__name": "Office-Router-01",
      "parameter": {
        "id": 45,
        "name": "WiFi SSID",
        "short_name": "wifi-ssid",
        "variable_name": "wifi_ssid",
        "type": "string",
        "position": 1,
        "required": true,
        "read_only": false,
        "metric": false,
        "group": {
          "id": 12,
          "name": "Wireless Configuration",
          "service": "WiFi Management",
          "discovery_group": "Network",
          "title": "WiFi Settings"
        }
      },
      "value": "CompanyGuest",
      "created": "2024-01-15T10:30:00Z",
      "last_change": "2024-01-20T14:25:00Z",
      "pending": false
    },
    {
      "id": 1548,
      "parent_id": "123",
      "parent__name": "Office-Router-01",
      "parameter": {
        "id": 46,
        "name": "WiFi Password",
        "short_name": "wifi-password",
        "variable_name": "wifi_password",
        "type": "password",
        "position": 2,
        "required": true,
        "read_only": false,
        "metric": false,
        "group": {
          "id": 12,
          "name": "Wireless Configuration",
          "service": "WiFi Management",
          "discovery_group": "Network",
          "title": "WiFi Settings"
        }
      },
      "value": "********",
      "created": "2024-01-15T10:30:00Z",
      "last_change": "2024-01-22T09:15:00Z",
      "pending": true
    }
  ]
}

Response Codes:

Status	Description
200	Success - Returns paginated list of device settings
400	Bad Request - Missing required parent_id parameter
401	Unauthorized - Invalid or missing API token
403	Forbidden - Insufficient permissions to view device settings
404	Not Found - Device with specified parent_id does not exist

PUT /inventory_device_setting/{parent_id}/

Description: Performs a complete update of device settings for the specified device. This endpoint replaces all current settings with the provided data, making it ideal for bulk configuration updates or when you need to ensure a device has exactly the configuration you specify. Use this when you want to set the complete configuration state of a device.

Use Cases:

Deploy a complete configuration template to a new device
Restore device settings from a known good backup
Standardize device configurations across a fleet
Reset device configuration to factory defaults with custom values

Full URL Example:

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

Parameters:

Parameter	Type	In	Required	Description
parent_id	integer	path	Yes	The device ID whose settings you want to update completely
data	object	body	Yes	Complete device configuration data including all parameter values

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_setting/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": [
      {
        "parameter_id": 45,
        "value": "NewCompanyWiFi"
      },
      {
        "parameter_id": 46,
        "value": "SecurePassword123!"
      },
      {
        "parameter_id": 47,
        "value": "192.168.1.1"
      }
    ]
  }'

Example Response:

{
  "id": 1547,
  "parent_id": "123",
  "parent__name": "Office-Router-01",
  "parameter": {
    "id": 45,
    "name": "WiFi SSID",
    "short_name": "wifi-ssid",
    "variable_name": "wifi_ssid",
    "type": "string",
    "position": 1,
    "required": true,
    "read_only": false,
    "metric": false,
    "group": {
      "id": 12,
      "name": "Wireless Configuration",
      "service": "WiFi Management",
      "discovery_group": "Network",
      "title": "WiFi Settings"
    }
  },
  "value": "NewCompanyWiFi",
  "created": "2024-01-15T10:30:00Z",
  "last_change": "2024-01-25T11:45:00Z",
  "pending": true
}

Response Codes:

Status	Description
200	Success - Device settings updated successfully
400	Bad Request - Invalid data format or missing required parameters
401	Unauthorized - Invalid or missing API token
403	Forbidden - Insufficient permissions to modify device settings
404	Not Found - Device with specified parent_id does not exist
422	Unprocessable Entity - Validation errors in parameter values

PATCH /inventory_device_setting/{parent_id}/

Description: Performs a partial update of device settings, allowing you to modify only specific parameters without affecting other existing settings. This endpoint is ideal for targeted configuration changes, such as updating a single parameter or a small subset of settings while preserving the rest of the device configuration.

Use Cases:

Update a specific configuration parameter (e.g., change WiFi password only)
Apply security updates that affect only certain settings
Make incremental configuration adjustments
Update device settings based on monitoring alerts or policy changes

Full URL Example:

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

Parameters:

Parameter	Type	In	Required	Description
parent_id	integer	path	Yes	The device ID whose settings you want to partially update
data	object	body	Yes	Partial device configuration data with only the parameters you want to modify

cURL Example:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device_setting/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameter_id": 46,
    "value": "NewSecurePassword456!"
  }'

Example Response:

{
  "id": 1548,
  "parent_id": "123",
  "parent__name": "Office-Router-01",
  "parameter": {
    "id": 46,
    "name": "WiFi Password",
    "short_name": "wifi-password",
    "variable_name": "wifi_password",
    "type": "password",
    "position": 2,
    "required": true,
    "read_only": false,
    "metric": false,
    "group": {
      "id": 12,
      "name": "Wireless Configuration",
      "service": "WiFi Management",
      "discovery_group": "Network",
      "title": "WiFi Settings"
    }
  },
  "value": "********",
  "created": "2024-01-15T10:30:00Z",
  "last_change": "2024-01-25T16:20:00Z",
  "pending": true
}

Response Codes:

Status	Description
200	Success - Device setting updated successfully
400	Bad Request - Invalid data format or parameter
401	Unauthorized - Invalid or missing API token
403	Forbidden - Insufficient permissions to modify device settings
404	Not Found - Device or parameter does not exist
422	Unprocessable Entity - Validation error for the parameter value

Common Use Cases

Use Case 1: Device Configuration Audit

Retrieve all settings for a device to perform compliance checking or generate configuration reports. Use the GET endpoint with filtering to examine specific parameter groups or identify pending changes before they're applied.

Use Case 2: Bulk WiFi Password Update

Update WiFi passwords across multiple devices in your network. First, use GET to identify devices with WiFi parameters, then use PATCH to update only the password parameter while preserving other wireless settings.

Use Case 3: New Device Provisioning

Deploy a complete configuration template to newly added devices. Use PUT to apply a standardized configuration that includes all required parameters for your organization's network policies.

Use Case 4: Monitoring Configuration Drift

Regularly query device settings to detect unauthorized changes or configuration drift. Filter by parameter types and use the pending flag to identify settings that haven't been synchronized with the physical device.

Use Case 5: Emergency Security Updates

Quickly update security-related parameters across your device fleet. Use PATCH to modify specific security settings (like admin passwords or access control parameters) without disrupting other operational configurations.

Best Practices

Use pagination wisely: When querying large device inventories, always use appropriate limit values (recommended: 50-100) to avoid timeouts and improve response times.
Monitor pending status: Always check the pending field in responses to understand which settings are queued for application. Schedule follow-up checks to ensure configurations are successfully applied.
Filter effectively: Use parameter-based filters to reduce response sizes and improve query performance. Combine parent_id with specific parameter filters for targeted operations.
Handle parameter types correctly: Respect parameter type definitions when updating values. Boolean parameters expect true/false, integers require numeric values, and password fields may have special validation rules.
Implement retry logic: Device configuration updates may fail due to network issues or device unavailability. Implement exponential backoff retry logic for critical configuration changes.
Validate before bulk operations: Use GET requests to validate current device states and parameter requirements before performing bulk updates with PUT or PATCH.
Track changes with timestamps: Use the created and last_change fields to implement change tracking and audit trails for compliance requirements.
Secure sensitive parameters: Be especially careful with password and security-related parameters. Ensure your application properly handles masked values in responses and validates input for security parameters.