Skip to main content

Inventory Device Name

The inventory_device_name API endpoints provide comprehensive device management capabilities for network inventory systems. These endpoints enable you to perform complete CRUD operations on network devices, including retrieving device lists with advanced filtering, creating new device entries, updating device configurations, and managing device lifecycle 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 category is designed for managing network devices within an organization's infrastructure. These endpoints serve as the core interface for device inventory management, allowing you to:

  • Track device inventory across multiple organizations and locations
  • Monitor device status and health with real-time updates
  • Manage device configurations including firmware updates and settings synchronization
  • Control device operations such as reboots, factory resets, and configuration reapplication
  • Filter and search devices using multiple criteria like type, status, organization, and location

The API supports both individual device operations (by name) and bulk operations across device collections. Each device is uniquely identified by its name and contains comprehensive metadata including hardware/software versions, serial numbers, location data, and operational status.

Key concepts include device types (configuration templates), organizations (for multi-tenant environments), firmware management, and various operational states that control device behavior and connectivity.

Endpoints

GET /inventory_device_name/

Description: Retrieves a paginated list of all devices in your inventory with comprehensive filtering capabilities. This endpoint is essential for device discovery, monitoring dashboards, and bulk operations. It supports real-time status updates and can report pending configuration changes.

Use Cases:

  • Building device monitoring dashboards
  • Filtering devices by status for maintenance operations
  • Finding devices that need firmware updates
  • Generating inventory reports for specific organizations or locations

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name/?organization=123&status=true&limit=50&offset=0

Parameters:

Parameter Type In Required Description
type integer query No Filter devices by device type ID (configuration template)
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 by status change date (ISO format: 2000-01-01 or 2000-01-01 00:01:00+00:00)
organization integer query No Filter devices by organization ID for multi-tenant environments
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 configuration settings
update_status boolean query No Force real-time status update before returning results

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_name/?organization=123&status=true&pending=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_name/?limit=20&offset=20",
  "previous": null,
  "results": [
    {
      "id": 1,
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "router-hq-001",
      "customer_id": "CUST-001",
      "is_active": true,
      "status": "Up",
      "status_change": "2024-01-15T10:30:00Z",
      "type": 5,
      "type_short_name": "enterprise-router",
      "software_version": "1.4.2",
      "hardware_version": "Rev-C",
      "manufacturer": "Cisco",
      "serial_number": "SN123456789",
      "description": "Main headquarters router",
      "organization_id": 123,
      "location_name": "Headquarters - Server Room",
      "location_short_name": "HQ-SR",
      "latitude": "40.7128",
      "longitude": "-74.0060",
      "address": "192.168.1.1",
      "last_connection": "2024-01-15T14:22:00Z",
      "last_configuration": "2024-01-14T09:15:00Z",
      "pending_settings": "firmware_update,reboot_pending"
    }
  ]
}

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_name/

Description: Creates a new device entry in the inventory system. This endpoint is used when onboarding new network devices or registering devices that will connect via CWMP/TR-069 protocols. The device name must be unique within the system.

Use Cases:

  • Onboarding new network equipment
  • Pre-registering devices before physical installation
  • Bulk device provisioning for new sites
  • Setting up device authentication 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-005",
    "customer_id": "CUST-005",
    "is_active": true,
    "type": 5,
    "serial_number": "SN987654321",
    "description": "Branch office router - Site 005",
    "organization_id": 123,
    "location_name": "Branch Office 005",
    "latitude": "42.3601",
    "longitude": "-71.0589",
    "username": "device_005",
    "password": "secure_password_123"
  }'

Example Response:

{
  "id": 156,
  "uuid": "660f9511-f3ac-52e5-b827-557766551111",
  "name": "router-branch-005",
  "customer_id": "CUST-005",
  "is_active": true,
  "status": "Down",
  "status_change": "2024-01-15T15:45:00Z",
  "type": 5,
  "type_short_name": "enterprise-router",
  "serial_number": "SN987654321",
  "description": "Branch office router - Site 005",
  "organization_id": 123,
  "location_name": "Branch Office 005",
  "latitude": "42.3601",
  "longitude": "-71.0589",
  "username": "device_005",
  "created": "2024-01-15T15:45:00Z",
  "pending_settings": null
}

Response Codes:

Status Description
201 Created - Device successfully created
400 Bad Request - Invalid data or duplicate device name
401 Unauthorized - Invalid or missing API token

GET /inventory_device_name/{name}/

Description: Retrieves detailed information about a specific device identified by its unique name. This endpoint provides complete device metadata, current status, and configuration details. It's essential for device-specific operations and detailed monitoring.

Use Cases:

  • Getting complete device details for management interfaces
  • Checking device status before performing operations
  • Retrieving device credentials for configuration tasks
  • Monitoring specific device health and connectivity

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name/router-hq-001/?pending=true&update_status=true

Parameters:

Parameter Type In Required Description
name string path Yes Unique device name identifier
pending boolean query No Include pending settings information in response
update_status boolean query No Force real-time status check before returning data

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_name/router-hq-001/?pending=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "id": 1,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "router-hq-001",
  "customer_id": "CUST-001",
  "is_active": true,
  "status": "Up",
  "status_change": "2024-01-15T10:30:00Z",
  "type": 5,
  "type_short_name": "enterprise-router",
  "software_version": "1.4.2",
  "hardware_version": "Rev-C",
  "manufacturer": "Cisco",
  "unique_identifier": "cisco-1841-router",
  "product_class": "Router",
  "serial_number": "SN123456789",
  "serial_number_alt": "ALT-SN-001",
  "description": "Main headquarters router",
  "organization_id": 123,
  "firmware_image": 15,
  "firmware_image_is_pending": true,
  "location_name": "Headquarters - Server Room",
  "location": 45,
  "location_short_name": "HQ-SR",
  "latitude": "40.7128",
  "longitude": "-74.0060",
  "username": "admin_hq_001",
  "update_frequency": 300,
  "address": "192.168.1.1",
  "last_connection": "2024-01-15T14:22:00Z",
  "last_configuration": "2024-01-14T09:15:00Z",
  "last_change": "2024-01-14T09:15:00Z",
  "created": "2024-01-01T08:00:00Z",
  "debug": false,
  "pending_settings": "firmware_update,configuration_sync"
}

Response Codes:

Status Description
200 Success - Returns complete device information
401 Unauthorized - Invalid or missing API token
404 Not Found - Device with specified name does not exist

PUT /inventory_device_name/{name}/

Description: Performs a complete update of a device's configuration, replacing all modifiable fields with the provided data. This endpoint is used for comprehensive device reconfiguration, including changing device profiles, locations, credentials, and operational settings.

Use Cases:

  • Complete device reconfiguration during migrations
  • Updating device profiles and types
  • Changing device location and organizational assignment
  • Bulk configuration updates via automation scripts

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name/router-hq-001/

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_name/router-hq-001/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "router-hq-001",
    "customer_id": "CUST-001-UPDATED",
    "is_active": true,
    "type": 7,
    "serial_number": "SN123456789",
    "description": "Updated headquarters main router",
    "organization_id": 123,
    "location_name": "Headquarters - New Server Room",
    "latitude": "40.7128",
    "longitude": "-74.0060",
    "username": "admin_hq_001_new",
    "password": "updated_secure_password",
    "update_frequency": 600,
    "debug": true,
    "sync": true
  }'

Response Codes:

Status Description
200 Success - Device configuration updated completely
400 Bad Request - Invalid data format or validation errors
401 Unauthorized - Invalid or missing API token
404 Not Found - Device with specified name does not exist

PATCH /inventory_device_name/{name}/

Description: Performs a partial update of a device's configuration, modifying only the specified fields while leaving others unchanged. This endpoint is ideal for targeted updates like changing device status, triggering operations, or updating specific configuration parameters.

Use Cases:

  • Triggering device operations (reboot, factory reset, sync)
  • Updating specific configuration fields without full reconfiguration
  • Enabling/disabling debug mode
  • Changing firmware update settings

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name/router-hq-001/

cURL Example:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device_name/router-hq-001/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated device description",
    "debug": true,
    "reboot": true,
    "firmware_image": 18,
    "firmware_image_is_pending": true
  }'

Device Operation Examples:

Reboot Device:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device_name/router-hq-001/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reboot": true}'

Factory Reset:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device_name/router-hq-001/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"factory": true}'

Sync Configuration:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device_name/router-hq-001/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sync": true}'

Response Codes:

Status Description
200 Success - Device partially updated
400 Bad Request - Invalid field values or operation conflicts
401 Unauthorized - Invalid or missing API token
404 Not Found - Device with specified name does not exist

DELETE /inventory_device_name/{name}/

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

Use Cases:

  • Decommissioning retired network equipment
  • Removing test devices from production inventory
  • Cleaning up duplicate or incorrectly created device entries
  • Mass cleanup operations during system migrations

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name/old-router-decommissioned/

cURL Example:

curl -X DELETE "https://control.zequenze.com/api/v1/inventory_device_name/old-router-decommissioned/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response Codes:

Status Description
204 No Content - Device successfully deleted
401 Unauthorized - Invalid or missing API token
404 Not Found - Device with specified name does not exist
409 Conflict - Device cannot be deleted due to dependencies

Common Use Cases

Use Case 1: Device Status Monitoring Dashboard

Monitor device health across your network by regularly polling the GET /inventory_device_name/ endpoint with update_status=true and filtering by organization. Use status filters to identify problematic devices and the pending parameter to detect configuration drift.

Use Case 2: Automated Device Onboarding

Streamline new device deployment by using POST /inventory_device_name/ to pre-register devices with their serial numbers and credentials, then use PATCH operations to update configurations as devices come online and report their capabilities.

Use Case 3: Firmware Update Management

Manage firmware deployments by using GET to identify devices needing updates, PATCH to set firmware_image and firmware_image_is_pending=true, then monitor the pending_settings field to track update progress across your device fleet.

Use Case 4: Bulk Device Operations

Perform maintenance operations across multiple devices by first using GET with appropriate filters to identify target devices, then iterate through the results using PATCH to trigger operations like reboot, sync, or reconf based on your maintenance requirements.

Use Case 5: Multi-Organization Device Management

In multi-tenant environments, use the organization filter on GET requests to scope device operations to specific customers, ensuring proper data isolation while maintaining centralized management capabilities.

Best Practices

  • Use pagination wisely: When retrieving large device inventories, implement proper pagination with reasonable limit values (50-100) to avoid timeout issues and improve response times.

  • Leverage filtering effectively: Always use specific filters (organization, type, status) rather than retrieving all devices and filtering client-side. This reduces bandwidth and improves performance.

  • Handle device operations carefully: Operations like reboot, factory, and device_factory are immediate and irreversible. Always verify device names and consider maintenance windows before triggering these operations.

  • Monitor pending settings: Regular polling of the pending_settings field helps track configuration synchronization and identify devices with stale configurations that may need attention.

  • Implement proper error handling: Device operations can fail due to connectivity issues, device states, or conflicts. Implement retry logic with exponential backoff for transient failures.

  • Use meaningful device names: Device names serve as the primary identifier throughout the API. Use consistent naming conventions that include location, function, and sequence information for easier management.

  • Secure credential management: When creating or updating devices with authentication credentials, ensure passwords are generated securely and stored appropriately in your management systems.

Back to top