Skip to main content

Inventory Device Headless Operation

The Inventory Device Headless Operation API provides endpoints for managing and monitoringenables automated device management operations that run without requiring user interaction.interface interactions. These endpoints allow you to schedule, retrieve,schedule and trackexecute the status of headlessdevice operations onlike inventoryparameter devices,retrieval, making them ideal for automated maintenance, bulkconfiguration updates, and monitoringobject workflows.management across your device inventory 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 Headless Operation API enablesprovides youa powerful interface for managing device operations at scale through automated, programmatic interactions. This API category is designed for system administrators and developers who need to manageperform automatedbulk operationsdevice onoperations, devicesschedule inmaintenance your inventory system. Headless operations are background tasks that execute without requiring direct user interaction, such as firmware updates, configuration synchronization, status checks,tasks, or scheduledintegrate maintenancedevice routines.management into larger automation workflows.

Key Concepts:

  • Headless Operations: AutomatedDevice management tasks that run on devicesexecute without user interface interactioninteraction, ideal for automation and batch processing
  • ScheduledOperation TransactionsTypes: OperationsFour thatprimary areoperations queuedsupported - Get (retrieve parameters), Set (update configurations), Add Object (create new device objects), and executedDelete atObject specific(remove timesdevice or intervalsobjects)
  • StatusVariable UpdatesManagement: Real-timeFlexible monitoringparameter ofsystem supporting different data types (integer, boolean, string) for device states and operation progressconfiguration
  • DeviceTransaction Inventory IntegrationTracking: DirectEach connectionoperation tois yourassigned manageda deviceunique inventoryID for monitoring and status tracking

Common Integration Patterns:Scenarios:

  • ScheduleAutomated bulkdevice provisioning and configuration management
Scheduled maintenance operations across multipledevice devicesfleets MonitorReal-time device healthparameter throughmonitoring automatedand status checksalerting ImplementBulk maintenanceconfiguration workflowsupdates during system migrations Integration with automaticthird-party executionnetwork Trackmanagement operation history and results for compliance reportingsystems

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 headlessor operationscompleted fordevice inventory devices.operations. This endpoint allows you to monitor the status of automatedheadless tasks,operations, track their progress, and retrieve operation results. You can filter by specific transactionoperation IDs,IDs andor optionallyrequest updatereal-time device status information before returning results. Perfect for dashboards, monitoring systems, and operation tracking workflows.updates.

Use Cases:

  • Monitor the progress of scheduled firmware updates acrossbulk device fleetsconfiguration updates
  • CheckRetrieve results from scheduled device parameter collection tasks
Track the status of automated configurationdevice synchronizationprovisioning tasksoperations RetrieveAudit operationhistorical historydevice formanagement compliance and audit reporting Build monitoring dashboards showing real-time headless operation statusactivities

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.retrieve Usespecific this to getoperation 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)information

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_headless_operation/?update_status=true&limit=10"true" \
  -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,
    "12345"operation": "get",
    "operation_type"variables": "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"variable_name": "2.4.1",
        "backup_created": true,
        "estimated_duration": "00:15:00"Device.ManagementServer.PeriodicInformInterval"
      },
      {
        "created_at"variable_name": "2024-01-15T09:45:00Z",Device.WiFi.SSID.2.Stats.BytesReceived"
      "updated_at":}
    "2024-01-15T10:08:30Z"]
  },
  {
    "id": 12346,
    "12346"operation": "set",
    "operation_type"variables": "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"variable_name": "master_template"Device.ManagementServer.PeriodicInformInterval",
        "value": "300",
        "value_type": "integer"
      },
      {
        "created_at"variable_name": "2024-01-15T09:15:00Z"Device.ManagementServer.PeriodicInformEnable",
        "updated_at"value": "2024-01-15T09:32:18Z"1",
        "value_type": "boolean"
      }
    ]
  }
]

Response Codes:

Status Description
200 Success - Returns the listarray of headlessoperation operationsobjects
401 Unauthorized - Invalid or missing API token
403404 ForbiddenNot Found - Insufficient permissions to accessSpecified operation data
ID does not 500 Internal Server Error - Issue with status update helpers or databaseexist

POST /inventory_device_headless_operation/

Description: Creates and schedules a new headless device operation forto inventorybe executed on target devices. This endpoint allows you to automateschedule device management tasks such as firmwareparameter retrieval, configuration updates, configuration changes, or maintenanceobject routinesmanagement that need to run without user interaction.operations. The operation will be queued for execution and executedcan accordingbe tomonitored yourusing schedulingthe parameters.GET endpoint.

Use Cases:

  • Schedule firmware updates for device fleets during maintenance windows
Automatebulk configuration synchronizationupdates across multiple devices Initiate automated device parameter collection for monitoring Create object management operations for device provisioning Set up recurring healthdevice checksmaintenance and diagnostic operations Queue bulk operations for off-hours execution to minimize service impacttasks

Full URL Example:

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

Parameters:

Parameter Type In Required Description
data string body Yes JSON stringpayload containing the operation configuration,details including device targets,ID, schedulingoperation parameters,type, and operation-specific settingsvariables

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"id": 67890,
    "operation": "config_sync"set",
    "device_ids"variables": ["DEV-005"],
    "scheduled_at": "2024-01-16T01:00:00Z",
    "operation_data":
      {
        "config_template"variable_name": "standard_router_config"Device.ManagementServer.PeriodicInformInterval",
        "create_backup"value": true,"600",
        "validate_before_apply"value_type": true"integer"
      },
      {
        "variable_name": "Device.ManagementServer.PeriodicInformEnable",
        "value": "1",
        "value_type": "boolean"
      }
    ]
  }'

Example Request Body (Get Operation):

{
  "id": 67890,
  "operation": "get",
  "variables": [
    {
      "variable_name": "Device.ManagementServer.PeriodicInformInterval"
    },
    {
      "variable_name": "Device.WiFi.SSID.1.BSSID"
    }
  ]
}

Example Request Body (Set Operation):

{
  "id": 67890,
  "operation": "set",
  "variables": [
    {
      "variable_name": "Device.ManagementServer.PeriodicInformInterval",
      "value": "300",
      "value_type": "integer"
    },
    {
      "variable_name": "Device.ManagementServer.PeriodicInformEnable",
      "value": "true",
      "value_type": "boolean"
    }
  ]
}

Example Response:

{
  "id": 67890,
  "12347"operation": "set",
  "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"variables": [
    {
      "device_id"variable_name": "DEV-005"Device.ManagementServer.PeriodicInformInterval",
      "device_name"value": "Edge Router C"300",
      "device_serial"value_type": "ER-123-DEF"integer"
    },
    {
      "variable_name": "Device.ManagementServer.PeriodicInformEnable",
      "device_status"value": "online"true",
      "value_type": "boolean"
    }
  ],
  "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 JSONparameters
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: MonitoringBulk Fleet-WideDevice FirmwareConfiguration UpdatesUpdate

UseSchedule configuration changes across multiple devices by creating set operations for each device. Monitor progress using the GET endpoint with update_status=true to buildtrack acompletion real-time dashboard showing the progress of firmware updates across your entire device fleet. Filter by operation typestatus and useidentify paginationany tofailed handle large inventories efficiently.operations.

Use Case 2: Automated MaintenanceDevice WindowsMonitoring

ScheduleCreate multiplerecurring headlessget operations usingto collect device parameters for monitoring dashboards. Use the POSTupdate_status endpointparameter to ensure real-time data collection for yourcritical regular maintenance windows. Queue configuration backups, firmware updates, and health checks to run automatically during off-hours, reducing manual intervention and service disruptions.metrics.

Use Case 3: ComplianceDevice Provisioning Workflow

Combine add.obj operations to create new device objects during automated provisioning, followed by set operations to configure initial parameters and Auditget Reporting

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

Use Case 4: ProactiveNetwork DeviceMaintenance ManagementAutomation

Create recurring headless operations forSchedule device healthparameter checkscollection before maintenance windows, perform configuration updates, and preventivevalidate maintenance.changes Useafterward theusing POSTa endpointcombination toof schedule regular configuration validation, performance monitoring,get and automatedset remediation tasks.operations.

Use Case 5: EmergencyCompliance Response AutomationAuditing

WhenUse securityget patches or critical updates needoperations to beperiodically deployedcollect rapidly,device useconfiguration theparameters POSTand endpointcompare toagainst schedulecompliance immediatebaselines, headlessautomatically operationsgenerating acrossreports affectedof devices,configuration then monitor progress with the GET endpoint to ensure timely completion.drift.

Best Practices

  • BatchOperation Operations WiselySequencing: GroupWhen relatedperforming devices in singlemultiple operations ratheron thanthe creatingsame individualdevice, allow sufficient time between operations for each device to reduceensure APIproper overheadexecution and improveavoid scheduling efficiency.

    conflicts

  • 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 andusing implementthe retryGET logicendpoint before assuming success, especially for failedcritical operations.configuration Monitor for timeout scenarios and have rollback procedures ready.

changes

LeverageBatch WebhooksProcessing: ConfigureGroup webhookrelated notificationsoperations forby device or operation completion instead of frequent pollingtype to reduceoptimize APIexecution loadefficiency and improvesimplify real-time responsiveness.

monitoring

PlanVariable Validation: Verify variable names and data types before creating operations to prevent execution failures

Status Monitoring: Use the update_status parameter judiciously as it may impact API response times for Concurrencylarge device inventories Transaction Logging: BeStore awareoperation ofIDs devicefor capacityaudit trails and troubleshooting purposes Rate Limiting: Implement appropriate delays between API calls to respect system 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 quickreliable recoveryoperation if operations fail or need to be reversed.

execution
Back to top