Skip to main content

Inventory Device

The Inventory Device API provides comprehensive device management capabilities, allowing you to perform CRUD operations on network devices, monitor their status, and execute device operations like reboots and factory resets. These endpoints are essential for managing device inventories, tracking device health, and performing remote device administration in network management systems.

Base URL: https://control.zequenze.com/api/v1

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device API is the core of device management operations, providing full lifecycle management for network devices. This API category enables you to:

  • Device Inventory Management: Create, read, update, and delete device records with comprehensive metadata including serial numbers, locations, firmware versions, and organizational assignments
  • Status Monitoring: Track device operational status, connection history, and configuration states with real-time updates
  • Remote Device Operations: Execute critical device operations like reboots, factory resets, configuration synchronization, and firmware updates
  • Organizational Control: Manage devices across different organizations with proper filtering and access controls
  • Location & Asset Tracking: Maintain device locations with GPS coordinates and location hierarchies

The API supports both bulk operations through the list endpoint with advanced filtering, and individual device management through the detail endpoints. Device operations are designed to work with CWMP/TR-069 protocols for remote device management, making it ideal for ISP and enterprise network management scenarios.

Key concepts include device types (profiles/templates), pending settings tracking, firmware management, and comprehensive audit trails for all device interactions.

Endpoints

GET /inventory_device/

Description: Retrieves a paginated list of inventory devices with comprehensive filtering capabilities. This endpoint is essential for device discovery, status monitoring, and bulk device management operations. It supports real-time status updates and pending settings detection.

Use Cases:

  • Dashboard displays showing all devices with current status
  • Filtering devices by organization for multi-tenant management
  • Finding devices that need firmware updates or have pending configurations
  • Monitoring device connectivity and health across the network

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device/?status=1&organization=5&limit=50&update_status=true

Parameters:

Parameter Type In Required Description
type integer query No Filter devices by device type/profile 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-01T00:01:00+00:00)
organization integer query No Filter devices by organization ID
limit integer query No Number of results per page (default: system configured)
offset integer query No Starting index for pagination
pending boolean query No Include pending settings information in response
update_status boolean query No Refresh device status from remote agents before returning data

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device/?status=1&organization=5&limit=25&update_status=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 150,
  "next": "https://control.zequenze.com/api/v1/inventory_device/?limit=25&offset=25&organization=5&status=1&update_status=true",
  "previous": null,
  "results": [
    {
      "id": 1001,
      "uuid": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Router-Branch-Office-001",
      "customer_id": "CUST-2024-001",
      "is_active": true,
      "status": "Up",
      "status_change": "2024-01-15T09:30:15Z",
      "type": 12,
      "type_short_name": "enterprise_router",
      "software_version": "2.4.1",
      "hardware_version": "v1.2",
      "manufacturer": "Zequenze Systems",
      "serial_number": "ZEQ240100001",
      "description": "Main branch office router",
      "organization_id": 5,
      "location_name": "New York Branch Office",
      "location": 25,
      "location_short_name": "ny_branch",
      "latitude": "40.7128",
      "longitude": "-74.0060",
      "address": "192.168.1.1",
      "last_connection": "2024-01-15T14:22:30Z",
      "last_configuration": "2024-01-14T10:15:00Z",
      "created": "2024-01-10T08:00:00Z",
      "pending_settings": "firmware_update,reboot_scheduled"
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns paginated device list
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient permissions for requested organization

POST /inventory_device/

Description: Creates a new inventory device record in the system. This endpoint is used for device onboarding, bulk device imports, and integrating new network equipment into the management platform.

Use Cases:

  • Adding new devices during network expansion
  • Bulk importing devices from spreadsheets or other systems
  • Pre-configuring device records before physical deployment
  • Setting up device credentials for CWMP/TR-069 authentication

Full URL Example:

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

cURL Example:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Router-Branch-Office-002",
    "customer_id": "CUST-2024-002",
    "serial_number": "ZEQ240100002",
    "type": 12,
    "organization_id": 5,
    "location_name": "Boston Branch Office",
    "description": "Secondary branch office router",
    "username": "device_admin",
    "password": "secure_password_123",
    "update_frequency": 300
  }'

Example Request Body:

{
  "name": "Router-Branch-Office-002",
  "customer_id": "CUST-2024-002",
  "serial_number": "ZEQ240100002",
  "serial_number_alt": "ALT-ZEQ240100002",
  "type": 12,
  "organization_id": 5,
  "location_name": "Boston Branch Office",
  "latitude": "42.3601",
  "longitude": "-71.0589",
  "description": "Secondary branch office router",
  "username": "device_admin",
  "password": "secure_password_123",
  "update_frequency": 300
}

Example Response:

{
  "id": 1002,
  "uuid": "550e8400-e29b-41d4-a716-446655440002",
  "name": "Router-Branch-Office-002",
  "customer_id": "CUST-2024-002",
  "is_active": false,
  "status": "Down",
  "status_change": "2024-01-15T15:30:00Z",
  "type": 12,
  "type_short_name": "enterprise_router",
  "software_version": null,
  "hardware_version": null,
  "manufacturer": null,
  "serial_number": "ZEQ240100002",
  "serial_number_alt": "ALT-ZEQ240100002",
  "description": "Secondary branch office router",
  "organization_id": 5,
  "location_name": "Boston Branch Office",
  "latitude": "42.3601",
  "longitude": "-71.0589",
  "username": "device_admin",
  "update_frequency": 300,
  "created": "2024-01-15T15:30:00Z",
  "pending_settings": null
}

Response Codes:

Status Description
201 Created - Device successfully created
400 Bad Request - Invalid input data or missing required fields
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient permissions to create devices

GET /inventory_device/{id}/

Description: Retrieves detailed information about a specific inventory device by its ID. This endpoint provides complete device metadata, operational status, and configuration details for individual device management.

Use Cases:

  • Device detail views in management interfaces
  • Retrieving device information for configuration operations
  • Checking specific device status and pending operations
  • Gathering device data for reporting and diagnostics

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device/1001/?pending=true&update_status=true

Parameters:

Parameter Type In Required Description
id integer path Yes Unique device ID
pending boolean query No Include detailed pending settings information
update_status boolean query No Refresh device status from remote agent before returning data

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device/1001/?pending=true&update_status=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "id": 1001,
  "uuid": "550e8400-e29b-41d4-a716-446655440001",
  "name": "Router-Branch-Office-001",
  "customer_id": "CUST-2024-001",
  "is_active": true,
  "status": "Up",
  "status_change": "2024-01-15T09:30:15Z",
  "type": 12,
  "type_short_name": "enterprise_router",
  "software_version": "2.4.1",
  "hardware_version": "v1.2",
  "manufacturer": "Zequenze Systems",
  "unique_identifier": "ZEQ:ENT:RTR:240100001",
  "product_class": "EnterpriseRouter",
  "serial_number": "ZEQ240100001",
  "serial_number_alt": "ALT-ZEQ240100001",
  "description": "Main branch office router",
  "organization_id": 5,
  "firmware_image": 45,
  "firmware_image_is_pending": true,
  "location_name": "New York Branch Office",
  "location": 25,
  "location_short_name": "ny_branch",
  "latitude": "40.7128",
  "longitude": "-74.0060",
  "username": "device_admin",
  "update_frequency": 300,
  "address": "192.168.1.1",
  "last_connection": "2024-01-15T14:22:30Z",
  "last_configuration": "2024-01-14T10:15:00Z",
  "last_change": "2024-01-15T12:45:20Z",
  "created": "2024-01-10T08:00:00Z",
  "debug": false,
  "pending_settings": "firmware_update:pending,reboot_scheduled:2024-01-16T02:00:00Z"
}

Response Codes:

Status Description
200 Success - Returns device details
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient permissions to view this device
404 Not Found - Device with specified ID does not exist

PUT /inventory_device/{id}/

Description: Updates all fields of an existing inventory device record. This endpoint performs a complete replacement of the device record and is used for comprehensive device configuration updates and bulk data corrections.

Use Cases:

  • Complete device reconfiguration during network changes
  • Updating device profiles when hardware is replaced
  • Bulk updates from external inventory systems
  • Correcting device information after physical audits

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device/1001/

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device/1001/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Router-Branch-Office-001-Updated",
    "customer_id": "CUST-2024-001",
    "serial_number": "ZEQ240100001",
    "type": 15,
    "organization_id": 5,
    "location_name": "New York Main Office",
    "description": "Updated main office router with new configuration",
    "latitude": "40.7589",
    "longitude": "-73.9851",
    "update_frequency": 180
  }'

Response Codes:

Status Description
200 Success - Device updated successfully
400 Bad Request - Invalid input data
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient permissions to update this device
404 Not Found - Device with specified ID does not exist

PATCH /inventory_device/{id}/

Description: Performs partial updates on an existing inventory device record. This endpoint allows you to update specific fields without affecting other device properties and is ideal for targeted operations like status changes, configuration updates, or device operations.

Use Cases:

  • Triggering device operations (reboot, factory reset, sync)
  • Updating device location or description without changing credentials
  • Setting firmware update flags and scheduling operations
  • Enabling debug mode or changing administrative state

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device/1001/

cURL Example for Device Reboot:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device/1001/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reboot": true,
    "debug": true
  }'

cURL Example for Firmware Update:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device/1001/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firmware_image": 47,
    "firmware_image_is_pending": true
  }'

cURL Example for Configuration Sync:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device/1001/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sync": true,
    "reconf": true
  }'

Device Operation Parameters:

Parameter Type Description
reboot boolean Triggers a device reboot operation
factory boolean Performs factory reset with configuration wipe
device_factory boolean Device-only factory reset (keeps stored config)
sync boolean Synchronizes settings with device's active configuration
reconf boolean Re-applies all existing settings to the device
debug boolean Enables/disables debug mode on the device

Response Codes:

Status Description
200 Success - Device updated successfully
400 Bad Request - Invalid operation or field values
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient permissions to update this device
404 Not Found - Device with specified ID does not exist

DELETE /inventory_device/{id}/

Description: Permanently removes an inventory device record from the system. This operation is irreversible and will delete all associated device data, configurations, and history. Use with caution in production environments.

Use Cases:

  • Removing decommissioned devices from inventory
  • Cleaning up test or duplicate device records
  • Device lifecycle management for retired equipment
  • Bulk cleanup operations during system maintenance

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device/1001/

cURL Example:

curl -X DELETE "https://control.zequenze.com/api/v1/inventory_device/1001/" \
  -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 this device
404 Not Found - Device with specified ID does not exist
409 Conflict - Device cannot be deleted due to dependencies

Common Use Cases

Use Case 1: Device Health Monitoring Dashboard

Create a real-time monitoring dashboard by using the list endpoint with status filtering and automatic updates. Combine GET /inventory_device/ with status=1&update_status=true to show all active devices, then use status=0 to identify down devices requiring attention.

Use Case 2: Remote Device Operations

Execute remote device management by using PATCH operations to trigger device actions. Use the detail endpoint to check pending operations, then PATCH with specific operation flags like reboot=true or sync=true to perform maintenance tasks.

Use Case 3: Firmware Management Workflow

Implement firmware updates by first using GET to identify devices needing updates, then PATCH to set firmware_image and firmware_image_is_pending=true flags. Monitor the process through the pending_settings field in subsequent GET requests.

Use Case 4: Multi-Tenant Device Management

Manage devices across multiple organizations using the organization filter parameter. Combine with proper API token scoping to ensure users only access devices within their authorized organizations.

Use Case 5: Device Onboarding Automation

Automate device deployment by using POST to create device records with pre-configured credentials and settings, then monitor first connection through the last_connection field using GET requests with update_status=true.

Best Practices

  • Pagination Management: Always use limit and offset parameters for large device inventories. Start with reasonable page sizes (25-50 devices) to balance performance and usability.

  • Status Update Optimization: Use update_status=true judiciously as it triggers real-time device queries. Enable it for critical monitoring but avoid it in high-frequency polling scenarios to prevent network overhead.

  • Device Operations: When performing device operations via PATCH, monitor the pending_settings field to track operation completion. Operations are asynchronous and may take time to complete.

  • Batch Operations: For bulk device management, implement proper error handling and retry logic. Use the list endpoint with appropriate filters to identify target devices before performing batch updates.

  • Security Considerations: Store device passwords securely and rotate them regularly. Use strong authentication credentials and consider the security implications of debug mode when troubleshooting.

  • Error Handling: Implement comprehensive error handling for device operations, especially for remote operations that may fail due to network connectivity or device state issues.

Back to top