Skip to main content

Inventory Device Serial Diags

The inventory device serial diagnostics endpoints allow you to schedule and retrieve network diagnostic operations for specific devices in your inventory using their serial numbers. These endpoints enable remote troubleshooting and network performance testing on managed devices.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The inventory device serial diagnostics API provides powerful remote diagnostic capabilities for network-connected devices in your inventory. This API category enables you to perform various network diagnostic operations on devices by referencing their serial numbers, making it ideal for remote troubleshooting, performance monitoring, and network health assessments.

Key Features:

  • Multiple Diagnostic Types: Support for HTTP download/upload tests, ICMP ping, UDP echo, traceroute, DNS lookup, and WiFi neighbor scanning
  • Device-Specific Operations: Target specific devices using their serial numbers
  • Configurable Parameters: Customize test parameters like packet size, timeout values, hop counts, and network interfaces
  • Real-Time Status Updates: Option to update device status before returning diagnostic information

Common Use Cases:

  • Remote troubleshooting of connectivity issues
  • Network performance benchmarking and monitoring
  • Automated diagnostic scheduling for device health checks
  • WiFi environment analysis and optimization
  • DNS resolution testing and validation

The endpoints work together to provide a complete diagnostic workflow: use the GET endpoint to retrieve scheduled diagnostics and their results, and the POST endpoint to create new diagnostic operations.

Endpoints

GET /inventory_device_serial_diags/

Description: Retrieves a list of scheduled network diagnostic operations for devices in your inventory. This endpoint allows you to view existing diagnostic schedules, check their status, and optionally trigger real-time device status updates before returning the information.

Use Cases:

  • Monitor the status of previously scheduled diagnostic operations
  • Retrieve diagnostic results and performance metrics
  • Check which devices have pending diagnostic operations
  • Update device connectivity status before retrieving diagnostic information

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_diags/?id=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_serial_diags/?update_status=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

[
  {
    "serial_number": "SN123456789",
    "operation": "ipping",
    "target": "8.8.8.8",
    "count": 10,
    "size": 64,
    "timeout": 2,
    "interface": "eth0"
  },
  {
    "serial_number": "SN987654321",
    "operation": "download",
    "target": "https://speedtest.example.com/100MB.zip",
    "timeout": 30,
    "interface": "wlan0"
  },
  {
    "serial_number": "SN456789123",
    "operation": "wifi.neighbor",
    "target": "scan_all",
    "interface": "wlan0"
  }
]

Response Codes:

Status Description
200 Success - Returns the list of scheduled diagnostics
401 Unauthorized - Invalid or missing token
403 Forbidden - Insufficient permissions
500 Internal Server Error - Server-side error occurred

POST /inventory_device_serial_diags/

Description: Creates a new network diagnostic operation for a specific device identified by its serial number. This endpoint schedules various types of network tests including connectivity, performance, and environment scanning operations that will be executed on the target device.

Use Cases:

  • Schedule connectivity tests to troubleshoot network issues
  • Perform bandwidth testing with HTTP download/upload operations
  • Diagnose routing problems using traceroute operations
  • Test DNS resolution capabilities
  • Scan WiFi environment for interference and optimization

Full URL Example:

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

Request Body Parameters:

Field Type Required Description
serial_number string Yes Serial number of the device to run diagnostics on
operation string Yes Type of diagnostic operation (download, upload, ipping, udpecho, traceroute, dnslookup, wifi.neighbor)
target string Yes URL for download/upload, IP for ping/traceroute, hostname for DNS lookup, or parameter for WiFi scan
upload_size string No File size in MB for upload operations
count integer No Number of packets for ping (default: 5) or DNS lookup repetitions (default: 1)
size integer No Packet size in bytes for ping operations (default: 64)
timeout integer No Response timeout in seconds (default: 1)
max_hops integer No Maximum hops for traceroute (default: 30)
interface string No Network interface name to use for the operation

cURL Example - ICMP Ping Test:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_serial_diags/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serial_number": "SN123456789",
    "operation": "ipping",
    "target": "8.8.8.8",
    "count": 10,
    "size": 64,
    "timeout": 2,
    "interface": "eth0"
  }'

cURL Example - HTTP Download Test:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_serial_diags/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serial_number": "SN987654321",
    "operation": "download",
    "target": "https://speedtest.example.com/100MB.zip",
    "timeout": 30,
    "interface": "wlan0"
  }'

cURL Example - WiFi Neighbor Scan:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_serial_diags/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serial_number": "SN456789123",
    "operation": "wifi.neighbor",
    "target": "scan_all",
    "interface": "wlan0"
  }'

Example Response:

{
  "serial_number": "SN123456789",
  "operation": "ipping",
  "target": "8.8.8.8",
  "count": 10,
  "size": 64,
  "timeout": 2,
  "max_hops": null,
  "interface": "eth0",
  "upload_size": null
}

Response Codes:

Status Description
201 Created - Diagnostic operation successfully scheduled
400 Bad Request - Invalid parameters or missing required fields
401 Unauthorized - Invalid or missing token
403 Forbidden - Insufficient permissions
404 Not Found - Device with specified serial number not found
422 Unprocessable Entity - Invalid operation type or parameter combination

Common Use Cases

Use Case 1: Remote Connectivity Troubleshooting

When a device reports connectivity issues, schedule an ICMP ping test to verify basic network connectivity, followed by a traceroute to identify routing problems, and a DNS lookup test to verify name resolution.

Use Case 2: Bandwidth Performance Testing

Schedule HTTP download and upload tests to measure the actual throughput performance of devices, useful for validating service level agreements and identifying bandwidth bottlenecks.

Use Case 3: WiFi Environment Analysis

Use WiFi neighbor diagnostics to scan for nearby access points, identify channel interference, and optimize wireless performance for devices in dense RF environments.

Use Case 4: Automated Health Monitoring

Create scheduled diagnostic operations that run periodically to monitor device health, combining ping tests for connectivity, DNS lookups for name resolution, and interface-specific tests.

Use Case 5: Network Troubleshooting Workflow

Implement a systematic troubleshooting approach by first retrieving existing diagnostic results, then scheduling new tests based on the findings, and finally updating device status to reflect current conditions.

Best Practices

  • Operation Selection: Choose the most appropriate diagnostic operation for your specific troubleshooting needs - use ping for basic connectivity, traceroute for routing issues, and download/upload for performance testing
  • Parameter Optimization: Adjust timeout values based on network conditions and expected latency - longer timeouts for satellite or high-latency connections
  • Interface Specification: Always specify the network interface when testing specific connection types (ethernet vs WiFi) to get accurate results
  • Batch Processing: When testing multiple devices, stagger diagnostic operations to avoid overwhelming network resources
  • Status Updates: Use the update_status=true parameter when retrieving diagnostics to ensure you have the most current device status information
  • Error Handling: Implement proper retry logic for failed diagnostic operations, as network conditions can cause temporary failures
  • Security Considerations: Ensure diagnostic targets (URLs, IP addresses) are trusted and appropriate for your network security policies
Back to top