Inventory Device Serial Headless Operation

ManageThe headlessInventory 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 serial numbers, including scheduled transactionsstatuses and deviceperform statusinventory updates.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/

RetrieveDescription: Retrieves information about scheduled headless operations fordevice inventory deviceoperations. serialThis numbers.endpoint Optionallyallows updateyou to monitor the status and progress of background tasks, optionally triggering device status updates before returning information.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	UseWhen true, uses configured helpers to updaterefresh device status information before returning the informationresults

ExamplecURL Request:Example:

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

Example Response:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "txn_12345",
      "device_serial": "SN123456789"12345",
      "operation_type": "firmware_update"bulk_serial_sync",
      "status": "scheduled"in_progress",
      "scheduled_time"progress": 65,
      "total_devices": 150,
      "processed_devices": 98,
      "failed_devices": 2,
      "created_at": "2024-01-15T10:30:00Z",
      "created_at"updated_at": "2024-01-14T14:22:15T11:45:30Z",
      "estimated_completion": "2024-01-15T12:15:00Z",
      "device_status"operation_details": {
        "online"device_types": true,
        ["last_seen": "2024-01-15T09:45:00Z"router", "firmware_version"switch", "access_point"],
        "organization_ids": [101, 102],
        "1.2.3"error_summary": {
          "connection_timeouts": 1,
          "authentication_failures": 1
        }
      }
    }
  ]
}

Response Codes:

Status	Description
200	SuccessfullySuccess retrieved- headlessReturns operationsscheduled operation information
401	Unauthorized - Invalid or missing API token
404	TransactionNot Found - Specified operation ID does not foundexist

500 Internal Server Error - Operation status update failed

---

POST /inventory_device_serial_headless_operation/

CreateDescription: Creates a new scheduled headless operation for andevice inventory management. This endpoint queues background tasks for device serial number.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 theoperation configuration including operation detailstype, target devices, and scheduling parameters

ExamplecURL Request: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/jsonjson" \
  -d '{
  "device_serial": "SN123456789",
    "operation_type": "configuration_update"bulk_serial_sync",
    "scheduled_time"target_organizations": [101, 102, 103],
    "device_filters": {
      "types": ["router", "switch"],
      "status": ["active", "pending"]
    },
    "schedule": {
      "execute_at": "2024-01-16T02:00:00Z",
      "parameters"priority": "normal"
    },
    "options": {
      "config_profile"update_firmware_info": "production_v2",true,
      "restart_required"validate_connectivity": truetrue,
      "timeout_minutes": 120
    }
  }'

Example Response:

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

Response Codes:

Status	Description
201	HeadlessCreated operation- Operation successfully createdscheduled
400	Bad Request - Invalid requestoperation dataconfiguration or malformed JSON
401	Unauthorized - Invalid or missing API token
404403	DeviceForbidden serial- numberInsufficient notpermissions foundfor 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 sparinglyjudiciously as it may increaseimpact response timetimes due to real-time device queries Schedulefor operations duringinvolving maintenancemany windows when possible to minimize service disruption Always verify device serial numbers exist in inventory before creating operations Monitor operation status regularly using the GET endpoint with specific transaction IDs Include all required parameters in the data payload when creating operations Consider device timezone and connectivity patterns when scheduling operationsdevices

---