Skip to main content

Inventory Device Serial Setting

The Inventory Device Serial Settings API allows you to manage configuration parameters and settings for specific devices identified by their serial numbers. These endpoints enable you to retrieve, update, and modify device-specific parameters, track pending changes, and monitor configuration status across your device inventory.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Device Serial Settings API provides granular control over individual device configurations within your inventory management system. These endpoints are designed for managing device-specific parameters, configuration values, and settings that are tied to a device's serial number.

Key Capabilities:

  • Parameter Management: Access and modify device-specific configuration parameters including network settings, operational parameters, and custom configurations
  • Pending Changes Tracking: Monitor and manage configuration changes that are waiting to be applied to devices
  • Filtered Retrieval: Query device settings using various filters such as parameter names, variable names, or parameter types
  • Bulk Operations: Update multiple settings for a device in a single operation

Common Integration Scenarios:

  • Device provisioning and initial configuration setup
  • Remote device management and configuration updates
  • Configuration compliance monitoring and reporting
  • Automated device parameter synchronization
  • Troubleshooting and configuration auditing

The API supports both full updates (PUT) and partial updates (PATCH) for maximum flexibility in configuration management workflows.

Endpoints

GET /inventory_device_serial_setting/

Description: Retrieves a paginated list of configuration settings for devices based on their serial numbers. This endpoint is essential for viewing current device configurations, checking parameter values, and identifying pending changes across your device inventory.

Use Cases:

  • Audit device configurations and parameter values
  • Check for pending configuration changes before maintenance windows
  • Filter device settings by specific parameter types or names
  • Generate configuration reports for compliance or documentation

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_setting/?parent__serial_number=ABC123456&parameter__name=network_config&limit=20

Parameters:

Parameter Type In Required Description
parent__serial_number string query Yes The serial number of the parent device whose settings you want to retrieve
parameter_id string query No Filter by specific parameter ID
parameter__variable_name string query No Filter settings by parameter variable name (e.g., "wifi_ssid", "ip_address")
parameter__name string query No Filter settings by human-readable parameter name
parameter__short_name string query No Filter settings by parameter short name or slug
limit integer query No Number of results to return per page (default varies by system configuration)
offset integer query No Starting index for pagination (use with limit for page navigation)
pending boolean query No Set to true to only return settings with pending changes

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_serial_setting/?parent__serial_number=RTR001234&parameter__name=interface_config&limit=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 25,
  "next": "https://control.zequenze.com/api/v1/inventory_device_serial_setting/?limit=10&offset=10&parent__serial_number=RTR001234",
  "previous": null,
  "results": [
    {
      "id": 1001,
      "parent_id": "RTR001234",
      "parent__name": "Router-Branch-Office-01",
      "parameter": {
        "id": 45,
        "name": "WAN Interface IP Address",
        "short_name": "wan-ip",
        "variable_name": "wan_interface_ip",
        "type": "string",
        "position": 1,
        "required": true,
        "read_only": false,
        "metric": false,
        "group": {
          "id": 3,
          "name": "Network Configuration",
          "service": "routing",
          "discovery_group": "network",
          "title": "Network Settings"
        }
      },
      "value": "192.168.100.1",
      "created": "2024-01-15T10:30:00Z",
      "last_change": "2024-01-20T14:22:15Z",
      "pending": false
    },
    {
      "id": 1002,
      "parent_id": "RTR001234",
      "parent__name": "Router-Branch-Office-01",
      "parameter": {
        "id": 46,
        "name": "DHCP Pool Range",
        "short_name": "dhcp-range",
        "variable_name": "dhcp_pool_range",
        "type": "string",
        "position": 2,
        "required": false,
        "read_only": false,
        "metric": false,
        "group": {
          "id": 3,
          "name": "Network Configuration",
          "service": "dhcp",
          "discovery_group": "network",
          "title": "Network Settings"
        }
      },
      "value": "192.168.100.100-192.168.100.200",
      "created": "2024-01-15T10:30:00Z",
      "last_change": "2024-01-18T09:15:30Z",
      "pending": true
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns paginated list of device settings
400 Bad Request - Missing required parent__serial_number parameter
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Device with specified serial number not found

PUT /inventory_device_serial_setting/{parent__serial_number}/

Description: Performs a complete update of device settings for the specified serial number. This endpoint replaces the entire configuration set with the provided data, making it ideal for bulk configuration updates or complete device reconfiguration scenarios.

Use Cases:

  • Apply complete configuration templates to devices
  • Perform bulk configuration updates during device provisioning
  • Synchronize device settings with centralized configuration management
  • Reset device configurations to standard templates

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_setting/RTR001234/

Parameters:

Parameter Type In Required Description
parent__serial_number string path Yes Serial number of the device to update (included in URL path)
data object body Yes Complete configuration data object containing all settings to apply

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_serial_setting/RTR001234/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": [
      {
        "parameter_id": 45,
        "value": "192.168.100.10"
      },
      {
        "parameter_id": 46,
        "value": "192.168.100.50-192.168.100.150"
      }
    ]
  }'

Example Response:

{
  "id": 1001,
  "parent_id": "RTR001234",
  "parent__name": "Router-Branch-Office-01",
  "parameter": {
    "id": 45,
    "name": "WAN Interface IP Address",
    "short_name": "wan-ip",
    "variable_name": "wan_interface_ip",
    "type": "string",
    "position": 1,
    "required": true,
    "read_only": false,
    "metric": false,
    "group": {
      "id": 3,
      "name": "Network Configuration",
      "service": "routing",
      "discovery_group": "network",
      "title": "Network Settings"
    }
  },
  "value": "192.168.100.10",
  "created": "2024-01-15T10:30:00Z",
  "last_change": "2024-01-22T11:45:20Z",
  "pending": true
}

Response Codes:

Status Description
200 Success - Configuration updated successfully
400 Bad Request - Invalid configuration data or parameter values
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Device with specified serial number not found
422 Unprocessable Entity - Configuration validation failed

PATCH /inventory_device_serial_setting/{parent__serial_number}/

Description: Performs a partial update of device settings, allowing you to modify specific configuration parameters without affecting other settings. This endpoint is perfect for targeted configuration changes and incremental updates to device parameters.

Use Cases:

  • Update specific configuration parameters without changing others
  • Apply incremental configuration changes
  • Modify individual settings based on monitoring alerts or events
  • Fine-tune device parameters during troubleshooting

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_setting/RTR001234/

Parameters:

Parameter Type In Required Description
parent__serial_number string path Yes Serial number of the device to update (included in URL path)
data object body Yes Partial configuration data containing only the settings to modify

cURL Example:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device_serial_setting/RTR001234/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameter_id": 46,
    "value": "192.168.100.75-192.168.100.175"
  }'

Example Response:

{
  "id": 1002,
  "parent_id": "RTR001234",
  "parent__name": "Router-Branch-Office-01",
  "parameter": {
    "id": 46,
    "name": "DHCP Pool Range",
    "short_name": "dhcp-range",
    "variable_name": "dhcp_pool_range",
    "type": "string",
    "position": 2,
    "required": false,
    "read_only": false,
    "metric": false,
    "group": {
      "id": 3,
      "name": "Network Configuration",
      "service": "dhcp",
      "discovery_group": "network",
      "title": "Network Settings"
    }
  },
  "value": "192.168.100.75-192.168.100.175",
  "created": "2024-01-15T10:30:00Z",
  "last_change": "2024-01-22T15:30:45Z",
  "pending": true
}

Response Codes:

Status Description
200 Success - Setting updated successfully
400 Bad Request - Invalid parameter data or value format
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Device or parameter not found
422 Unprocessable Entity - Parameter validation failed

Common Use Cases

Use Case 1: Device Configuration Audit

Retrieve all settings for multiple devices to generate configuration reports and ensure compliance with organizational standards. Use the GET endpoint with various filters to identify devices with specific configurations or pending changes.

Use Case 2: Bulk Device Provisioning

When deploying new devices, use the PUT endpoint to apply complete configuration templates. This ensures consistent setup across similar device types and reduces manual configuration errors.

Use Case 3: Dynamic Configuration Management

Monitor device performance and automatically adjust specific parameters using the PATCH endpoint. For example, modify DHCP ranges, update QoS settings, or adjust security parameters based on network conditions.

Use Case 4: Pending Changes Management

Use the pending=true filter with the GET endpoint to identify all devices with configuration changes waiting to be applied. This is crucial for maintenance planning and change management workflows.

Use Case 5: Parameter-Specific Updates

Filter settings by parameter names or variable names to update specific configuration types across multiple devices. For example, update all WiFi passwords or modify firewall rules across your device fleet.

Best Practices

  • Pagination Strategy: Always use appropriate limit values (typically 10-50) for large device inventories to maintain API performance and avoid timeouts.

  • Serial Number Validation: Ensure serial numbers are properly formatted and exist in your inventory before making update requests to avoid 404 errors.

  • Pending Changes Workflow: Check for pending changes before applying new configurations. Consider implementing a change approval process for critical device parameters.

  • Parameter Type Awareness: Understand parameter types (string, integer, boolean, etc.) and format values correctly. Invalid formats will result in validation errors.

  • Error Handling: Implement robust error handling for 422 responses, as these indicate parameter validation failures. Parse error messages to identify specific validation issues.

  • Change Tracking: Use the last_change timestamp to track configuration history and coordinate updates across multiple systems or team members.

  • Security Considerations: Treat device serial numbers as sensitive identifiers. Implement proper access controls and audit logging for all configuration changes.

  • Batch Operations: For updating multiple parameters on the same device, prefer PUT operations over multiple PATCH requests to reduce API calls and improve consistency.

Back to top