Skip to main content

Inventory Device Serial Headless Operation

The Inventory Device Serial Headless Operation endpoints enable programmatic control of device operations through serial number identification. These endpoints allow you to schedule and retrieve device operations like getting parameters, setting configurations, and managing objects without manual intervention, making them ideal for automated device management 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 Serial Headless Operation API provides a powerful interface for managing device operations programmatically using device serial numbers. This API category is designed for automated device management scenarios where you need to perform bulk operations or scheduled maintenance tasks across multiple devices without manual intervention.

Key Capabilities:

  • Device Parameter Management: Get and set device configuration parameters using TR-069/CWMP variable paths
  • Object Operations: Add or delete configuration objects on devices
  • Bulk Operations: Execute the same operation across multiple devices simultaneously
  • Scheduled Transactions: Track and monitor operation status through unique transaction IDs
  • Status Updates: Real-time device status updates using configured helpers

Common Integration Scenarios:

  • Automated device provisioning and configuration management
  • Scheduled maintenance tasks like firmware updates or parameter adjustments
  • Bulk configuration changes across device fleets
  • Monitoring and reporting on device parameter values
  • Remote troubleshooting and diagnostics

The API uses TR-069/CWMP data model variable paths (e.g., Device.ManagementServer.PeriodicInformInterval) to identify specific device parameters and supports multiple data types including integers, booleans, and strings for set operations.

Endpoints

GET /inventory_device_serial_headless_operation/

Description: Retrieves scheduled headless operations for devices, allowing you to monitor operation status and results. This endpoint supports filtering by transaction ID and can optionally update device status before returning information.

Use Cases:

  • Monitor the progress and results of previously scheduled device operations
  • Retrieve operation details for specific transactions using the ID filter
  • Get updated device status information along with operation results
  • Audit and track device management activities

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_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 the information

cURL Example:

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

Example Response:

[
  {
    "serial_number": "SN123456789",
    "operation": "get",
    "variables": [
      {"variable_name": "Device.ManagementServer.PeriodicInformInterval"},
      {"variable_name": "Device.WiFi.SSID.1.SSID"}
    ]
  },
  {
    "serial_number": "SN987654321", 
    "operation": "set",
    "variables": [
      {
        "variable_name": "Device.ManagementServer.PeriodicInformInterval",
        "value": "300",
        "value_type": "integer"
      }
    ]
  }
]

Response Codes:

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

POST /inventory_device_serial_headless_operation/

Description: Creates a new headless operation for a device identified by serial number. This endpoint schedules device operations like parameter retrieval, configuration changes, or object management that will be executed automatically.

Use Cases:

  • Schedule configuration changes across multiple devices
  • Retrieve specific parameter values for monitoring or reporting
  • Add new configuration objects to devices (e.g., new WiFi SSIDs)
  • Remove obsolete configuration objects from devices
  • Automate device provisioning workflows

Full URL Example:

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

Request Body: The request body should contain operation details in JSON format.

cURL Example - Get Operation:

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

cURL Example - Set Operation:

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

Request Schema:

Field Type Required Description
serial_number string Yes Serial number of the target device
operation string Yes Operation type: get, set, add.obj, or del.obj
variables array No Array of variable objects with operation-specific properties

Variable Object Schema:

For Get/Add Object/Delete Object operations:

Field Type Required Description
variable_name string Yes TR-069/CWMP variable path

For Set operations:

Field Type Required Description
variable_name string Yes TR-069/CWMP variable path
value string Yes Value to set (as string)
value_type string Yes Data type: integer, boolean, or string

Example Response:

{
  "serial_number": "SN123456789",
  "operation": "set",
  "variables": [
    {
      "variable_name": "Device.ManagementServer.PeriodicInformInterval",
      "value": "300",
      "value_type": "integer"
    }
  ]
}

Response Codes:

Status Description
201 Created - Operation successfully scheduled
400 Bad Request - Invalid request data or parameters
401 Unauthorized - Invalid or missing API token
404 Not Found - Device with specified serial number not found

Common Use Cases

Use Case 1: Bulk Configuration Update

Schedule configuration changes across multiple devices by creating separate operations for each device serial number. Monitor progress using the GET endpoint with transaction IDs.

Use Case 2: Device Health Monitoring

Regularly retrieve key device parameters like uptime, signal strength, and error counters by scheduling get operations for specific variables across your device fleet.

Use Case 3: Automated Provisioning

Set up new devices by scheduling a series of set operations to configure network settings, management parameters, and service configurations based on device serial numbers.

Use Case 4: WiFi Network Management

Add new WiFi SSIDs to devices using add.obj operations, or remove obsolete networks using del.obj operations, targeting specific TR-069 WiFi object paths.

Use Case 5: Compliance Reporting

Schedule regular get operations to retrieve security and configuration parameters needed for compliance reporting, using the update_status flag to ensure current data.

Best Practices

  • Transaction Tracking: Always store the transaction IDs returned from POST operations to monitor status and results using the GET endpoint
  • Error Handling: Implement retry logic for failed operations and check device connectivity before scheduling critical configuration changes
  • Batch Processing: When updating multiple devices, implement proper rate limiting to avoid overwhelming the API or target devices
  • Variable Path Validation: Verify TR-069/CWMP variable paths are correct for your device models before scheduling operations
  • Data Type Consistency: Ensure value_type matches the actual parameter type expected by the device (integer, boolean, string)
  • Status Updates: Use the update_status parameter judiciously as it may add latency to GET requests but ensures current device information
  • Security: Never include sensitive credentials or keys in variable values; use secure provisioning methods for authentication parameters
Back to top