Inventory Device Serial Headless Operation

The Inventory Device Serial Headless Operation endpoints manage automated, scheduled operations for device inventory without user interaction. These endpoints allow you to create and monitor background tasks that update device statuses and perform inventory operations 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 Serial Headless Operation API enables automated management of device inventory operations that run without user interface interaction. This system is designed for scenarios where you need to:

Schedule automated device status updates and inventory synchronization
Monitor long-running inventory operations without blocking user workflows
Integrate device management into automated systems and workflows
Perform bulk operations on device inventory in the background

These endpoints work together to provide a complete headless operation management system. You can create new scheduled operations using the POST endpoint and monitor their progress using the GET endpoint. The operations are designed to handle device serial number tracking, status updates, and inventory management tasks that may take extended time to complete.

Key concepts include scheduled transactions (operations queued for execution), status helpers (automated tools that update device information), and headless processing (operations that run independently of user sessions).

Endpoints

GET /inventory_device_serial_headless_operation/

Description: Retrieves information about scheduled device inventory operations. This endpoint allows you to monitor the status and progress of background tasks, optionally triggering device status updates before returning results.

Use Cases:

Monitor progress of bulk device inventory updates
Check status of scheduled serial number synchronization tasks
Retrieve operation logs for audit and troubleshooting purposes
Trigger device status refresh as part of monitoring workflows

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 specific scheduled transaction to retrieve. If omitted, returns all operations
update_status	boolean	query	No	When true, uses configured helpers to refresh device status information before returning results

cURL Example:

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

Example Response:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "12345",
      "operation_type": "bulk_serial_sync",
      "status": "in_progress",
      "progress": 65,
      "total_devices": 150,
      "processed_devices": 98,
      "failed_devices": 2,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T11:45:30Z",
      "estimated_completion": "2024-01-15T12:15:00Z",
      "operation_details": {
        "device_types": ["router", "switch", "access_point"],
        "organization_ids": [101, 102],
        "error_summary": {
          "connection_timeouts": 1,
          "authentication_failures": 1
        }
      }
    }
  ]
}

Response Codes:

Status	Description
200	Success - Returns scheduled operation information
401	Unauthorized - Invalid or missing API token
404	Not Found - Specified operation ID does not exist
500	Internal Server Error - Operation status update failed

POST /inventory_device_serial_headless_operation/

Description: Creates a new scheduled headless operation for device inventory management. This endpoint queues background tasks for device serial number synchronization, bulk updates, or other inventory operations that should run without user interaction.

Use Cases:

Schedule bulk device serial number synchronization across multiple organizations
Create automated inventory audits that run during off-hours
Queue device status updates for large device populations
Initiate compliance reporting operations for device inventory

Full URL Example:

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

Parameters:

Parameter	Type	In	Required	Description
data	string	body	Yes	JSON string containing operation configuration including operation type, target devices, and scheduling parameters

cURL Example:

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 '{
    "operation_type": "bulk_serial_sync",
    "target_organizations": [101, 102, 103],
    "device_filters": {
      "types": ["router", "switch"],
      "status": ["active", "pending"]
    },
    "schedule": {
      "execute_at": "2024-01-16T02:00:00Z",
      "priority": "normal"
    },
    "options": {
      "update_firmware_info": true,
      "validate_connectivity": true,
      "timeout_minutes": 120
    }
  }'

Example Response:

{
  "id": "67890",
  "operation_type": "bulk_serial_sync",
  "status": "scheduled",
  "created_at": "2024-01-15T14:30:00Z",
  "scheduled_for": "2024-01-16T02:00:00Z",
  "estimated_duration_minutes": 90,
  "target_device_count": 245,
  "operation_config": {
    "organizations": [101, 102, 103],
    "device_types": ["router", "switch"],
    "options": {
      "update_firmware_info": true,
      "validate_connectivity": true,
      "timeout_minutes": 120
    }
  },
  "monitoring_url": "/api/v1/inventory_device_serial_headless_operation/?id=67890"
}

Response Codes:

Status	Description
201	Created - Operation successfully scheduled
400	Bad Request - Invalid operation configuration or malformed JSON
401	Unauthorized - Invalid or missing API token
403	Forbidden - Insufficient permissions for target organizations
422	Unprocessable Entity - Valid JSON but invalid operation parameters

Common Use Cases

Use Case 1: Automated Nightly Inventory Sync

Schedule comprehensive device inventory synchronization to run during maintenance windows. Create operations that update serial numbers, firmware versions, and connectivity status across all managed devices without impacting daytime operations.

Use Case 2: Compliance Audit Preparation

Generate scheduled operations that collect device serial numbers and configuration data needed for compliance reporting. Monitor progress through the GET endpoint and retrieve results when auditors require current inventory information.

Use Case 3: Large Organization Device Management

For organizations managing hundreds or thousands of devices, create bulk operations that update device information across multiple sites and device types. Use the monitoring capabilities to track progress and handle any devices that fail to update.

Use Case 4: Integration with External Systems

Integrate device inventory updates with external asset management, ticketing, or monitoring systems by scheduling operations through the API and monitoring their completion status programmatically.

Use Case 5: Proactive Device Maintenance

Schedule regular operations that check device connectivity and update status information, enabling proactive identification of devices that may need attention before they impact network operations.

Best Practices

Schedule operations during low-usage periods to minimize impact on network performance and device availability
Use appropriate timeout values in operation configuration to balance thoroughness with completion time
Monitor operation progress regularly using the GET endpoint, especially for large-scale operations affecting many devices
Implement proper error handling for failed operations and retry logic for transient network issues
Filter target devices appropriately to avoid unnecessary operations on devices that don't require updates
Consider rate limiting when creating multiple operations to avoid overwhelming the scheduling system
Store operation IDs returned from POST requests for later monitoring and result retrieval
Use the update_status parameter judiciously as it may impact response times for operations involving many devices