Skip to main content

Inventory Device Name Operation

This API category enables remote device management operations for inventory devices within the Zequenze platform. It provides endpoints to perform critical device operations like reboots, factory resets, configuration synchronization, and reconfiguration tasks programmatically. This is essential for IT administrators managing large fleets of devices who need to execute maintenance operations remotely without physical access.

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 operation API allows administrators to remotely execute critical maintenance and configuration operations on managed devices. This API is particularly valuable for:

  • Remote Device Management: Execute operations on devices across multiple locations without physical access
  • Bulk Maintenance Operations: Programmatically perform maintenance tasks across device fleets
  • Automated Device Recovery: Integrate device recovery operations into monitoring and alerting systems
  • Configuration Management: Synchronize device configurations and push updates remotely

The API supports five core operations: reboot, factory reset, device-specific factory reset, configuration synchronization, and device reconfiguration. Each operation is executed asynchronously, allowing for safe management of devices that may temporarily lose connectivity during the operation.

Important Concepts:

  • Operations are identified by device name rather than ID for easier integration
  • All operations are asynchronous and may take time to complete
  • Device connectivity may be temporarily interrupted during certain operations
  • Operation status should be monitored through other inventory endpoints

Endpoints

PUT /inventory_device_name_operation/{name}/

Description: Executes a specified operation on a device identified by its name. This endpoint is the primary mechanism for remotely managing device states, performing maintenance tasks, and updating configurations. The operation is queued and executed asynchronously on the target device.

Use Cases:

  • Remotely reboot unresponsive devices to restore functionality
  • Perform factory resets on devices being reassigned or decommissioned
  • Synchronize device configurations after policy updates
  • Reconfigure devices with new network or security settings
  • Execute maintenance operations during scheduled maintenance windows

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_operation/office-printer-01/

Parameters:

Parameter Type In Required Description
name string path Yes The unique name identifier of the target device in the inventory
data string body Yes JSON payload containing the operation details and parameters

Request Body Schema:

Field Type Required Description Allowed Values
operation string Yes The operation to perform on the device reboot, factory, device_factory, sync, reconf

Operation Types:

  • reboot: Performs a standard device restart
  • factory: Executes a complete factory reset, removing all configurations and data
  • device_factory: Performs a device-specific factory reset (preserves certain device-level settings)
  • sync: Synchronizes device configuration with the management server
  • reconf: Reconfigures device with updated settings and policies

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_name_operation/office-printer-01/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "reboot"
  }'

Example Request Bodies:

Reboot Operation:

{
  "operation": "reboot"
}

Factory Reset Operation:

{
  "operation": "factory"
}

Configuration Sync Operation:

{
  "operation": "sync"
}

Example Response:

{
  "id": 1247,
  "operation": "reboot"
}

Response Codes:

Status Description
200 Success - Operation queued successfully and will be executed on the device
400 Bad Request - Invalid operation type or malformed request data
401 Unauthorized - Invalid or missing API token
404 Not Found - Device with specified name does not exist in inventory
422 Unprocessable Entity - Device exists but cannot perform the requested operation (e.g., device offline)
500 Internal Server Error - Server error occurred while processing the request

Common Use Cases

Use Case 1: Automated Device Recovery

When monitoring systems detect unresponsive devices, automatically trigger a reboot operation to restore functionality without manual intervention.

Example Workflow:

  1. Monitoring system detects device is unresponsive
  2. Call the operation endpoint with "operation": "reboot"
  3. Monitor device status through inventory endpoints to confirm recovery

Use Case 2: Bulk Device Maintenance

Schedule maintenance operations across multiple devices during off-hours by iterating through device names and executing operations.

Example Workflow:

  1. Retrieve list of devices requiring maintenance
  2. For each device, call the operation endpoint with appropriate operation
  3. Log operation results for maintenance records

Use Case 3: Device Lifecycle Management

When devices are being reassigned or decommissioned, perform factory resets to ensure data security and prepare devices for new deployment.

Example Workflow:

  1. Identify devices for reassignment
  2. Execute factory operation to completely reset devices
  3. Verify reset completion before physical device transfer

Use Case 4: Configuration Deployment

After updating device policies or configurations in the management system, synchronize all affected devices to apply the changes.

Example Workflow:

  1. Update device policies in management system
  2. Execute sync operation on affected devices
  3. Monitor configuration status to ensure successful deployment

Best Practices

  • Operation Timing: Schedule intensive operations like factory resets during maintenance windows to minimize business impact
  • Error Handling: Always check response status codes and implement retry logic for transient failures (500 errors)
  • Device State Monitoring: After executing operations, monitor device status through inventory endpoints to confirm successful completion
  • Batch Processing: When performing operations on multiple devices, implement delays between requests to avoid overwhelming the system
  • Operation Logging: Maintain logs of all operations performed for audit trails and troubleshooting purposes
  • Network Considerations: Be aware that factory resets and reconfigurations may change device network settings, potentially affecting connectivity
  • Security: Ensure API tokens have appropriate permissions for device operations and rotate tokens regularly
  • Timeout Handling: Operations may take several minutes to complete; implement appropriate timeout values in your applications

Error Handling and Troubleshooting

Common Issues:

Device Not Found (404)

  • Verify the device name is correct and matches the inventory exactly
  • Check that the device exists in your organization's inventory
  • Ensure proper URL encoding for device names with special characters

Operation Failed (422)

  • Device may be offline or unreachable
  • Some operations may not be supported on specific device types
  • Device may be in a state that prevents the requested operation

Authentication Issues (401)

  • Verify API token is valid and not expired
  • Ensure token has sufficient permissions for device operations
  • Check that the Authorization header is properly formatted
Back to top