Skip to main content

Inventory Device Headless Operation

The Inventory Device Headless Operation API enables automated device management operations without requiring user interface interactions. These endpoints allow you to schedule and execute device operations like parameter retrieval, configuration updates, and object management across your device inventory programmatically.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Headless Operation API provides a powerful interface for managing device operations at scale through automated, programmatic interactions. This API category is designed for system administrators and developers who need to perform bulk device operations, schedule maintenance tasks, or integrate device management into larger automation workflows.

Key Concepts:

  • Headless Operations: Device management tasks that execute without user interface interaction, ideal for automation and batch processing
  • Operation Types: Four primary operations supported - Get (retrieve parameters), Set (update configurations), Add Object (create new device objects), and Delete Object (remove device objects)
  • Variable Management: Flexible parameter system supporting different data types (integer, boolean, string) for device configuration
  • Transaction Tracking: Each operation is assigned a unique ID for monitoring and status tracking

Common Integration Scenarios:

  • Automated device provisioning and configuration management
  • Scheduled maintenance operations across device fleets
  • Real-time device parameter monitoring and alerting
  • Bulk configuration updates during system migrations
  • Integration with third-party network management systems

Endpoints

GET /inventory_device_headless_operation/

Description: Retrieves a list of scheduled or completed device operations. This endpoint allows you to monitor the status of headless operations, track their progress, and retrieve operation results. You can filter by specific operation IDs or request real-time device status updates.

Use Cases:

  • Monitor the progress of bulk device configuration updates
  • Retrieve results from scheduled device parameter collection tasks
  • Track the status of automated device provisioning operations
  • Audit historical device management activities

Full URL Example:

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

Parameters:

Parameter Type In Required Description
id string query No ID of the scheduled transaction to retrieve specific operation details
update_status boolean query No When true, uses configured helpers to refresh device status before returning information

cURL Example:

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

Example Response:

[
  {
    "id": 12345,
    "operation": "get",
    "variables": [
      {
        "variable_name": "Device.ManagementServer.PeriodicInformInterval"
      },
      {
        "variable_name": "Device.WiFi.SSID.2.Stats.BytesReceived"
      }
    ]
  },
  {
    "id": 12346,
    "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 array of operation objects
401 Unauthorized - Invalid or missing API token
404 Not Found - Specified operation ID does not exist

POST /inventory_device_headless_operation/

Description: Creates a new headless device operation to be executed on target devices. This endpoint allows you to schedule device management tasks such as parameter retrieval, configuration updates, or object management operations. The operation will be queued for execution and can be monitored using the GET endpoint.

Use Cases:

  • Schedule bulk configuration updates across multiple devices
  • Initiate automated device parameter collection for monitoring
  • Create object management operations for device provisioning
  • Set up recurring device maintenance tasks

Full URL Example:

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

Parameters:

Parameter Type In Required Description
data string body Yes JSON payload containing the operation details including device ID, operation type, and variables

cURL Example:

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

Example Request Body (Get Operation):

{
  "id": 67890,
  "operation": "get",
  "variables": [
    {
      "variable_name": "Device.ManagementServer.PeriodicInformInterval"
    },
    {
      "variable_name": "Device.WiFi.SSID.1.BSSID"
    }
  ]
}

Example Request Body (Set Operation):

{
  "id": 67890,
  "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:

{
  "id": 67890,
  "operation": "set",
  "variables": [
    {
      "variable_name": "Device.ManagementServer.PeriodicInformInterval",
      "value": "300",
      "value_type": "integer"
    },
    {
      "variable_name": "Device.ManagementServer.PeriodicInformEnable",
      "value": "true",
      "value_type": "boolean"
    }
  ]
}

Response Codes:

Status Description
201 Created - Operation successfully scheduled
400 Bad Request - Invalid operation data or parameters
401 Unauthorized - Invalid or missing API token
422 Unprocessable Entity - Valid JSON but invalid operation parameters

Common Use Cases

Use Case 1: Bulk Device Configuration Update

Schedule configuration changes across multiple devices by creating set operations for each device. Monitor progress using the GET endpoint to track completion status and identify any failed operations.

Use Case 2: Automated Device Monitoring

Create recurring get operations to collect device parameters for monitoring dashboards. Use the update_status parameter to ensure real-time data collection for critical metrics.

Use Case 3: Device Provisioning Workflow

Combine add.obj operations to create new device objects during automated provisioning, followed by set operations to configure initial parameters and get operations to verify successful deployment.

Use Case 4: Network Maintenance Automation

Schedule device parameter collection before maintenance windows, perform configuration updates, and validate changes afterward using a combination of get and set operations.

Use Case 5: Compliance Auditing

Use get operations to periodically collect device configuration parameters and compare against compliance baselines, automatically generating reports of configuration drift.

Best Practices

  • Operation Sequencing: When performing multiple operations on the same device, allow sufficient time between operations to ensure proper execution and avoid conflicts
  • Error Handling: Always check operation status using the GET endpoint before assuming success, especially for critical configuration changes
  • Batch Processing: Group related operations by device or operation type to optimize execution efficiency and simplify monitoring
  • Variable Validation: Verify variable names and data types before creating operations to prevent execution failures
  • Status Monitoring: Use the update_status parameter judiciously as it may impact API response times for large device inventories
  • Transaction Logging: Store operation IDs for audit trails and troubleshooting purposes
  • Rate Limiting: Implement appropriate delays between API calls to respect system limits and ensure reliable operation execution
Back to top