Inventory Device Serial Diags
Endpoints Summary
POST
/inventory_device_serial_diags/
Swagger ↗
GET
/inventory_device_serial_diags/
Swagger ↗
The
inventoryInventorydeviceDeviceserialSerialdiagnosticsDiagnosticsendpointsAPIallowenablesyouremotetoexecutionschedule and retrieveof network diagnostic operationsforon specific devicesin your inventoryusing their serial numbers. These endpointsenableallowremoteyoutroubleshootingto schedule diagnostic tests like ping, traceroute, speed tests, and WiFi neighbor scans, then retrieve results to troubleshoot connectivity issues and monitor networkperformance testing on managed devices.performance.
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-connectednetwork devices in your inventory. This API category enables youtechnicians and network administrators to performremotely execute various network diagnostic operations on devicesCustomer byPremises referencingEquipment their serial numbers, making it ideal for remote troubleshooting, performance monitoring,(CPE) and networkother healthmanaged assessments.devices without requiring physical access.
Key Features:capabilities include:
-
MultipleNetworkDiagnosticPerformanceTypesTesting:Support for HTTPExecute download/uploadtests,speedICMPtestsping,toUDPmeasureecho, traceroute, DNS lookup, and WiFi neighbor scanningbandwidth -
Device-SpecificConnectivityOperationsDiagnostics:TargetPerformspecificICMPdevicespingusingteststheirtoserialverifynumbersreachability -
ConfigurableRouteParametersAnalysis:CustomizeRuntesttracerouteparametersoperationsliketopacket size, timeout values, hop counts, andidentify networkinterfacespath issues -
Real-TimeDNSStatusResolutionUpdatesTesting:OptionValidatetoDNSupdatelookupdevicefunctionality
CommonHow Useit Cases:works:
Remote troubleshooting of connectivity issues
The endpoints work together to provide a complete diagnostic workflow: use the GET endpoint to retrieve scheduled diagnostics and their results, andusing the POST endpoint towith createspecific newtest parameters
Endpoints
GET /inventory_device_serial_diags/
Description: Retrieves a list of scheduled network diagnostic operationsrequest for devicesthe in your inventory. This endpoint allows you to view existing diagnostic schedules, check their status, and optionally trigger real-timetarget device status updates before returning the information.
Use Cases:
Full URL Example:
https://control.zequenze.com/api/v1/inventory_device_serial_diags/?id=12345&update_status=true
Parameters:
cURLThis Example:API is essential for remote troubleshooting, proactive network monitoring, and validating service quality without dispatching field technicians.
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"
Endpoints
[
{
"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:
POST /inventory_device_serial_diags/
Description: CreatesSchedules a new network diagnostic operation foron a specific device identified by its serial number. This endpoint schedulesqueues various types of networkdiagnostic tests including connectivity, performance, and environment scanning operations that will be executed onwhen the target device.device next communicates with the management platform. Use this to initiate remote troubleshooting or performance testing.
Use Cases:
ScheduleCustomerconnectivityreports slow internet speeds - schedule download/upload tests
Full URL Example:
https://control.zequenze.com/api/v1/inventory_device_serial_diags/
Request Body Parameters:
| Type | Required | Description | |
|---|---|---|---|
| serial_number | string | Yes | Serial number of the target device to |
| operation | string | Yes | Type of diagnostic download, upload, ipping, udpecho, traceroute, dnslookup, wifi. |
| target | string | Yes | Test target - URL for |
| upload_size | string | No | File size in MB for upload |
| 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 for ping/DNS operations (default: 1) |
| max_hops | integer | No | Maximum hops for traceroute operations (default: 30) |
| interface | string | No |
cURL Example - ICMPSpeed PingTest:
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": "download",
"target": "http://speedtest.example.com/1GB.bin"
}'
cURL Example - Connectivity 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"2
}'
Example Response:
{
"serial_number": "SN123456789",
"operation": "ipping"download",
"target": "8.8.8.8"http://speedtest.example.com/1GB.bin",
"upload_size": null,
"count": 10,null,
"size": 64,null,
"timeout": 2,null,
"max_hops": null,
"interface": null,
"eth0"id": "diag_12345",
"upload_size"status": null"scheduled",
"created_at": "2024-01-15T10:30:00Z"
}
Response Codes:
| Status | Description |
|---|---|
| 201 | Created - Diagnostic operation successfully scheduled |
| 400 | Bad Request - Invalid parameters or |
| 401 | Unauthorized - Invalid or missing API token |
GET /inventory_device_serial_diags/
Description: Retrieves diagnostic operation results and status information. Use this endpoint to check the progress and results of previously scheduled diagnostic tests. You can query for specific operations or list all diagnostics for monitoring purposes.
Use Cases:
Full URL Example:
https://control.zequenze.com/api/v1/inventory_device_serial_diags/?id=diag_12345&update_status=true
Parameters:
cURL Example - Get Specific Diagnostic:
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_serial_diags/?id=diag_12345" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json"
cURL Example - List All Diagnostics:
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 - Speed Test Results:
[
{
"id": "diag_12345",
"serial_number": "SN123456789",
"operation": "download",
"target": "http://speedtest.example.com/1GB.bin",
"status": "completed",
"created_at": "2024-01-15T10:30:00Z",
"completed_at": "2024-01-15T10:32:15Z",
"results": {
"download_speed_mbps": 95.4,
"bytes_downloaded": 1073741824,
"duration_seconds": 89.2,
"success": true
}
},
{
"id": "diag_12346",
"serial_number": "SN987654321",
"operation": "ipping",
"target": "8.8.8.8",
"count": 5,
"size": 64,
"timeout": 1,
"status": "completed",
"created_at": "2024-01-15T11:15:00Z",
"completed_at": "2024-01-15T11:15:08Z",
"results": {
"packets_sent": 5,
"packets_received": 5,
"packet_loss_percent": 0,
"min_rtt_ms": 12.4,
"max_rtt_ms": 15.8,
"avg_rtt_ms": 14.1,
"success": true
}
}
]
Example Response - WiFi Neighbor Scan:
[
{
"id": "diag_12347",
"serial_number": "SN555666777",
"operation": "wifi.neighbor",
"target": "2.4GHz",
"status": "completed",
"created_at": "2024-01-15T12:00:00Z",
"completed_at": "2024-01-15T12:00:45Z",
"results": {
"networks_found": 12,
"strongest_signal_dbm": -35,
"channel_utilization": {
"1": 25,
"6": 60,
"11": 45
},
"recommended_channel": 1,
"success": true
}
}
]
Response Codes:
Common Use Cases
Use Case 1: RemoteCustomer ConnectivitySpeed Complaint Troubleshooting
When acustomers devicereport reportsslow connectivityinternet issues,speeds, 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 throughputthroughput, performancethen ofcompare devices,results useful for validatingagainst service level agreements andto identifyingidentify bandwidthif bottlenecks.the issue is network-related or device-specific.
Use Case 2: Device Connectivity Verification
For devices that appear offline or unreachable, execute ping tests to multiple targets (gateway, DNS servers, public IPs) to isolate whether the issue is local network connectivity, ISP routing, or device configuration.
Use Case 3: WiFi EnvironmentPerformance AnalysisOptimization
UseBefore deploying new wireless equipment or when customers report WiFi neighbor diagnostics toissues, scan forneighboring nearbynetworks access points,to identify channel interference,congestion and optimizeinterference wirelesssources, performancethen forrecommend devicesoptimal inchannel dense RF environments.configurations.
Use Case 4: AutomatedProactive HealthNetwork Monitoring
CreateSchedule scheduledregular diagnostic operationstests thatacross runyour periodicallydevice fleet to monitorestablish devicebaseline health,performance combining ping tests for connectivity, DNS lookups for name resolution,metrics and interface-specificidentify tests.degrading connections before customers experience service issues.
Use Case 5: NetworkDNS Resolution Troubleshooting Workflow
ImplementWhen acustomers systematicexperience troubleshootingweb approachbrowsing byissues, firsttest retrievingDNS existinglookup diagnosticperformance results,against thenmultiple schedulingDNS new tests based on the findings, and finally updating device statusservers to reflectidentify currentresolution conditions.failures or slow response times that could impact user experience.
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
update_status=true