Skip to main content

Inventory Device Name

The Inventory Device Name API provides endpoints for managing network device inventory through name-based operations. These endpoints enable full CRUD functionality for device management, status monitoring, and organizational filtering, making it easy to maintain an up-to-date inventory of your network infrastructure.

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 comprehensive device inventory management within network infrastructure systems. This API allows you to perform complete lifecycle management of network devices, from initial registration to ongoing monitoring and maintenance.

Key Features:

  • Device Discovery and Registration: Add new devices to your inventory with detailed specifications
  • Status Monitoring: Track device operational status and historical changes
  • Organizational Management: Filter and organize devices by organizational units
  • Real-time Updates: Get current device status with optional live status checks
  • Pending Configuration Tracking: Monitor devices that have configuration changes awaiting application

Common Integration Scenarios:

  • Network monitoring dashboards pulling device status and inventory data
  • Automated device provisioning systems registering new hardware
  • Maintenance scheduling systems filtering devices by type and organization
  • Compliance reporting tools tracking device status changes over time

The endpoints work together to provide a complete device management workflow: list and filter devices, retrieve detailed information, update configurations, and remove decommissioned equipment.

Endpoints

GET /inventory_device_name/

Description: Retrieves a paginated list of all inventory devices with comprehensive filtering options. This endpoint serves as the primary entry point for device discovery and bulk operations, allowing you to filter by device characteristics, organizational boundaries, and operational status.

Use Cases:

  • Dashboard displays showing all devices in an organization
  • Automated monitoring systems checking for devices with pending configurations
  • Maintenance workflows identifying devices that haven't been updated recently
  • Compliance audits filtering devices by type and status

Full URL Example:

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

Parameters:

Parameter Type In Required Description
type integer query No Filter devices by device type ID (e.g., router, switch, firewall)
status string query No Filter by operational status. Use '0', 'false', 'False' for Down devices, or '1', 'true', 'True' for Up devices
last_status_change_from string query No Filter devices with status changes after specified datetime in ISO format (2000-01-01, 2000-01-01 00:01:00, 2000-01-01 00:01:00+00:00)
organization integer query No Filter devices by organization ID to scope results to specific organizational units
limit integer query No Number of results to return per page (default: 20, max: 100)
offset integer query No Starting index for pagination (use with limit for page navigation)
pending boolean query No When true, includes information about pending configuration changes
update_status boolean query No When true, performs real-time status check before returning results (may increase response time)

cURL Example:

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

Example Response:

{
  "count": 156,
  "next": "https://control.zequenze.com/api/v1/inventory_device_name/?limit=20&offset=20&organization=5&status=true",
  "previous": null,
  "results": [
    {
      "name": "core-switch-01",
      "type": 2,
      "type_name": "Core Switch",
      "organization": 5,
      "organization_name": "IT Operations",
      "status": true,
      "ip_address": "192.168.1.10",
      "serial_number": "CS-2024-001",
      "model": "Cisco Catalyst 9500",
      "last_seen": "2024-01-15T14:30:22Z",
      "last_status_change": "2024-01-10T09:15:00Z",
      "pending_changes": true,
      "location": "Data Center Rack 4A",
      "firmware_version": "16.12.05"
    },
    {
      "name": "edge-router-02",
      "type": 1,
      "type_name": "Edge Router",
      "organization": 5,
      "organization_name": "IT Operations",
      "status": true,
      "ip_address": "10.0.1.1",
      "serial_number": "ER-2024-002",
      "model": "Juniper MX204",
      "last_seen": "2024-01-15T14:29:45Z",
      "last_status_change": "2024-01-12T16:20:30Z",
      "pending_changes": false,
      "location": "Network Closet B",
      "firmware_version": "21.2R3.8"
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns paginated list of devices
401 Unauthorized - Invalid or missing authentication token
403 Forbidden - Insufficient permissions to access organization devices
400 Bad Request - Invalid filter parameters or date format

POST /inventory_device_name/

Description: Creates a new device entry in the inventory system. This endpoint is typically used during device onboarding, network expansion, or when integrating with automated discovery tools that identify new hardware on the network.

Use Cases:

  • Automated network discovery tools registering newly detected devices
  • Manual device registration during infrastructure deployments
  • Bulk import operations from existing inventory systems
  • Integration with procurement systems when new hardware arrives

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": "new-firewall-03",
    "type": 3,
    "organization": 5,
    "ip_address": "192.168.1.50",
    "serial_number": "FW-2024-003",
    "model": "Fortinet FortiGate 200F",
    "location": "DMZ Rack 1B",
    "firmware_version": "7.2.3",
    "status": false
  }'

Example Request Body:

{
  "name": "new-firewall-03",
  "type": 3,
  "organization": 5,
  "ip_address": "192.168.1.50",
  "serial_number": "FW-2024-003",
  "model": "Fortinet FortiGate 200F",
  "location": "DMZ Rack 1B",
  "firmware_version": "7.2.3",
  "status": false,
  "description": "Edge firewall for DMZ protection",
  "purchase_date": "2024-01-10",
  "warranty_expiry": "2027-01-10"
}

Example Response:

{
  "name": "new-firewall-03",
  "type": 3,
  "type_name": "Firewall",
  "organization": 5,
  "organization_name": "IT Operations",
  "ip_address": "192.168.1.50",
  "serial_number": "FW-2024-003",
  "model": "Fortinet FortiGate 200F",
  "location": "DMZ Rack 1B",
  "firmware_version": "7.2.3",
  "status": false,
  "description": "Edge firewall for DMZ protection",
  "purchase_date": "2024-01-10",
  "warranty_expiry": "2027-01-10",
  "created_at": "2024-01-15T14:35:00Z",
  "updated_at": "2024-01-15T14:35:00Z",
  "pending_changes": false
}

Response Codes:

Status Description
201 Created - Device successfully added to inventory
400 Bad Request - Invalid data format or missing required fields
401 Unauthorized - Invalid or missing authentication token
409 Conflict - Device name or serial number already exists

GET /inventory_device_name/{name}/

Description: Retrieves detailed information for a specific device identified by its unique name. This endpoint provides comprehensive device details and is commonly used for device-specific operations, monitoring dashboards, and detailed configuration management.

Use Cases:

  • Device detail pages in management interfaces
  • Configuration management systems retrieving current device state
  • Monitoring alerts requiring specific device information
  • Troubleshooting workflows needing complete device context

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name/core-switch-01/?pending=true&update_status=true

Parameters:

Parameter Type In Required Description
name string path Yes The unique device name identifier
pending boolean query No Include detailed information about pending configuration changes
update_status boolean query No Perform real-time status check before returning device information

cURL Example:

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

Example Response:

{
  "name": "core-switch-01",
  "type": 2,
  "type_name": "Core Switch",
  "organization": 5,
  "organization_name": "IT Operations",
  "status": true,
  "ip_address": "192.168.1.10",
  "serial_number": "CS-2024-001",
  "model": "Cisco Catalyst 9500",
  "location": "Data Center Rack 4A",
  "firmware_version": "16.12.05",
  "description": "Primary core switch for data center traffic",
  "purchase_date": "2023-06-15",
  "warranty_expiry": "2026-06-15",
  "last_seen": "2024-01-15T14:30:22Z",
  "last_status_change": "2024-01-10T09:15:00Z",
  "created_at": "2023-06-20T10:00:00Z",
  "updated_at": "2024-01-15T14:30:22Z",
  "pending_changes": true,
  "pending_details": {
    "config_changes": 3,
    "firmware_update": true,
    "last_config_push": "2024-01-14T16:45:00Z"
  },
  "interfaces": [
    {
      "name": "GigabitEthernet1/0/1",
      "status": "up",
      "speed": "1000Mbps"
    }
  ],
  "uptime": "15 days, 8 hours, 22 minutes"
}

Response Codes:

Status Description
200 Success - Returns detailed device information
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Device with specified name does not exist
403 Forbidden - Insufficient permissions to access this device

PUT /inventory_device_name/{name}/

Description: Completely replaces all device information with the provided data. This endpoint performs a full update operation, requiring all device fields to be specified. Use this when you need to update multiple device attributes or when integrating with systems that provide complete device records.

Use Cases:

  • Bulk synchronization from external inventory management systems
  • Complete device reconfiguration during infrastructure changes
  • Data migration scenarios requiring full record replacement
  • Integration with asset management systems providing complete device profiles

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name/core-switch-01/

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_name/core-switch-01/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "core-switch-01",
    "type": 2,
    "organization": 5,
    "ip_address": "192.168.1.10",
    "serial_number": "CS-2024-001",
    "model": "Cisco Catalyst 9500",
    "location": "Data Center Rack 4A",
    "firmware_version": "16.12.06",
    "status": true,
    "description": "Updated primary core switch with latest firmware",
    "purchase_date": "2023-06-15",
    "warranty_expiry": "2026-06-15"
  }'

Response Codes:

Status Description
200 Success - Device information completely updated
400 Bad Request - Invalid data format or missing required fields
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Device with specified name does not exist

PATCH /inventory_device_name/{name}/

Description: Performs a partial update of device information, modifying only the specified fields while leaving other attributes unchanged. This endpoint is ideal for targeted updates like status changes, firmware updates, or location modifications without affecting other device data.

Use Cases:

  • Status updates from monitoring systems detecting device state changes
  • Location updates when devices are physically relocated
  • Firmware version tracking after upgrade operations
  • Incremental data updates from automated discovery tools

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name/core-switch-01/

cURL Example:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device_name/core-switch-01/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firmware_version": "16.12.06",
    "status": true,
    "location": "Data Center Rack 4B"
  }'

Example Request Body:

{
  "firmware_version": "16.12.06",
  "status": true,
  "location": "Data Center Rack 4B",
  "description": "Relocated and updated with latest firmware"
}

Response Codes:

Status Description
200 Success - Device information partially updated
400 Bad Request - Invalid data format for provided fields
401 Unauthorized - Invalid or missing authentication 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 endpoint should be used when devices are decommissioned, replaced, or no longer part of the managed infrastructure. The operation is irreversible and will remove all associated device data.

Use Cases:

  • Decommissioning old hardware that's been replaced
  • Removing devices that are no longer part of the managed network
  • Cleanup operations for devices that were incorrectly added
  • Automated removal of devices that haven't been seen for extended periods

Full URL Example:

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

cURL Example:

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

Response Codes:

Status Description
204 No Content - Device successfully deleted from inventory
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Device with specified name does not exist
403 Forbidden - Insufficient permissions to delete this device

Common Use Cases

Use Case 1: Network Dashboard Integration

Build a real-time network monitoring dashboard by first calling GET /inventory_device_name/ with update_status=true to get current device states, then use GET /inventory_device_name/{name}/ for detailed views when users click on specific devices. Filter by organization to scope the dashboard to specific network segments.

Use Case 2: Automated Device Discovery and Registration

Network discovery tools can integrate by first checking if devices exist using GET /inventory_device_name/ with IP address or serial number filters, then calling POST /inventory_device_name/ to register new devices. Use PATCH /inventory_device_name/{name}/ to update device status and firmware information as discovered.

Use Case 3: Maintenance and Compliance Tracking

Generate maintenance reports by filtering devices using last_status_change_from parameter to identify devices that haven't been updated recently. Use the pending=true parameter to find devices with configuration changes awaiting application. Update device information with PATCH operations as maintenance is completed.

Use Case 4: Device Lifecycle Management

Track devices from procurement to decommissioning: create devices with POST when they arrive, update locations and configurations with PATCH during deployment, monitor status with filtered GET requests, and remove with DELETE when decommissioned.

Use Case 5: Multi-Organization Infrastructure Management

Use the organization filter parameter to separate device management for different business units or customers. This enables service providers or large organizations to maintain separate device inventories while using a single API instance.

Best Practices

  • Pagination Strategy: Always use limit and offset parameters for large device inventories. Start with smaller page sizes (20-50 items) to ensure responsive API calls, especially when using update_status=true.

  • Status Update Performance: The update_status=true parameter performs real-time device checks and can significantly increase response time. Use it judiciously for critical operations and consider caching results for dashboard displays.

  • Error Handling: Implement retry logic for 5xx errors and respect rate limits. When creating devices, handle 409 conflicts gracefully by checking if the device already exists with the same serial number or name.

  • Filtering Optimization: Use specific filters like organization and type to reduce response payload size. Combine multiple filters to create precise device queries rather than filtering large result sets client-side.

  • Date Format Consistency: Always use ISO format for datetime parameters (2024-01-15T14:30:00Z). Include timezone information to avoid ambiguity in multi-region deployments.

  • Partial Updates: Prefer PATCH over PUT for most update operations to avoid accidentally clearing fields that weren't intended to be modified. Reserve PUT for complete data synchronization scenarios.

  • Security Considerations: Store API tokens securely and rotate them regularly. Use organization-based filtering to ensure users only access devices within their scope of responsibility.

Back to top