Inventory Device Headless Operation

ManageThe headlessInventory operationsDevice Headless Operation API provides endpoints for inventory devices, including schedulingmanaging and monitoring automated device tasks.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/

RetrieveDescription: Retrieves a list of scheduled headless operations for inventory devices. OptionallyThis endpoint allows you to monitor the status of automated tasks, filter by operationspecific IDtransaction orIDs, 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	UseWhen true, uses configured helpers to updaterefresh device status from the actual devices before returning thedata. informationThis 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)

ExamplecURL Request:Example:

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

Example Response:

{
  "count": 3,45,
  "next": "https://control.zequenze.com/api/v1/inventory_device_headless_operation/?limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "id": "op_12345",
      "device_id": "dev_67890"12345",
      "operation_type": "firmware_update",
      "device_id": "DEV-001",
      "device_name": "Production Router A",
      "device_serial": "RT-789-XYZ",
      "status": "pending"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:15:00Z",
      "parameters": {
        "firmware_version": "2.1.3",
        "auto_reboot": true
      }
    },
    {
      "id": "op_12346",
      "device_id": "dev_67891",
      "operation_type": "configuration_sync",
      "status": "completed",
      "scheduled_at": "2024-01-15T08:00:00Z",
      "created_at": "2024-01-15T07:45:00Z",
      "updated_at": "2024-01-15T08:15:00Z",
      "parameters": {
        "config_template": "default_template"
      }32:18Z"
    }
  ]
}

Response Codes:

Status	Description
200	SuccessfullySuccess retrieved- Returns the list of headless operations
401	Unauthorized - Invalid or missing BearerAPI 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/

ScheduleDescription: Creates and schedules a new headless operation for an inventory device.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 automaticallyaccording atto theyour specifiedscheduling time.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 detailsconfiguration, device targets, scheduling parameters, and operation-specific settings

ExampleRequest Request:Body Structure:

POST /api/v1/inventory_device_headless_operation/
Content-Type: application/json

{
  "device_id": "dev_67892",
  "operation_type": "backup_configuration"firmware_update",
  "device_ids": ["DEV-001", "DEV-002", "DEV-003"],
  "scheduled_at": "2024-01-16T02:00:00Z",
  "parameters"operation_data": {
    "backup_location"firmware_version": "s3://backups/devices/"2.5.0",
    "compression"create_backup": true,
    "retention_days"rollback_on_failure": true,
    "timeout_minutes": 30
  },
  "priority"notification_settings": {
    "email_on_completion": true,
    "email_on_failure": true,
    "webhook_url": "normal"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": "op_12347",
  "device_id": "dev_67892"12347",
  "operation_type": "backup_configuration"config_sync",
  "device_count": 1,
  "status": "scheduled",
  "scheduled_at": "2024-01-16T02: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",
  "updated_at"created_by": "2024-01-15T14:30:00Z",
  "parameters": {
    "backup_location": "s3://backups/devices/",
    "compression": true,
    "retention_days": 30
  },
  "priority": "normal"api_user_12345"
}

Response Codes:

Status	Description
201	Created - Operation successfully scheduled
400	Bad Request - Invalid parametersoperation data or malformed JSON
401	Unauthorized - Invalid or missing BearerAPI token
403	Forbidden - Insufficient permissions to schedule operations
404409	Not FoundConflict - SpecifiedScheduling deviceconflict doeswith notexisting existoperations

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

• StatusBatch UpdatesOperations Wisely: UseGroup therelated update_status=truedevices parameterin whensingle youoperations needrather real-timethan creating individual operations for each device statusto information,reduce butAPI beoverhead awareand thisimprove mayscheduling increaseefficiency.

  response time

• SchedulingUse Maintenance Windows: Schedule operations during maintenancelow-traffic windowsperiods to minimize impactservice onimpact. deviceConsider performancetime 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 the operation status after creation and implement retry logic for failed operationsoperations. Monitor for timeout scenarios and have rollback procedures ready.

FilteringLeverage Webhooks: UseConfigure thewebhook idnotifications parameterfor operation completion instead of frequent polling to trackreduce specificAPI operationsload orand implementimprove pollingreal-time forresponsiveness.

status updates

JSONPlan Formattingfor Concurrency: EnsureBe theaware dataof parameterdevice containscapacity properlylimits escaped JSON when creating operations

Time Zones: All timestamps should be provided in UTC format (ISO 8601) toand avoid scheduling conflictsconflicting 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.

---