Skip to main content

Inventory Device Name Diags

The inventory device name diagnostics endpoints enable you to execute and manage network diagnostic operations on specific devices in your inventory. These endpoints allow you to perform various network tests including speed tests, connectivity checks, and WiFi diagnostics to troubleshoot device performance and network issues.

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 diagnostics API provides a comprehensive suite of network diagnostic tools for managing and troubleshooting devices in your network inventory. This category allows you to remotely execute various diagnostic operations on Customer Premises Equipment (CPE) and other network devices to assess connectivity, performance, and configuration issues.

Key Features:

  • Multiple Diagnostic Types: Support for HTTP download/upload tests, ICMP ping, UDP echo tests, traceroute, DNS lookups, and WiFi neighbor discovery
  • Flexible Targeting: Configure tests with specific targets, interfaces, and parameters
  • Real-time Status Updates: Option to refresh device status before returning diagnostic information
  • Comprehensive Test Parameters: Control packet sizes, timeouts, hop counts, and repetition counts

Common Use Cases:

  • Network performance monitoring and speed testing
  • Connectivity troubleshooting for customer devices
  • WiFi environment analysis and interference detection
  • DNS resolution and routing path analysis
  • Automated network health assessments

The endpoints work together to provide a complete diagnostic workflow: list existing or scheduled diagnostics, and create new diagnostic operations with customized parameters for specific network testing scenarios.

Endpoints

GET /inventory_device_name_diags/

Description: Retrieves a list of network diagnostic operations for devices in your inventory. This endpoint allows you to view scheduled, running, or completed diagnostic tests and optionally refresh device status information before returning results.

Use Cases:

  • Monitor the status of ongoing diagnostic operations
  • Review historical diagnostic test results
  • Check scheduled diagnostic tasks before creating new ones
  • Update device connectivity status as part of diagnostic reporting

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_diags/?id=diag_12345&update_status=true

Parameters:

Parameter Type In Required Description
id string query No ID of the specific scheduled transaction to retrieve
update_status boolean query No Use configured helpers to update device status before returning the information

cURL Example:

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

Example Response:

[
  {
    "name": "customer-router-01",
    "operation": "download",
    "target": "http://speedtest.example.com/100mb.bin",
    "count": null,
    "size": null,
    "timeout": null,
    "max_hops": null,
    "interface": "eth0",
    "upload_size": null
  },
  {
    "name": "office-ap-wireless",
    "operation": "ipping",
    "target": "8.8.8.8",
    "count": 10,
    "size": 64,
    "timeout": 1,
    "max_hops": null,
    "interface": null,
    "upload_size": null
  },
  {
    "name": "branch-gateway-02",
    "operation": "wifi.neighbor",
    "target": "channel_scan",
    "count": null,
    "size": null,
    "timeout": null,
    "max_hops": null,
    "interface": "wlan0",
    "upload_size": null
  }
]

Response Codes:

Status Description
200 Success - Returns array of diagnostic operations
401 Unauthorized - Invalid or missing API token
404 Not Found - No diagnostic operations found
500 Internal Server Error - Server-side processing error

POST /inventory_device_name_diags/

Description: Creates a new network diagnostic operation for a specified device. This endpoint allows you to configure and initiate various types of network tests including speed tests, connectivity checks, DNS lookups, and WiFi diagnostics with customizable parameters.

Use Cases:

  • Initiate speed tests to measure download/upload performance
  • Perform connectivity diagnostics for troubleshooting
  • Schedule WiFi environment scans for interference analysis
  • Execute traceroute operations for routing path analysis
  • Run DNS lookup tests to verify name resolution

Full URL Example:

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

Request Body Parameters:

Parameter Type Required Description
name string Yes Name of the target device for diagnostic operation
operation string Yes Type of diagnostic operation. Allowed values: download, upload, ipping, udpecho, traceroute, dnslookup, wifi.neighbor
target string Yes Target URL, IP address, or hostname depending on operation type
upload_size string No File size in MB for upload operations
count integer No Number of packets (ping) or repetitions (DNS). Default: 5 for ping, 1 for DNS
size integer No Packet size in bytes for ping operations. Default: 64 bytes
timeout integer No Response timeout in seconds for ping/DNS operations. Default: 1 second
max_hops integer No Maximum hops for traceroute operations. Default: 30 hops
interface string No Network interface name to use for the operation

cURL Example - HTTP Download Test:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_name_diags/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-router-01",
    "operation": "download",
    "target": "http://speedtest.example.com/100mb.bin",
    "interface": "eth0"
  }'

cURL Example - ICMP Ping Test:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_name_diags/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "office-gateway",
    "operation": "ipping",
    "target": "8.8.8.8",
    "count": 10,
    "size": 128,
    "timeout": 2
  }'

cURL Example - WiFi Neighbor Scan:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_name_diags/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "wireless-ap-01",
    "operation": "wifi.neighbor",
    "target": "full_scan",
    "interface": "wlan0"
  }'

Example Response:

{
  "name": "customer-router-01",
  "operation": "download",
  "target": "http://speedtest.example.com/100mb.bin",
  "upload_size": null,
  "count": null,
  "size": null,
  "timeout": null,
  "max_hops": null,
  "interface": "eth0"
}

Response Codes:

Status Description
201 Created - Diagnostic operation successfully initiated
400 Bad Request - Invalid parameters or malformed request
401 Unauthorized - Invalid or missing API token
404 Not Found - Specified device not found in inventory
422 Unprocessable Entity - Valid JSON but invalid operation parameters
500 Internal Server Error - Server-side processing error

Common Use Cases

Use Case 1: Network Performance Monitoring

Monitor customer connection speeds by scheduling regular download and upload tests. Use the GET endpoint to track historical performance data and the POST endpoint to initiate new speed tests during peak usage times.

Use Case 2: Connectivity Troubleshooting

When customers report connectivity issues, use ping and traceroute operations to diagnose network path problems. Start with basic ping tests to verify connectivity, then use traceroute to identify where packets are being dropped or delayed.

Use Case 3: WiFi Environment Analysis

For wireless network optimization, use WiFi neighbor diagnostics to scan for interference and analyze channel utilization. This helps identify optimal channel assignments and detect rogue access points.

Use Case 4: DNS Resolution Monitoring

Ensure reliable internet access by testing DNS lookup performance against multiple DNS servers. Use this to identify DNS-related connectivity issues and optimize DNS server configurations.

Use Case 5: Scheduled Health Checks

Implement automated network health monitoring by combining device status updates with diagnostic operations. Use the update_status parameter to refresh device information before executing diagnostics.

Best Practices

  • Operation Selection: Choose the appropriate diagnostic operation for your use case. Use ipping for basic connectivity, traceroute for routing analysis, and download/upload for performance testing
  • Parameter Optimization: Adjust timeout values based on network conditions. Increase timeouts for high-latency connections and reduce packet counts for faster results
  • Interface Specification: Always specify the interface when testing specific network paths, especially on multi-homed devices with multiple network connections
  • Rate Limiting: Avoid overwhelming devices by spacing diagnostic operations appropriately. Consider device capabilities when scheduling multiple concurrent tests
  • Error Handling: Implement retry logic for failed operations, but include exponential backoff to prevent overwhelming devices or network infrastructure
  • Status Updates: Use the update_status=true parameter when you need current device information, but be aware this may increase response times
  • Target Selection: For speed tests, use geographically appropriate test servers. For ping tests, use reliable targets like major DNS servers (8.8.8.8, 1.1.1.1)
Back to top