Inventory Device Name

Endpoints Summary 
 
 
 
 Method 
 Path 
 Swagger 
 
 
 
 
 GET 
 /inventory_device_name/ 
 Swagger ↗ 
 
 
 POST 
 /inventory_device_name/ 
 Swagger ↗ 
 
 
 GET 
 /inventory_device_name/{name}/ 
 Swagger ↗ 
 
 
 PUT 
 /inventory_device_name/{name}/ 
 Swagger ↗ 
 
 
 PATCH 
 /inventory_device_name/{name}/ 
 Swagger ↗ 
 
 
 DELETE 
 /inventory_device_name/{name}/ 
 Swagger ↗ 
 
 
 
 
 
 The Inventory Device Name API provides comprehensive management capabilities for network devices in the Zequenze Control platform. These endpoints enable full CRUD operations for device inventory management, including device registration, configuration, monitoring, and control operations like reboots and factory resets. 
 
 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 API is the core interface for managing network devices within the Zequenze Control system. This API category handles device lifecycle management, from initial registration through ongoing monitoring and maintenance operations. 
 Key capabilities include: 
 
 
 Device Registration & Management : Add, update, and remove devices from your inventory 
 
 Status Monitoring : Track device connectivity, configuration state, and operational status 
 
 Remote Operations : Execute device operations like reboots, factory resets, and configuration synchronization 
 
 Location & Organization : Organize devices by location and organization for better management 
 
 Firmware Management : Handle firmware updates and version tracking 
 
 CWMP/TR-069 Integration : Support for standard device management protocols 
 
 The API uses device names as the primary identifier for individual device operations, while supporting various filtering options for bulk operations. All device data includes both user-configurable fields (name, location, credentials) and system-generated information (status, connection history, hardware details). 
 
 Endpoints 
 
 GET /inventory_device_name/ 
 Description: Retrieves a paginated list of all devices in your inventory. This endpoint supports extensive filtering options to help you find specific devices based on status, type, organization, or recent activity. It's the primary endpoint for building device dashboards, monitoring systems, and bulk operations. 
 Use Cases: 
 
 Building device inventory dashboards 
 Monitoring device status across your network 
 Filtering devices by organization or location for management 
 Finding devices that need attention (offline, pending updates) 
 
 Full URL Example: 
 https://control.zequenze.com/api/v1/inventory_device_name/?status=1&organization=123&limit=50&offset=0
 
 Parameters: 
 
 
 
 Parameter 
 Type 
 In 
 Required 
 Description 
 
 
 
 
 type 
 integer 
 query 
 No 
 Filter devices by device profile/type ID 
 
 
 status 
 string 
 query 
 No 
 Filter by device status. Use '0', 'false', 'False' for Down devices; '1', 'true', 'True' for Up devices 
 
 
 last_status_change_from 
 string 
 query 
 No 
 Filter devices with status changes after specified datetime (ISO format: 2000-01-01 or 2000-01-01 00:01:00+00:00) 
 
 
 organization 
 integer 
 query 
 No 
 Filter devices by organization ID 
 
 
 limit 
 integer 
 query 
 No 
 Number of results per page (default pagination applies) 
 
 
 offset 
 integer 
 query 
 No 
 Starting index for pagination 
 
 
 pending 
 boolean 
 query 
 No 
 Include information about pending device settings 
 
 
 update_status 
 boolean 
 query 
 No 
 Refresh device status from configured helpers before returning data 
 
 
 
 cURL Example: 
 curl -X GET "https://control.zequenze.com/api/v1/inventory_device_name/?status=1&limit=25&pending=true" \
 -H "Authorization: Bearer YOUR_API_TOKEN" \
 -H "Content-Type: application/json"
 
 Example Response: 
 {
 "count": 847,
 "next": "https://control.zequenze.com/api/v1/inventory_device_name/?limit=25&offset=25",
 "previous": null,
 "results": [
 {
 "id": 1001,
 "uuid": "550e8400-e29b-41d4-a716-446655440000",
 "name": "Router-Office-Main",
 "customer_id": "CUST-12345",
 "is_active": true,
 "status": "Up",
 "status_change": "2024-01-15T08:30:00Z",
 "type": 5,
 "type_short_name": "CPE-Router",
 "software_version": "1.4.2",
 "hardware_version": "Rev C",
 "manufacturer": "TechCorp",
 "unique_identifier": "MAC:00:1B:44:11:3A:B7",
 "product_class": "InternetGatewayDevice",
 "serial_number": "TC240115001",
 "serial_number_alt": "ALT-240115-001",
 "description": "Main office internet router",
 "organization_id": 123,
 "firmware_image": 89,
 "firmware_image_is_pending": false,
 "location_name": "Corporate Headquarters",
 "location": 45,
 "location_short_name": "HQ-Main",
 "latitude": "40.7128",
 "longitude": "-74.0060",
 "username": "device_001",
 "update_frequency": 300,
 "address": "192.168.1.1",
 "last_connection": "2024-01-15T14:22:33Z",
 "last_configuration": "2024-01-15T09:15:20Z",
 "last_change": "2024-01-15T09:15:20Z",
 "created": "2024-01-10T10:00:00Z",
 "debug": false,
 "reboot": false,
 "factory": false,
 "device_factory": false,
 "sync": false,
 "reconf": false,
 "pending_settings": "None"
 }
 ]
}
 
 Response Codes: 
 
 
 
 Status 
 Description 
 
 
 
 
 200 
 Success - Returns paginated device list 
 
 
 401 
 Unauthorized - Invalid or missing API token 
 
 
 403 
 Forbidden - Insufficient permissions 
 
 
 400 
 Bad Request - Invalid filter parameters 
 
 
 
 
 
 POST /inventory_device_name/ 
 Description: Creates a new device in your inventory. This endpoint registers a new device with the system, allowing you to set initial configuration, assign it to an organization and location, and configure management credentials. The device will be available for management operations once created. 
 Use Cases: 
 
 Adding newly purchased devices to inventory 
 Bulk device registration during network rollouts 
 Pre-configuring devices before deployment 
 Setting up device management credentials 
 
 Full URL Example: 
 https://control.zequenze.com/api/v1/inventory_device_name/
 
 cURL Example: 
 curl -X POST "https://control.zequenze.com/api/v1/inventory_device_name/" \
 -H "Authorization: Bearer YOUR_API_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
 "name": "Router-Branch-Office-A",
 "customer_id": "CUST-67890",
 "is_active": true,
 "type": 5,
 "serial_number": "TC240116002",
 "description": "Branch office A primary router",
 "organization_id": 124,
 "location": 46,
 "latitude": "34.0522",
 "longitude": "-118.2437",
 "username": "branch_router_a",
 "password": "secure_password_123",
 "update_frequency": 300
 }'
 
 Example Response: 
 {
 "id": 1002,
 "uuid": "660e8400-e29b-41d4-a716-446655440001",
 "name": "Router-Branch-Office-A",
 "customer_id": "CUST-67890",
 "is_active": true,
 "status": null,
 "status_change": null,
 "type": 5,
 "type_short_name": "CPE-Router",
 "software_version": null,
 "hardware_version": null,
 "manufacturer": null,
 "unique_identifier": null,
 "product_class": null,
 "serial_number": "TC240116002",
 "serial_number_alt": null,
 "description": "Branch office A primary router",
 "organization_id": 124,
 "firmware_image": null,
 "firmware_image_is_pending": false,
 "location_name": null,
 "location": 46,
 "location_short_name": "Branch-A",
 "latitude": "34.0522",
 "longitude": "-118.2437",
 "username": "branch_router_a",
 "password": "secure_password_123",
 "update_frequency": 300,
 "address": null,
 "last_connection": null,
 "last_configuration": null,
 "last_change": null,
 "created": "2024-01-16T10:30:00Z",
 "debug": false,
 "reboot": false,
 "factory": false,
 "device_factory": false,
 "sync": false,
 "reconf": false,
 "pending_settings": "None"
}
 
 Response Codes: 
 
 
 
 Status 
 Description 
 
 
 
 
 201 
 Created - Device successfully added to inventory 
 
 
 400 
 Bad Request - Invalid device data or missing required fields 
 
 
 401 
 Unauthorized - Invalid or missing API token 
 
 
 403 
 Forbidden - Insufficient permissions 
 
 
 409 
 Conflict - Device name already exists 
 
 
 
 
 
 GET /inventory_device_name/{name}/ 
 Description: Retrieves detailed information for a specific device identified by its name. This endpoint provides complete device information including current status, configuration, hardware details, and connection history. Use this for device-specific monitoring and troubleshooting. 
 Use Cases: 
 
 Displaying device details in management interfaces 
 Checking device status and connectivity 
 Retrieving device configuration before making changes 
 Troubleshooting device connectivity issues 
 
 Full URL Example: 
 https://control.zequenze.com/api/v1/inventory_device_name/Router-Office-Main/?pending=true&update_status=true
 
 Parameters: 
 
 
 
 Parameter 
 Type 
 In 
 Required 
 Description 
 
 
 
 
 name 
 string 
 path 
 Yes 
 Device name (URL encoded if contains special characters) 
 
 
 pending 
 boolean 
 query 
 No 
 Include pending settings information in response 
 
 
 update_status 
 boolean 
 query 
 No 
 Update device status from helpers before returning data 
 
 
 
 cURL Example: 
 curl -X GET "https://control.zequenze.com/api/v1/inventory_device_name/Router-Office-Main/?pending=true" \
 -H "Authorization: Bearer YOUR_API_TOKEN" \
 -H "Content-Type: application/json"
 
 Example Response: 
 {
 "id": 1001,
 "uuid": "550e8400-e29b-41d4-a716-446655440000",
 "name": "Router-Office-Main",
 "customer_id": "CUST-12345",
 "is_active": true,
 "status": "Up",
 "status_change": "2024-01-15T08:30:00Z",
 "type": 5,
 "type_short_name": "CPE-Router",
 "software_version": "1.4.2",
 "hardware_version": "Rev C",
 "manufacturer": "TechCorp",
 "unique_identifier": "MAC:00:1B:44:11:3A:B7",
 "product_class": "InternetGatewayDevice",
 "serial_number": "TC240115001",
 "serial_number_alt": "ALT-240115-001",
 "description": "Main office internet router",
 "organization_id": 123,
 "firmware_image": 89,
 "firmware_image_is_pending": false,
 "location_name": "Corporate Headquarters",
 "location": 45,
 "location_short_name": "HQ-Main",
 "latitude": "40.7128",
 "longitude": "-74.0060",
 "username": "device_001",
 "update_frequency": 300,
 "address": "192.168.1.1",
 "last_connection": "2024-01-16T14:22:33Z",
 "last_configuration": "2024-01-15T09:15:20Z",
 "last_change": "2024-01-15T09:15:20Z",
 "created": "2024-01-10T10:00:00Z",
 "debug": false,
 "reboot": false,
 "factory": false,
 "device_factory": false,
 "sync": false,
 "reconf": false,
 "pending_settings": "WiFi password update, Firmware upgrade to v1.4.3"
}
 
 Response Codes: 
 
 
 
 Status 
 Description 
 
 
 
 
 200 
 Success - Returns device details 
 
 
 401 
 Unauthorized - Invalid or missing API token 
 
 
 403 
 Forbidden - Insufficient permissions 
 
 
 404 
 Not Found - Device with specified name does not exist 
 
 
 
 
 
 PUT /inventory_device_name/{name}/ 
 Description: Completely updates a device's configuration by replacing all editable fields. This endpoint requires all writable fields to be provided and will overwrite the existing device configuration. Use for complete device reconfiguration or when you need to ensure all fields are set to specific values. 
 Use Cases: 
 
 Complete device reconfiguration 
 Standardizing device configurations across deployments 
 Migrating device settings to new templates 
 Bulk configuration updates with complete field control 
 
 Full URL Example: 
 https://control.zequenze.com/api/v1/inventory_device_name/Router-Office-Main/
 
 cURL Example: 
 curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_name/Router-Office-Main/" \
 -H "Authorization: Bearer YOUR_API_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
 "name": "Router-Office-Main",
 "customer_id": "CUST-12345-UPDATED",
 "is_active": true,
 "type": 5,
 "serial_number": "TC240115001",
 "serial_number_alt": "ALT-240115-001-UPD",
 "description": "Main office internet router - Updated configuration",
 "organization_id": 123,
 "firmware_image": 92,
 "firmware_image_is_pending": true,
 "location_name": "Corporate Headquarters - Building A",
 "location": 45,
 "latitude": "40.7128",
 "longitude": "-74.0060",
 "username": "device_001_updated",
 "password": "new_secure_password_456",
 "update_frequency": 600,
 "debug": false,
 "reboot": false,
 "factory": false,
 "device_factory": false,
 "sync": true,
 "reconf": false
 }'
 
 Example Response: 
 {
 "id": 1001,
 "uuid": "550e8400-e29b-41d4-a716-446655440000",
 "name": "Router-Office-Main",
 "customer_id": "CUST-12345-UPDATED",
 "is_active": true,
 "status": "Up",
 "status_change": "2024-01-15T08:30:00Z",
 "type": 5,
 "type_short_name": "CPE-Router",
 "software_version": "1.4.2",
 "hardware_version": "Rev C",
 "manufacturer": "TechCorp",
 "unique_identifier": "MAC:00:1B:44:11:3A:B7",
 "product_class": "InternetGatewayDevice",
 "serial_number": "TC240115001",
 "serial_number_alt": "ALT-240115-001-UPD",
 "description": "Main office internet router - Updated configuration",
 "organization_id": 123,
 "firmware_image": 92,
 "firmware_image_is_pending": true,
 "location_name": "Corporate Headquarters - Building A",
 "location": 45,
 "location_short_name": "HQ-Main",
 "latitude": "40.7128",
 "longitude": "-74.0060",
 "username": "device_001_updated",
 "update_frequency": 600,
 "address": "192.168.1.1",
 "last_connection": "2024-01-16T14:22:33Z",
 "last_configuration": "2024-01-16T15:45:12Z",
 "last_change": "2024-01-16T15:45:12Z",
 "created": "2024-01-10T10:00:00Z",
 "debug": false,
 "reboot": false,
 "factory": false,
 "device_factory": false,
 "sync": true,
 "reconf": false,
 "pending_settings": "Sync requested, Firmware upgrade to v1.4.5 pending"
}
 
 Response Codes: 
 
 
 
 Status 
 Description 
 
 
 
 
 200 
 Success - Device configuration updated 
 
 
 400 
 Bad Request - Invalid data or missing required fields 
 
 
 401 
 Unauthorized - Invalid or missing API token 
 
 
 403 
 Forbidden - Insufficient permissions 
 
 
 404 
 Not Found - Device with specified name does not exist 
 
 
 
 
 
 PATCH /inventory_device_name/{name}/ 
 Description: Partially updates a device's configuration by modifying only the specified fields. This endpoint allows you to update individual device properties without affecting other settings. It's ideal for making targeted changes like updating credentials, triggering operations, or modifying specific configuration parameters. 
 Use Cases: 
 
 Updating device credentials without changing other settings 
 Triggering device operations (reboot, sync, factory reset) 
 Modifying location or organizational assignments 
 Updating firmware assignments and triggering upgrades 
 
 Full URL Example: 
 https://control.zequenze.com/api/v1/inventory_device_name/Router-Office-Main/
 
 cURL Example: 
 curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device_name/Router-Office-Main/" \
 -H "Authorization: Bearer YOUR_API_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
 "description": "Updated description for main office router",
 "firmware_image": 95,
 "firmware_image_is_pending": true,
 "reboot": true,
 "sync": true
 }'
 
 Example Response: 
 {
 "id": 1001,
 "uuid": "550e8400-e29b-41d4-a716-446655440000",
 "name": "Router-Office-Main",
 "customer_id": "CUST-12345-UPDATED",
 "is_active": true,
 "status": "Up",
 "status_change": "2024-01-15T08:30:00Z",
 "type": 5,
 "type_short_name": "CPE-Router",
 "software_version": "1.4.2",
 "hardware_version": "Rev C",
 "manufacturer": "TechCorp",
 "unique_identifier": "MAC:00:1B:44:11:3A:B7",
 "product_class": "InternetGatewayDevice",
 "serial_number": "TC240115001",
 "serial_number_alt": "ALT-240115-001-UPD",
 "description": "Updated description for main office router",
 "organization_id": 123,
 "firmware_image": 95,
 "firmware_image_is_pending": true,
 "location_name": "Corporate Headquarters - Building A",
 "location": 45,
 "location_short_name": "HQ-Main",
 "latitude": "40.7128",
 "longitude": "-74.0060",
 "username": "device_001_updated",
 "update_frequency": 600,
 "address": "192.168.1.1",
 "last_connection": "2024-01-16T14:22:33Z",
 "last_configuration": "2024-01-16T15:45:12Z",
 "last_change": "2024-01-16T16:20:30Z",
 "created": "2024-01-10T10:00:00Z",
 "debug": false,
 "reboot": true,
 "factory": false,
 "device_factory": false,
 "sync": true,
 "reconf": false,
 "pending_settings": "Reboot requested, Sync requested, Firmware upgrade to v1.4.7 pending"
}
 
 Response Codes: 
 
 
 
 Status 
 Description 
 
 
 
 
 200 
 Success - Device partially updated 
 
 
 400 
 Bad Request - Invalid field values 
 
 
 401 
 Unauthorized - Invalid or missing API token 
 
 
 403 
 Forbidden - Insufficient permissions 
 
 
 404 
 Not Found - Device with specified name does not exist 
 
 
 
 
 
 DELETE /inventory_device_name/{name}/ 
 Description: Permanently removes a device from your inventory. This operation cannot be undone and will delete all associated device configuration, history, and settings. Use with caution and ensure the device is no longer needed in your management system. 
 Use Cases: 
 
 Removing decommissioned devices from inventory 
 Cleaning up test devices after development 
 Removing devices that have been physically replaced 
 Bulk cleanup of obsolete device entries 
 
 Full URL Example: 
 https://control.zequenze.com/api/v1/inventory_device_name/Router-Office-Main/
 
 Parameters: 
 
 
 
 Parameter 
 Type 
 In 
 Required 
 Description 
 
 
 
 
 name 
 string 
 path 
 Yes 
 Device name to delete (URL encoded if contains special characters) 
 
 
 
 cURL Example: 
 curl -X DELETE "https://control.zequenze.com/api/v1/inventory_device_name/Router-Old-Decommissioned/" \
 -H "Authorization: Bearer YOUR_API_TOKEN"
 
 Response Codes: 
 
 
 
 Status 
 Description 
 
 
 
 
 204 
 No Content - Device successfully deleted 
 
 
 401 
 Unauthorized - Invalid or missing API token 
 
 
 403 
 Forbidden - Insufficient permissions to delete device 
 
 
 404 
 Not Found - Device with specified name does not exist 
 
 
 409 
 Conflict - Device cannot be deleted (may have active connections or dependencies) 
 
 
 
 
 Common Use Cases 
 Device Status Dashboard 
 Build a real-time dashboard showing device health across your network by using the GET list endpoint with status filtering and regular polling. 
 # Get all online devices
https://control.zequenze.com/api/v1/inventory_device_name/?status=1&update_status=true

# Get devices that recently went offline
https://control.zequenze.com/api/v1/inventory_device_name/?status=0&last_status_change_from=2024-01-15T00:00:00
 
 Bulk Firmware Management 
 Manage firmware updates across multiple devices by filtering by device type and organization, then using PATCH to assign firmware images. 
 # Find all CPE routers in organization 123
https://control.zequenze.com/api/v1/inventory_device_name/?type=5&organization=123

# Update firmware for specific devices using PATCH with firmware_image and firmware_image_is_pending
 
 Device Provisioning Workflow 
 Automate device deployment by creating devices with POST, configuring initial settings, then using device operations to sync and activate. 
 # 1. Create device with POST
# 2. Use PATCH to set sync=true to synchronize initial configuration
# 3. Monitor device status until it comes online
 
 Remote Device Operations 
 Execute remote operations on devices using PATCH with operation flags like reboot, sync, factory reset. 
 # Reboot a device
PATCH /inventory_device_name/device-name/ with {"reboot": true}

# Factory reset and reconfigure
PATCH /inventory_device_name/device-name/ with {"factory": true, "reconf": true}
 
 Location-Based Device Management 
 Organize and manage devices by geographic location using location fields and filtering for field technician workflows. 
 # Get all devices at a specific location
https://control.zequenze.com/api/v1/inventory_device_name/?location=45

# Update device location
PATCH /inventory_device_name/device-name/ with {"location": 46, "latitude": "34.0522", "longitude": "-118.2437"}
 
 
 Best Practices 
 
 
 Use Pagination : Always implement pagination for list requests to avoid timeouts with large device inventories. Start with reasonable limits (25-100 devices). 
 
 
 Device Naming Strategy : Use consistent, meaningful device names that include location or function identifiers. Device names are the primary lookup mechanism. 
 
 
 Status Monitoring : Use the update_status=true parameter judiciously as it triggers real-time status checks which can impact performance. Consider caching status data for dashboard applications. 
 
 
 Bulk Operations : For bulk updates, retrieve device lists first, then use PATCH for individual devices rather than PUT to avoid overwriting unrelated settings. 
 
 
 Error Handling : Implement proper retry logic for 5xx errors and respect rate limits. Device operations may take time to complete, so poll for status changes rather than assuming immediate completion. 
 
 
 Security : Never log or store device passwords in plain text. Use the password field only for setting new credentials, not for retrieval. 
 
 
 Operation Flags : When using operation flags (reboot, sync, factory), set them to true to trigger the operation. The system will handle resetting the flags after execution. 
 
 
 Firmware Management : Always verify firmware compatibility before setting firmware_image_is_pending=true . Monitor the device after firmware updates to ensure successful deployment.