Inventory Device Name Headless Operation

The Inventory Device Name Headless Operation API provides endpoints for managing and monitoring automated device operations that run without direct user interface interaction. These endpoints allow you to retrieve information about scheduled device operations and create new headless operations for inventory 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 Name Headless Operation API is designed for automated device management scenarios where operations need to run independently without user intervention. This API category is particularly useful for:

Automated Inventory Updates: Running scheduled operations to sync device information, update statuses, and maintain inventory accuracy
Background Device Monitoring: Executing headless operations that continuously monitor device health, connectivity, and performance metrics
Batch Processing: Creating and managing bulk operations that process multiple devices without requiring manual oversight
Integration Workflows: Enabling third-party systems to trigger and monitor device operations programmatically

These endpoints work together to provide complete lifecycle management of headless operations - from creation and scheduling to monitoring and status updates. The API supports both real-time status updates and background processing, making it ideal for enterprise-scale device management scenarios.

Key concepts to understand:

Headless Operations: Automated tasks that run without user interface interaction
Scheduled Transactions: Time-based operations that execute according to predefined schedules
Status Updates: Real-time synchronization of device states using configured helpers
Operation Lifecycle: The complete process from operation creation to completion and monitoring

Endpoints

GET /inventory_device_name_headless_operation/

Description: Retrieves a list of scheduled headless operations for inventory devices. This endpoint allows you to monitor the status of automated operations, filter by specific transaction IDs, and optionally trigger real-time status updates using configured helpers before returning the data.

Use Cases:

Monitor the progress and status of scheduled device inventory operations
Retrieve specific operation details using transaction ID filtering
Get real-time device status updates before processing operation results
Generate reports on completed and pending headless operations

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_headless_operation/?id=txn_12345&update_status=true

Parameters:

Parameter	Type	In	Required	Description
id	string	query	No	ID of the scheduled transaction to filter results. Use this to retrieve specific operation details
update_status	boolean	query	No	When set to true, triggers configured helpers to update device status before returning information, ensuring real-time accuracy

cURL Example:

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

Example Response:

{
  "count": 15,
  "next": "https://control.zequenze.com/api/v1/inventory_device_name_headless_operation/?limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "id": "txn_12345",
      "device_name": "WS-001-LAB-PC",
      "operation_type": "inventory_sync",
      "status": "running",
      "scheduled_at": "2024-01-15T10:30:00Z",
      "started_at": "2024-01-15T10:30:15Z",
      "progress": 75,
      "device_details": {
        "serial_number": "SN123456789",
        "model": "OptiPlex 7090",
        "manufacturer": "Dell",
        "location": "Building A, Floor 2",
        "last_seen": "2024-01-15T10:45:30Z"
      },
      "operation_details": {
        "total_tasks": 8,
        "completed_tasks": 6,
        "current_task": "updating_software_inventory"
      }
    },
    {
      "id": "txn_12346",
      "device_name": "SRV-002-DB-01",
      "operation_type": "health_check",
      "status": "completed",
      "scheduled_at": "2024-01-15T09:00:00Z",
      "started_at": "2024-01-15T09:00:05Z",
      "completed_at": "2024-01-15T09:15:22Z",
      "progress": 100,
      "device_details": {
        "serial_number": "SN987654321",
        "model": "PowerEdge R740",
        "manufacturer": "Dell",
        "location": "Data Center Rack 15",
        "last_seen": "2024-01-15T09:15:22Z"
      },
      "result": {
        "status": "healthy",
        "checks_passed": 12,
        "checks_failed": 0,
        "warnings": 1
      }
    }
  ]
}

Response Codes:

Status	Description
200	Success - Returns list of headless operations with current status
401	Unauthorized - Invalid or missing API token
403	Forbidden - Insufficient permissions to access operation data
500	Internal Server Error - Error updating device status or retrieving operations

POST /inventory_device_name_headless_operation/

Description: Creates a new headless operation for inventory device management. This endpoint allows you to schedule automated tasks such as inventory synchronization, device health checks, or batch updates that will run without user intervention. The operation data should be provided in the request body.

Use Cases:

Schedule automated inventory synchronization for specific devices or device groups
Create background health monitoring operations for critical infrastructure
Initiate bulk device updates during maintenance windows
Set up recurring device compliance checks and reporting

Full URL Example:

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

Parameters:

Parameter	Type	In	Required	Description
data	string	body	Yes	JSON string containing the operation configuration including device targets, operation type, schedule, and parameters

cURL Example:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_name_headless_operation/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation_type": "inventory_sync",
    "device_targets": ["WS-001-LAB-PC", "WS-002-LAB-PC"],
    "schedule": {
      "type": "immediate"
    },
    "parameters": {
      "sync_software": true,
      "sync_hardware": true,
      "update_location": false,
      "timeout_minutes": 30
    },
    "notification": {
      "on_completion": true,
      "on_failure": true,
      "email": "admin@company.com"
    }
  }'

Example Request Body:

{
  "operation_type": "health_check",
  "device_targets": ["SRV-001-DB-01", "SRV-002-DB-01"],
  "schedule": {
    "type": "recurring",
    "cron": "0 2 * * 1",
    "timezone": "UTC"
  },
  "parameters": {
    "check_disk_space": true,
    "check_memory_usage": true,
    "check_network_connectivity": true,
    "check_running_services": true,
    "disk_threshold_percent": 85,
    "memory_threshold_percent": 90,
    "timeout_minutes": 15
  },
  "notification": {
    "on_completion": false,
    "on_failure": true,
    "webhook_url": "https://monitoring.company.com/webhook/device-alerts"
  },
  "retry_policy": {
    "max_attempts": 3,
    "retry_delay_minutes": 5
  }
}

Example Response:

{
  "id": "txn_12347",
  "status": "scheduled",
  "operation_type": "health_check",
  "device_targets": ["SRV-001-DB-01", "SRV-002-DB-01"],
  "created_at": "2024-01-15T11:20:00Z",
  "scheduled_for": "2024-01-22T02:00:00Z",
  "estimated_duration_minutes": 30,
  "parameters": {
    "check_disk_space": true,
    "check_memory_usage": true,
    "check_network_connectivity": true,
    "check_running_services": true,
    "disk_threshold_percent": 85,
    "memory_threshold_percent": 90,
    "timeout_minutes": 15
  },
  "schedule": {
    "type": "recurring",
    "cron": "0 2 * * 1",
    "timezone": "UTC",
    "next_execution": "2024-01-22T02:00:00Z"
  },
  "monitoring_url": "https://control.zequenze.com/api/v1/inventory_device_name_headless_operation/?id=txn_12347"
}

Response Codes:

Status	Description
201	Created - Headless operation successfully scheduled
400	Bad Request - Invalid operation data or missing required parameters
401	Unauthorized - Invalid or missing API token
403	Forbidden - Insufficient permissions to create operations for specified devices
422	Unprocessable Entity - Valid JSON but invalid operation configuration
500	Internal Server Error - Error scheduling the operation

Common Use Cases

Use Case 1: Automated Nightly Inventory Sync

Schedule recurring operations to synchronize device inventory information every night, ensuring accurate asset tracking and compliance reporting. Use POST to create the recurring operation and GET to monitor daily execution status.

Use Case 2: Real-time Operation Monitoring Dashboard

Build a dashboard that polls the GET endpoint with update_status=true to display real-time progress of running operations, allowing IT teams to monitor automation workflows and quickly identify issues.

Use Case 3: Maintenance Window Automation

Create batch operations during scheduled maintenance windows to update device configurations, install software, or perform health checks across multiple devices simultaneously without manual intervention.

Use Case 4: Compliance and Audit Reporting

Set up weekly headless operations to collect device compliance data, security status, and configuration drift information, automatically generating reports for audit and governance purposes.

Use Case 5: Proactive Device Health Monitoring

Implement continuous monitoring by creating recurring health check operations that automatically detect device issues, performance degradation, or connectivity problems before they impact business operations.

Best Practices

Operation Scheduling: Use appropriate scheduling strategies - immediate execution for urgent tasks, recurring schedules for routine maintenance, and maintenance windows for resource-intensive operations.
Error Handling: Always implement retry logic and monitor operation status. Use the GET endpoint with specific transaction IDs to track individual operations and handle failures gracefully.
Performance Optimization: When monitoring multiple operations, use pagination parameters and consider caching results. The update_status parameter should be used judiciously as it triggers real-time device communication.
Security Considerations: Ensure API tokens have appropriate scope limitations. Store operation configurations securely and avoid exposing sensitive device credentials in operation parameters.
Resource Management: Set appropriate timeout values for operations and limit concurrent executions to prevent overwhelming target devices. Monitor system resources during bulk operations.
Notification Strategy: Configure notifications for operation failures but consider using webhooks instead of email for high-frequency operations to avoid spam and improve integration with monitoring systems.