Inventory Device Headless Operation

The Inventory Device Headless Operation API provides endpoints for managing and monitoring automated device operations that run without user interaction. These endpoints allow you to schedule, retrieve, and track the status of headless operations on inventory devices, making them ideal for automated maintenance, bulk updates, and monitoring 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 Headless Operation API enables you to manage automated operations on devices in your inventory system. Headless operations are background tasks that execute without requiring direct user interaction, such as firmware updates, configuration synchronization, status checks, or scheduled maintenance routines.

Key Concepts:

Headless Operations: Automated tasks that run on devices without user interface interaction
Scheduled Transactions: Operations that are queued and executed at specific times or intervals
Status Updates: Real-time monitoring of device states and operation progress
Device Inventory Integration: Direct connection to your managed device inventory

Common Integration Patterns:

Schedule bulk operations across multiple devices
Monitor device health through automated status checks
Implement maintenance workflows with automatic execution
Track operation history and results for compliance reporting

These endpoints work together to provide a complete headless operation management system - use the GET endpoint to monitor existing operations and the POST endpoint to schedule new automated tasks.

Endpoints

GET /inventory_device_headless_operation/

Description: Retrieves a list of scheduled headless operations for inventory devices. This endpoint allows you to monitor the status of automated tasks, filter by specific transaction IDs, and optionally update device status information before returning results. Perfect for dashboards, monitoring systems, and operation tracking workflows.

Use Cases:

Monitor the progress of scheduled firmware updates across device fleets
Check the status of automated configuration synchronization tasks
Retrieve operation history for compliance and audit reporting
Build monitoring dashboards showing real-time headless operation status

Full URL Example:

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

Parameters:

Parameter	Type	In	Required	Description
id	string	query	No	ID of the specific scheduled transaction to retrieve. Use this to get details about a particular headless operation
update_status	boolean	query	No	When true, uses configured helpers to refresh device status from the actual devices before returning data. This ensures real-time accuracy but may increase response time
limit	integer	query	No	Number of results to return per page (default: 20, max: 100)
offset	integer	query	No	Starting point for pagination (default: 0)

cURL Example:

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

Example Response:

{
  "count": 45,
  "next": "https://control.zequenze.com/api/v1/inventory_device_headless_operation/?limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "id": "12345",
      "operation_type": "firmware_update",
      "device_id": "DEV-001",
      "device_name": "Production Router A",
      "device_serial": "RT-789-XYZ",
      "status": "in_progress",
      "scheduled_at": "2024-01-15T10:00:00Z",
      "started_at": "2024-01-15T10:00:15Z",
      "completed_at": null,
      "progress_percentage": 65,
      "operation_data": {
        "firmware_version": "2.4.1",
        "backup_created": true,
        "estimated_duration": "00:15:00"
      },
      "created_at": "2024-01-15T09:45:00Z",
      "updated_at": "2024-01-15T10:08:30Z"
    },
    {
      "id": "12346",
      "operation_type": "config_sync",
      "device_id": "DEV-002",
      "device_name": "Backup Switch B",
      "device_serial": "SW-456-ABC",
      "status": "completed",
      "scheduled_at": "2024-01-15T09:30:00Z",
      "started_at": "2024-01-15T09:30:05Z",
      "completed_at": "2024-01-15T09:32:18Z",
      "progress_percentage": 100,
      "operation_data": {
        "config_changes": 3,
        "backup_created": true,
        "sync_source": "master_template"
      },
      "created_at": "2024-01-15T09:15:00Z",
      "updated_at": "2024-01-15T09:32:18Z"
    }
  ]
}

Response Codes:

Status	Description
200	Success - Returns the list of headless operations
401	Unauthorized - Invalid or missing API token
403	Forbidden - Insufficient permissions to access operation data
500	Internal Server Error - Issue with status update helpers or database

POST /inventory_device_headless_operation/

Description: Creates and schedules a new headless operation for inventory devices. This endpoint allows you to automate tasks such as firmware updates, configuration changes, or maintenance routines that need to run without user interaction. The operation will be queued and executed according to your scheduling parameters.

Use Cases:

Schedule firmware updates for device fleets during maintenance windows
Automate configuration synchronization across multiple devices
Set up recurring health checks and diagnostic operations
Queue bulk operations for off-hours execution to minimize service impact

Full URL Example:

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

Parameters:

Parameter	Type	In	Required	Description
data	string	body	Yes	JSON string containing the operation configuration, device targets, scheduling parameters, and operation-specific settings

Request Body Structure:

{
  "operation_type": "firmware_update",
  "device_ids": ["DEV-001", "DEV-002", "DEV-003"],
  "scheduled_at": "2024-01-16T02:00:00Z",
  "operation_data": {
    "firmware_version": "2.5.0",
    "create_backup": true,
    "rollback_on_failure": true,
    "timeout_minutes": 30
  },
  "notification_settings": {
    "email_on_completion": true,
    "email_on_failure": true,
    "webhook_url": "https://your-system.com/webhooks/operation-status"
  }
}

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 '{
    "operation_type": "config_sync",
    "device_ids": ["DEV-005"],
    "scheduled_at": "2024-01-16T01:00:00Z",
    "operation_data": {
      "config_template": "standard_router_config",
      "create_backup": true,
      "validate_before_apply": true
    }
  }'

Example Response:

{
  "id": "12347",
  "operation_type": "config_sync",
  "device_count": 1,
  "status": "scheduled",
  "scheduled_at": "2024-01-16T01:00:00Z",
  "estimated_duration": "00:05:00",
  "operation_data": {
    "config_template": "standard_router_config",
    "create_backup": true,
    "validate_before_apply": true
  },
  "target_devices": [
    {
      "device_id": "DEV-005",
      "device_name": "Edge Router C",
      "device_serial": "ER-123-DEF",
      "device_status": "online"
    }
  ],
  "created_at": "2024-01-15T14:30:00Z",
  "created_by": "api_user_12345"
}

Response Codes:

Status	Description
201	Created - Operation successfully scheduled
400	Bad Request - Invalid operation data or malformed JSON
401	Unauthorized - Invalid or missing API token
403	Forbidden - Insufficient permissions to schedule operations
409	Conflict - Scheduling conflict with existing operations
422	Unprocessable Entity - Valid JSON but invalid operation parameters

Common Use Cases

Use Case 1: Monitoring Fleet-Wide Firmware Updates

Use the GET endpoint with update_status=true to build a real-time dashboard showing the progress of firmware updates across your entire device fleet. Filter by operation type and use pagination to handle large inventories efficiently.

Use Case 2: Automated Maintenance Windows

Schedule multiple headless operations using the POST endpoint for your regular maintenance windows. Queue configuration backups, firmware updates, and health checks to run automatically during off-hours, reducing manual intervention and service disruptions.

Use Case 3: Compliance and Audit Reporting

Retrieve historical operation data using the GET endpoint to generate compliance reports showing when devices were updated, what changes were made, and whether operations completed successfully. Filter by date ranges and device groups as needed.

Use Case 4: Proactive Device Management

Create recurring headless operations for device health checks and preventive maintenance. Use the POST endpoint to schedule regular configuration validation, performance monitoring, and automated remediation tasks.

Use Case 5: Emergency Response Automation

When security patches or critical updates need to be deployed rapidly, use the POST endpoint to schedule immediate headless operations across affected devices, then monitor progress with the GET endpoint to ensure timely completion.

Best Practices

Batch Operations Wisely: Group related devices in single operations rather than creating individual operations for each device to reduce API overhead and improve scheduling efficiency.
Use Maintenance Windows: Schedule operations during low-traffic periods to minimize service impact. Consider time zones when managing geographically distributed devices.
Enable Status Updates Judiciously: The update_status parameter provides real-time accuracy but increases response time. Use it for critical monitoring but avoid it for frequent polling scenarios.
Implement Proper Error Handling: Always check operation status and implement retry logic for failed operations. Monitor for timeout scenarios and have rollback procedures ready.
Leverage Webhooks: Configure webhook notifications for operation completion instead of frequent polling to reduce API load and improve real-time responsiveness.
Plan for Concurrency: Be aware of device capacity limits and avoid scheduling conflicting operations on the same devices simultaneously.
Backup Before Operations: Always enable backup creation in operation_data for critical changes to ensure quick recovery if operations fail or need to be reversed.