Inventory Device Name Headless Operation

The Inventory Device Name Headless Operation endpoints enable automated management and monitoring of network devices through programmatic operations. These endpoints allow you to perform device operations like getting parameters, setting configurations, adding objects, and deleting objects without manual intervention, making them ideal for bulk device management and automated workflows.

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 Headless Operation API category provides functionality for executing automated operations on network devices in your inventory. These endpoints are designed for scenarios where you need to perform bulk operations across multiple devices or integrate device management into automated workflows.

Key Concepts:

• Headless Operations: Automated device operations that run without user interaction
• Device Variables: TR-069/CWMP parameters that can be retrieved, modified, or managed on devices
• Operation Types: Four main operation types are supported:
  • get: Retrieve parameter values from devices
  • set: Update parameter values on devices
  • add.obj: Create new object instances on devices
  • del.obj: Remove object instances from devices

Common Use Cases:

• Bulk configuration updates across device fleets
• Automated monitoring and status collection
• Scheduled maintenance operations
• Integration with network management systems
• Device provisioning and deprovisioning workflows

The API supports complex variable operations with type validation and provides real-time status updates to help monitor operation progress.

---

Endpoints

GET /inventory_device_name_headless_operation/

Description: Retrieves a list of scheduled or completed headless operations for devices in your inventory. This endpoint allows you to monitor the status of operations, filter by specific transaction IDs, and optionally update device status information before returning results.

Use Cases:

• Monitor the progress of bulk device operations
• Retrieve results from previously executed headless operations
• Check the status of scheduled device maintenance tasks
• Audit device operation history for compliance reporting

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_headless_operation/?id=12345&update_status=true

Parameters:

Parameter	Type	In	Required	Description
id	string	query	No	ID of the scheduled transaction to filter results
update_status	boolean	query	No	Use configured helpers to update device status before returning information

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_name_headless_operation/?update_status=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

[
  {
    "name": "router-branch-01",
    "operation": "get",
    "variables": [
      {
        "variable_name": "Device.ManagementServer.PeriodicInformInterval"
      },
      {
        "variable_name": "Device.WiFi.SSID.1.Stats.BytesReceived"
      }
    ]
  },
  {
    "name": "switch-floor-02",
    "operation": "set",
    "variables": [
      {
        "variable_name": "Device.ManagementServer.PeriodicInformInterval",
        "value": "300",
        "value_type": "integer"
      },
      {
        "variable_name": "Device.ManagementServer.PeriodicInformEnable",
        "value": "1",
        "value_type": "boolean"
      }
    ]
  }
]

Response Codes:

Status	Description
200	Success - Returns list of headless operations
401	Unauthorized - Invalid or missing token
404	Not Found - No operations found for specified criteria

---

POST /inventory_device_name_headless_operation/

Description: Creates a new headless operation for one or more devices in your inventory. This endpoint allows you to schedule automated operations such as parameter retrieval, configuration updates, object creation, or object deletion across your device fleet.

Use Cases:

• Execute bulk configuration changes across multiple devices
• Schedule automated parameter collection for monitoring
• Provision new services by adding object instances
• Clean up unused configurations by removing object instances

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_headless_operation/

Parameters:

Parameter	Type	In	Required	Description
data	string	body	Yes	JSON payload containing operation details

Request Body Schema:

{
  "name": "string (required)",
  "operation": "string (required, one of: get, set, add.obj, del.obj)",
  "variables": [
    {
      "variable_name": "string (required)",
      "value": "string (optional, required for 'set' operations)",
      "value_type": "string (optional, one of: string, integer, boolean)"
    }
  ]
}

cURL Example - Get Operation:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_name_headless_operation/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "router-main-office",
    "operation": "get",
    "variables": [
      {
        "variable_name": "Device.ManagementServer.PeriodicInformInterval"
      },
      {
        "variable_name": "Device.WiFi.SSID.1.Stats.BytesReceived"
      }
    ]
  }'

cURL Example - Set Operation:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_name_headless_operation/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "router-branch-network",
    "operation": "set",
    "variables": [
      {
        "variable_name": "Device.ManagementServer.PeriodicInformInterval",
        "value": "300",
        "value_type": "integer"
      },
      {
        "variable_name": "Device.ManagementServer.PeriodicInformEnable",
        "value": "true",
        "value_type": "boolean"
      }
    ]
  }'

Example Response:

{
  "name": "router-main-office",
  "operation": "get",
  "variables": [
    {
      "variable_name": "Device.ManagementServer.PeriodicInformInterval"
    },
    {
      "variable_name": "Device.WiFi.SSID.1.Stats.BytesReceived"
    }
  ],
  "transaction_id": "op_67890",
  "status": "scheduled",
  "created_at": "2024-01-15T14:30:00Z"
}

Response Codes:

Status	Description
201	Created - Operation successfully scheduled
400	Bad Request - Invalid operation parameters or malformed request
401	Unauthorized - Invalid or missing token
404	Not Found - Specified device not found in inventory

---

Common Use Cases

Use Case 1: Bulk WiFi Configuration Update

Schedule set operations across multiple access points to update WiFi settings like channel, power, or security configurations during maintenance windows.

Use Case 2: Network Health Monitoring

Use get operations to collect statistics and performance metrics from devices on a scheduled basis for network monitoring and reporting dashboards.

Use Case 3: Service Provisioning

Implement add.obj operations to create new service instances (like VLANs, SSIDs, or port configurations) when onboarding new customers or locations.

Use Case 4: Automated Compliance Checking

Regularly execute get operations to verify device configurations meet compliance requirements and generate audit reports.

Use Case 5: Cleanup and Maintenance

Use del.obj operations to remove unused configurations, expired certificates, or decommissioned service instances during routine maintenance.

---

Best Practices

Operation Planning:

• Test operations on a small subset of devices before executing bulk operations
• Use the update_status=true parameter when you need current device information
• Monitor operation results using the GET endpoint with transaction IDs

Variable Management:

• Always specify the correct value_type for set operations to ensure proper parameter validation
• Use fully qualified TR-069 parameter paths for better compatibility across device types
• Validate variable names against your device's data model before executing operations

Error Handling:

• Implement retry logic for operations that may fail due to temporary network issues
• Check device connectivity status before scheduling operations
• Monitor operation status and implement timeout handling for long-running operations

Security Considerations:

• Limit access to headless operation endpoints to authorized automation systems only
• Log all operations for audit trails and troubleshooting
• Use least-privilege principles when granting API access for automated systems

Performance Optimization:

• Batch related operations together when possible to reduce API calls
• Consider device capabilities and network conditions when scheduling operations
• Implement rate limiting in your automation scripts to avoid overwhelming devices

---