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.

Revision #4
Created 2026-02-04 05:05:33 UTC by ipena@zequenze.com
Updated 2026-02-11 02:54:03 UTC by ipena@zequenze.com