Skip to main content

Inventory Device Name Setting

Endpoints Summary

Method Path Swagger GET /inventory_device_name_setting/ Swagger ↗ PUT /inventory_device_name_setting/{parent__name}/ Swagger ↗ PATCH /inventory_device_name_setting/{parent__name}/ Swagger ↗

The Inventory Device Name SettingSettings API provides endpoints to manage configuration parameters and settings for specific devices in your inventory. These endpoints allow you to retrieve, modify,update, and updatemodify device-specific settingsparameters such as network configurations, operational settings, and custom properties identified by the device name,name. makingThis itis easyessential tofor configuredevice individualconfiguration devicesmanagement withoutand needingmonitoring toin knownetwork their internal IDs.infrastructure.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Name Setting API providescategory aenables streamlinedcomprehensive waymanagement toof managedevice configuration parameters forwithin your network infrastructure. These endpoints are designed to work with individual devices inidentified yourby inventorytheir system.names, Unlikeallowing traditionalyou to retrieve current settings, update configurations, and perform partial modifications to device management that requires internal device IDs, these endpoints use human-readable device names, making them particularly useful for automation scripts, configuration management tools, and administrative interfaces.parameters.

Key Concepts:

  • Device Settings: Configuration parameters that controldefine how a device behavior,operates, appearance,including network settings, operational parameters, and functionalitycustom properties
  • ParametersParameter Types: TemplateVarious definitionsdata thattypes definesupported whatincluding settingsstrings, areintegers, availablebooleans, (name,dates, type,and validationcomplex rules)
types like Values:tables The actual configuration values assigned to each parameter for a specificand device dashboards Pending Status: IndicatesSettings whethermay settinghave a pending state indicating configuration changes arethat waitinghaven't to bebeen applied to the physicaldevice deviceyet Parameter Groups: Settings are organized into logical groups for better management and organization

Common Integration Scenarios:Patterns:

  • Bulk device configuration during deployment
  • Monitoring and auditing device settings
Automated configuration updates based on devicenetwork roles or locationspolicies ConfigurationDevice backupparameter validation and restorecompliance operations Compliance monitoring and remediation Integration with external configuration management systemschecking

TheThese APIendpoints supportswork bothtogether to provide a complete updatesdevice (PUT)configuration lifecycle, from initial setup through ongoing management and partial modifications (PATCH), with built-in change tracking and pending status monitoring to ensure configuration changes are properly synchronized with physical devices.updates.

Endpoints

GET /inventory_device_name_setting/

Description: Retrieves a paginated list of configuration settings for devices,a filteredspecified by device name and optionally by parameter characteristics.device. This endpoint is essential for auditingviewing current device configurations, bulkauditing operations,settings, and synchronizationpreparing processes.for configuration updates. It supports extensive filtering capabilities to narrow down results based on parameter characteristics.

Use Cases:

  • Audit all configuration settings for a specific device
Exportcurrent device configurations for backup or compliance reportingchecking SyncRetrieve configurationsspecific betweenparameter environmentsvalues before making configuration changes Monitor pending configuration changes across devices FilterExport settingsdevice by parameter typesconfigurations for bulkbackup operationsor migration purposes

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_setting/?parent__name=router-main-office01&parameter__name=hostnameip_address&limit=50pending=false

Parameters:

Parameter Type In Required Description
parent__name string query Yes The exact name of the device whose settings you want to retrieve settings for
parameter_id string query No Filter by specific parameter ID to retrieve a particular setting
parameter__variable_name string query No Filter settings by parameterthe parameter's variable name (e.g.,technical 'wifi_ssid', 'admin_password')identifier)
parameter__name string query No Filter settings by human-readablethe parameterparameter's display name (human-readable)
parameter__short_name string query No Filter settings by parameterthe shortparameter's name/slugabbreviated name
limit integer query No Number of results to return per page (default:default 20)varies, typically 20-100)
offset integer query No Starting index for pagination (default:use 0)with limit for page navigation)
pending boolean query No Filter to show only settings with pending orchanges applied settings(true/false)

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_name_setting/?parent__name=router-branch-001switch-main-floor&parameter__variable_name=wifi_enabledparameter__name=vlan&limit=25"50" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 15,125,
  "next": "https://control.zequenze.com/api/v1/inventory_device_name_setting/?limit=2550&offset=2550&parent__name=router-branch-001"switch-main-floor",
  "previous": null,
  "results": [
    {
      "id": 12847,1001,
      "parent_id": "dev_001"dev_12345",
      "parent__name": "router-branch-001"switch-main-floor",
      "parameter": {
        "id": 45,
        "name": "WiFiVLAN Network Enabled"Configuration",
        "short_name": "wifi-enabled"vlan-config",
        "variable_name": "wifi_enabled"vlan_settings",
        "type": "boolean"table",
        "position": 10,
        "required": true,
        "read_only": false,
        "metric": false,
        "group": {
          "id": 5,
          "name": "WirelessNetwork Configuration",
          "service": "networking",
          "discovery_group": "wireless",
          "title": "WiFi Settings"
        }
      },
      "value": "true"100,200,300",
      "extra": false,
      "extra_value": null,
      "created": "2024-01-15T09:15T08:30:00Z",
      "last_change": "2024-01-20T14:22:00Z"33Z",
      "pending": false
    },
    {
      "id": 12848,1002,
      "parent_id": "dev_001"dev_12345",
      "parent__name": "router-branch-001"switch-main-floor",
      "parameter": {
        "id": 46,
        "name": "NetworkManagement SSID"IP Address",
        "short_name": "ssid"mgmt-ip",
        "variable_name": "wifi_ssid"management_ip",
        "type": "string",
        "position": 15,5,
        "required": true,
        "read_only": false,
        "metric": false,true,
        "group": {
          "id": 5,
          "name": "WirelessNetwork Configuration",
          "service": "networking",
          "discovery_group": "wireless",
          "title": "WiFi Settings"
        }
      },
      "value": "BranchOffice-WiFi"192.168.1.100",
      "extra": false,
      "extra_value": null,
      "created": "2024-01-15T09:15T08:30:00Z",
      "last_change": "2024-01-18T11:45:00Z"18T09:15:22Z",
      "pending": true
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns paginated list of device settings with pagination metadata
400 Bad Request - Missing required parent__name parameter or invalid filter values
401 Unauthorized - Invalid or missing APIauthentication token
404 Not Found - Device with specified name does not exist

PUT /inventory_device_name_setting/{parent__name}/

Description: Performs a complete update of device settings,settings replacingfor the specified device. This endpoint replaces all configurableexisting parameterssettings with the provided values.configuration Thisdata. endpointUse is idealthis for full configurationdevice deployments,reconfiguration or when you need to ensure the device provisioning,has andexactly configurationthe restorationsettings scenarios.you specify, removing any not included in the request.

Use Cases:

  • DeployComplete completedevice reconfiguration during maintenance windows
Standardizing device configurations duringacross initialsimilar setuphardware RestoreRestoring device configurationssettings from a known good backup StandardizeBulk configurationsconfiguration acrossdeployment for new device groups Reset device configurations to known-good states Migrate configurations between devicesinstallations

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_setting/router-branch-001/firewall-dmz-01/

Parameters:

Parameter Type In Required Description
parent__name string path Yes The exact name of the device to update settings(must formatch existing device)
data object body Yes Complete deviceconfiguration configurationdata object containing all parameterdevice valuessettings

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_name_setting/router-branch-001/firewall-dmz-01/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wifi_enabled"settings": [
      {
        "parameter_id": 10,
        "value": "true"192.168.100.1"
      },
      {
        "wifi_ssid"parameter_id": 11,
        "value": "BranchOffice-Secure",enabled"
      "admin_timeout":}
    "1800",
    "backup_enabled": "true",
    "log_level": "info"]
  }'

Example Response:

{
  "id": 12847,2001,
  "parent_id": "dev_001"dev_67890",
  "parent__name": "router-branch-001"firewall-dmz-01",
  "parameter": {
    "id": 45,10,
    "name": "WiFiExternal NetworkInterface Enabled"IP",
    "short_name": "wifi-enabled"ext-ip",
    "variable_name": "wifi_enabled"external_interface_ip",
    "type": "boolean"string",
    "position": 10,1,
    "required": true,
    "read_only": false,
    "metric": false,true,
    "group": {
      "id": 5,8,
      "name": "WirelessInterface Configuration",
      "service": "networking",null,
      "discovery_group": "wireless",null,
      "title": "WiFiNetwork Settings"Interfaces"
    }
  },
  "value": "true"192.168.100.1",
  "extra": false,
  "extra_value": null,
  "created": "2024-01-15T09:15T08:30:00Z",
  "last_change": "2024-01-22T16:30:00Z"45:12Z",
  "pending": true
}

Response Codes:

Status Description
200 Success - ConfigurationDevice settings updated successfully
400 Bad Request - Invalid configuration data or validationparameter errorsvalues
401 Unauthorized - Invalid or missing APIauthentication token
404 Not Found - Device with specified name does not exist
422 UnprocessableValidation EntityError - Configuration violatesdata devicefails constraintsvalidation rules

PATCH /inventory_device_name_setting/{parent__name}/

Description: Performs a partial update of device settings, modifying only the specified parameters while leaving othersother settings unchanged. This endpoint is perfectideal for targeted configuration changes,changes and incremental updates,updates andwithout automatedaffecting configurationthe adjustments.entire device configuration.

Use Cases:

  • Update specific settingsnetwork parameters without affectingtouching otherssecurity settings
Modify monitoring thresholds while preserving operational configurations Apply configuration changespatches fromor monitoringhotfixes systemsto specific parameters Implement gradualIncremental configuration rolloutschanges Fix specific configuration issues Updateduring device settings based on external triggersoptimization

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_setting/router-branch-001/office/

Parameters:

Parameter Type In Required Description
parent__name string path Yes The exact name of the device to partially update settings for
data object body Yes Partial configuration objectdata containing only the parameterssettings to updatemodify

cURL Example:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device_name_setting/router-branch-001/office/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wifi_ssid"parameter_id": 25,
    "value": "NewBranchOffice-WiFi",
    "log_level": "debug"300"
  }'

Example Response:

{
  "id": 12848,3001,
  "parent_id": "dev_001"dev_11223",
  "parent__name": "router-branch-001"office",
  "parameter": {
    "id": 46,25,
    "name": "NetworkOSPF SSID"Hello Interval",
    "short_name": "ssid"ospf-hello",
    "variable_name": "wifi_ssid"ospf_hello_interval",
    "type": "string"positive",
    "position": 15,
    "required": true,false,
    "read_only": false,
    "metric": false,true,
    "group": {
      "id": 5,12,
      "name": "WirelessRouting Protocol Configuration",
      "service": "networking",null,
      "discovery_group": "wireless",null,
      "title": "WiFiDynamic Settings"Routing"
    }
  },
  "value": "NewBranchOffice-WiFi"300",
  "extra": false,
  "extra_value": null,
  "created": "2024-01-15T09:15T08:30:00Z",
  "last_change": "2024-01-22T17:15:00Z"20:45Z",
  "pending": true
}

Response Codes:

Status Description
200 Success - SettingsSpecified settings updated successfully
400 Bad Request - Invalid parameter namesdata or valuesunsupported parameter type
401 Unauthorized - Invalid or missing APIauthentication token
404 Not Found - Device withor specified nameparameter does not exist
422 UnprocessableValidation EntityError - Parameter value fails validation failedconstraints

Common Use Cases

Use Case 1: Device Configuration Audit

Retrieve all configuration settings for amultiple devicedevices to performensure compliance checkingwith ororganizational generate configuration reports.standards. Use the GET endpoint with filtering to focus on specific parameter groups.filters to check critical security and network configurations across your infrastructure.

Use Case 2: Bulk Network Configuration DeploymentUpdate

DeployWhen standardizednetwork configurationspolicies change, use the PATCH endpoint to update specific parameters (like VLAN assignments or routing settings) across multiple devices usingwithout thedisrupting PUTother endpoint in a loop, ensuring all devices in a location or role have identical baseline settings.configurations.

Use Case 3: AutomatedDevice ConfigurationDeployment UpdatesAutomation

MonitorDuring new device metricsinstallations, use the PUT endpoint to apply complete, standardized configurations based on device role and automaticallylocation, adjustensuring configurationconsistent parameterssetup usingacross theyour PATCHnetwork endpoint when thresholds are exceeded or conditions change.infrastructure.

Use Case 4: Configuration BackupChange and RestoreMonitoring

ExportRegularly completepoll device configurationsdevices using the GET endpoint forwith backup,the thenpending=true restorefilter themto usingidentify PUTdevices duringwith disasterpending recoveryconfiguration orchanges, deviceenabling replacementproactive scenarios.change management and deployment tracking.

Use Case 5: GradualParameter-Specific Setting UpdatesTroubleshooting

ImplementWhen phasedinvestigating network issues, use filtered GET requests to examine specific parameter types (like routing or interface settings) across affected devices to identify configuration rollouts by using PATCH to update specific settings across device groups, monitoring the pending status to ensure changes are applied successfully.discrepancies.

Best Practices

  • UseAuthentication Descriptive Device Names: Since these endpoints rely on device names, ensure your naming convention is consistent and meaningful for easier automation and maintenance.

Monitor Pending StatusManagement: Always checkuse secure token storage and implement token refresh mechanisms for long-running applications

Error Handling: Implement comprehensive error handling for all response codes, particularly 422 validation errors which provide detailed parameter-specific feedback Pagination Strategy: For devices with many parameters, use appropriate limit values (50-100) and implement proper pagination to avoid timeout issues Configuration Validation: Before applying changes, retrieve current settings to understand the existing state and validate proposed changes against device capabilities Change Tracking: Monitor the pending field in responses to understand whentrack configuration changesdeployment are waiting to be applied to physical devices. Use the pending parameter to filterstatus and monitorimplement deploymentretry status.mechanisms for failed deployments

ImplementParameter ProperType Error HandlingAwareness: DeviceUnderstand configurationparameter changestypes canbefore failupdating duevalues to- hardwareuse constraints,appropriate networkdata issues,formats orfor validationintegers, rules.booleans, Implement retry logicdates, and propercomplex errortypes handlinglike for production systems.

tables

Leverage Parameter Filtering: Use parameter filtering (by name, variable_name, or type) to focus on specific configuration areas, improving performanceBackup and reducing complexity in large-scale deployments.

Batch Related Changes: When updating multiple related settings, use PATCH with multiple parameters in a single request rather than making individual calls to maintain configuration consistency and reduce API overhead.

Validate Configuration DataRecovery: Always validateretrieve parametercurrent types and values against the parameter definitionsconfigurations before making update requestschanges to avoidenable unnecessaryrollback APIcapabilities errorsin andcase deploymentof failures.

issues
Back to top