Inventory Device Name Headless Operation

The Inventory Device Name Headless Operation API provides endpoints forenable managingautomated management and monitoring automatedof devicenetwork operationsdevices thatthrough runprogrammatic without direct user interface interaction.operations. These endpoints allow you to retrieve information about scheduledperform device operations like getting parameters, setting configurations, adding objects, and createdeleting newobjects headlesswithout operationsmanual intervention, making them ideal for inventorybulk device management and automated 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 iscategory provides functionality for executing automated operations on network devices in your inventory. These endpoints are designed for automatedscenarios where you need to perform bulk operations across multiple devices or integrate device management scenariosinto whereautomated 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.workflows.

Key concepts to understand:Concepts:

• Headless Operations: Automated tasksdevice operations that run without user interface interaction
• ScheduledDevice TransactionsVariables: Time-basedTR-069/CWMP operationsparameters that executecan accordingbe toretrieved, predefinedmodified, schedules

or managed Statuson Updates: Real-time synchronization of device states using configured helpersdevices Operation LifecycleTypes: TheFour completemain processoperation types are supported:

get: Retrieve parameter values from operationdevices creation set: Update parameter values on devices add.obj: Create new object instances on devices del.obj: Remove object instances from devices

Common Use Cases:

Bulk configuration updates across device fleets Automated monitoring and status collection Scheduled maintenance operations Integration with network management systems Device provisioning and deprovisioning workflows

The API supports complex variable operations with type validation and provides real-time status updates to completionhelp andmonitor monitoringoperation progress.

---

Endpoints

GET /inventory_device_name_headless_operation/

Description: Retrieves a list of scheduled or completed headless operations for inventorydevices devices.in your inventory. This endpoint allows you to monitor the status of automated operations, filter by specific transaction IDs, and optionally triggerupdate real-timedevice status updates using configured helpersinformation before returning the data.results.

Use Cases:

• Monitor the progress andof bulk device operations

Retrieve results from previously executed headless operations Check the status of scheduled device inventorymaintenance operationstasks RetrieveAudit specificdevice operation detailshistory usingfor transactioncompliance ID filtering Get real-time device status updates before processing operation results Generate reports on completed and pending headless operationsreporting

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_headless_operation/?id=txn_1234512345&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 detailsresults
update_status	boolean	query	No	When set to true, triggersUse configured helpers to update device status before returning information, ensuring real-time accuracyinformation

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"name": "https://control.zequenze.com/api/v1/inventory_device_name_headless_operation/?limit=10&offset=10"router-branch-01",
    "previous"operation": null,"get",
    "results"variables": [
      {
        "id"variable_name": "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"
      }Device.ManagementServer.PeriodicInformInterval"
      },
      {
        "id"variable_name": "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
      }Device.WiFi.SSID.1.Stats.BytesReceived"
      }
    ]
  },
  {
    "name": "switch-floor-02",
    "operation": "set",
    "variables": [
      {
        "variable_name": "Device.ManagementServer.PeriodicInformInterval",
        "value": "300",
        "value_type": "integer"
      },
      {
        "variable_name": "Device.ManagementServer.PeriodicInformEnable",
        "value": "1",
        "value_type": "boolean"
      }
    ]
  }
]

Response Codes:

Status	Description
200	Success - Returns list of headless operations with current status
401	Unauthorized - Invalid or missing API token
403404	ForbiddenNot Found - Insufficient permissions to access operation data

500 Internal Server Error - Error updating device status or retrievingNo operations found for specified criteria

---

POST /inventory_device_name_headless_operation/

Description: Creates a new headless operation for inventoryone deviceor management.more devices in your inventory. This endpoint allows you to schedule automated tasksoperations such as inventoryparameter synchronization,retrieval, configuration updates, object creation, or object deletion across your device health checks, or batch updates that will run without user intervention. The operation data should be provided in the request body.fleet.

Use Cases:

• Execute bulk configuration changes across multiple devices

Schedule automated inventoryparameter synchronizationcollection for specific devices or device groupsmonitoring CreateProvision backgroundnew healthservices monitoringby operationsadding forobject critical infrastructureinstances Initiate bulk device updates during maintenance windows SetClean up recurringunused deviceconfigurations complianceby checksremoving andobject reportinginstances

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 stringpayload containing the operation configuration including device targets, operation type, schedule, and parametersdetails

Request Body Schema:

{
  "name": "string (required)",
  "operation": "string (required, one of: get, set, add.obj, del.obj)",
  "variables": [
    {
      "variable_name": "string (required)",
      "value": "string (optional, required for 'set' operations)",
      "value_type": "string (optional, one of: string, integer, boolean)"
    }
  ]
}

cURL Example:Example - Get Operation:

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"name": "inventory_sync"router-main-office",
    "device_targets"operation": "get",
    "variables": ["WS-001-LAB-PC", "WS-002-LAB-PC"],
    "schedule":
      {
        "type"variable_name": "immediate"Device.ManagementServer.PeriodicInformInterval"
      },
      "parameters": {
        "sync_software": true,
      "sync_hardware": true,
      "update_location": false,
      "timeout_minutes": 30
    },
    "notification": {
      "on_completion": true,
      "on_failure": true,
      "email"variable_name": "admin@company.com"Device.WiFi.SSID.1.Stats.BytesReceived"
      }
    ]
  }'

cURL Example Request- Body:Set Operation:

{curl "operation_type":-X "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":POST "https://monitoring.company.control.zequenze.com/webhook/device-alerts"api/v1/inventory_device_name_headless_operation/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "router-branch-network",
    "operation": "set",
    "variables": [
      {
        "variable_name": "Device.ManagementServer.PeriodicInformInterval",
        "value": "300",
        "value_type": "integer"
      },
      "retry_policy": {
        "max_attempts"variable_name": 3,"Device.ManagementServer.PeriodicInformEnable",
        "retry_delay_minutes"value": 5"true",
        "value_type": "boolean"
      }
    ]
  }'

Example Response:

{
  "id"name": "txn_12347"router-main-office",
  "operation": "get",
  "variables": [
    {
      "variable_name": "Device.ManagementServer.PeriodicInformInterval"
    },
    {
      "variable_name": "Device.WiFi.SSID.1.Stats.BytesReceived"
    }
  ],
  "transaction_id": "op_67890",
  "status": "scheduled",
  "operation_type": "health_check",
  "device_targets": ["SRV-001-DB-01", "SRV-002-DB-01"],
  "created_at": "2024-01-15T11:20:15T14:30: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 operationOperation successfully scheduled
400	Bad Request - Invalid operation dataparameters or missingmalformed required parametersrequest
401	Unauthorized - Invalid or missing API token
403404	ForbiddenNot Found - InsufficientSpecified permissionsdevice tonot createfound operationsin for specified devices

422 Unprocessable Entity - Valid JSON but invalid operation configuration 500 Internal Server Error - Error scheduling the operationinventory

---

Common Use Cases

Use Case 1: AutomatedBulk NightlyWiFi InventoryConfiguration SyncUpdate

Schedule recurringset operations toacross synchronizemultiple deviceaccess inventory information every night, ensuring accurate asset tracking and compliance reporting. Use POSTpoints to createupdate theWiFi recurringsettings operationlike andchannel, GETpower, toor monitorsecurity dailyconfigurations executionduring status.maintenance windows.

Use Case 2: Real-timeNetwork OperationHealth Monitoring Dashboard

BuildUse get operations to collect statistics and performance metrics from devices on a dashboardscheduled thatbasis pollsfor thenetwork GET endpoint with update_status=true to display real-time progress of running operations, allowing IT teams to monitor automation workflowsmonitoring and quicklyreporting identify issues.dashboards.

Use Case 3: MaintenanceService Window AutomationProvisioning

CreateImplement batchadd.obj operations during scheduled maintenance windows to updatecreate devicenew configurations,service installinstances software,(like VLANs, SSIDs, or performport healthconfigurations) checkswhen acrossonboarding multiplenew devicescustomers simultaneouslyor without manual intervention.locations.

Use Case 4: Automated Compliance and Audit ReportingChecking

SetRegularly upexecute weekly headlessget operations to collectverify device configurations meet compliance data, security status,requirements and configuration drift information, automatically generating reports forgenerate audit and governance purposes.reports.

Use Case 5: ProactiveCleanup Deviceand Health MonitoringMaintenance

ImplementUse continuous monitoring by creating recurring health checkdel.obj operations thatto automaticallyremove detectunused deviceconfigurations, issues,expired performance degradation,certificates, or connectivitydecommissioned problemsservice beforeinstances theyduring impactroutine business operations.maintenance.

---

Best Practices

Operation SchedulingPlanning:: Use appropriate scheduling strategies - immediate execution for urgent tasks, recurring schedules for routine maintenance, and maintenance windows for resource-intensive operations.

Test operations on a small subset of devices before executing bulk operations Use

Errorthe Handling:update_status=true Alwaysparameter implementwhen retryyou logicneed andcurrent monitordevice information

Monitor operation status.results Useusing the GET endpoint with specific transaction IDs

Variable Management:

Always specify the correct value_type for set operations to trackensure individualproper parameter validation Use fully qualified TR-069 parameter paths for better compatibility across device types Validate variable names against your device's data model before executing operations

Error Handling:

Implement retry logic for operations andthat handlemay failuresfail gracefully.due to temporary network issues Check device connectivity status before scheduling operations Monitor operation status and implement timeout handling for long-running operations

Security Considerations:

Limit access to headless operation endpoints to authorized automation systems only Log all operations for audit trails and troubleshooting Use least-privilege principles when granting API access for automated systems

Performance OptimizationOptimization::

When

monitoringBatch multiplerelated operations,operations usetogether paginationwhen parameterspossible to reduce API calls Consider device capabilities and considernetwork cachingconditions results.when Thescheduling update_status parameter should be used judiciously as it triggers real-time device communication. operations Implement

Securityrate Considerations: Ensure API tokens have appropriate scope limitations. Store operation configurations securely and avoid exposing sensitive device credentialslimiting in operationyour parameters.

automation

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 operationsscripts to avoid spamoverwhelming and improve integration with monitoring systems.

devices

---