Inventory Device Name Diags
Endpoints Summary
POST
/inventory_device_name_diags/
Swagger ↗
GET
/inventory_device_name_diags/
Swagger ↗
The
inventoryInventorydeviceDevicenameNamediagnosticsDiagnostics API provides endpointsenableforyou to executescheduling andmanagemonitoring network diagnostic operations on specificdevicesnetworkin your inventory.devices. These endpoints allow you toperforminitiate various network testsincludingsuch as ping, traceroute, speed tests,connectivity checks,and WiFidiagnosticsdiagnostics,toastroubleshootwelldeviceasperformanceretrieve the status andnetworkresultsissues.of previously scheduled diagnostic operations.
Base URL: https://control.zequenze.com/api/v1
Authentication: All endpoints require a Bearer token:
Authorization: Bearer <your-api-token>
Overview
The inventoryInventory deviceDevice nameName Diagnostics API enables network administrators and developers to perform comprehensive network diagnostics on managed devices remotely. This API providescategory ais comprehensiveessential suite offor network diagnosticmonitoring, toolstroubleshooting forconnectivity managingissues, and troubleshootingperforming devices in yourroutine network inventory.health 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.checks.
Key Features:
- Remote Diagnostics: Execute network tests on devices without physical access
Common Integration Scenarios:
The API follows a simple pattern: use POST to schedule new diagnostic operations and GET to retrieve status updates and results. Each diagnostic operation is tied to a specific device name and can be configured with operation-specific parameters.
Endpoints
POST /inventory_device_name_diags/
Description: Schedules a new network diagnostic operation on a specified device. This endpoint allows you to initiate various types of network tests including connectivity checks, performance measurements, and WiFi diagnostics. The operation is queued and executed asynchronously on the target device.
Use Cases:
NetworkTroubleshoot connectivity issues by running ping or traceroute tests
TheFull endpointsURL workExample:
https://control.zequenze.com/api/v1/inventory_device_name_diags/
Request Body Schema:
cURL Example (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": "router-main-office",
"operation": "ipping",
"target": "8.8.8.8",
"count": 10,
"size": 64,
"timeout": 2
}'
cURL Example (Speed 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": "cpe-customer-001",
"operation": "download",
"target": "http://speedtest.example.com/test-file.zip",
"interface": "eth0"
}'
Example Response:
{
"name": "router-main-office",
"operation": "ipping",
"target": "8.8.8.8",
"count": 10,
"size": 64,
"timeout": 2,
"upload_size": null,
"max_hops": null,
"interface": null
}
Response Codes:
Endpoints
GET /inventory_device_name_diags/
Description: Retrieves athe liststatus and results of networkscheduled diagnostic operations. This endpoint can return all diagnostic operations foror devicesfilter inby yourspecific inventory.transaction ThisID. endpointUse allows youthis to viewmonitor scheduled,the running,progress or completed diagnosticof tests and optionallycollect refreshresults deviceonce statusoperations informationare before returning results.complete.
Use Cases:
- Monitor the status of
ongoingrecently scheduled diagnostic operations Review historical diagnosticRetrieve test results for analysis and reporting- Check
scheduledif devices are responding to diagnostictasks before creating new onesrequests - Update device connectivity status
asinpartmonitoringof diagnostic reportingsystems
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 | |
| update_status | boolean | query | No |
cURL Example:Example (All Operations):
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_name_diags/" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json"
cURL Example (Specific Operation):
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_name_diags/?id=diag_12345&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"main-office",
"operation": "ipping",
"target": "8.8.8.8",
"count": 10,
"size": 64,
"timeout": 1,2,
"upload_size": null,
"max_hops": null,
"interface": null,
"upload_size"status": null"completed",
"results": {
"packets_sent": 10,
"packets_received": 10,
"packet_loss": "0%",
"avg_rtt": "12.5ms",
"min_rtt": "11.2ms",
"max_rtt": "15.1ms"
},
"created_at": "2024-01-15T10:30:00Z",
"completed_at": "2024-01-15T10:30:15Z"
},
{
"name": "branch-gateway-02"cpe-customer-001",
"operation": "wifi.neighbor"download",
"target": "channel_scan"http://speedtest.example.com/test-file.zip",
"upload_size": null,
"count": null,
"size": null,
"timeout": null,
"max_hops": null,
"interface": "wlan0"eth0",
"upload_size"status": "running",
"results": null,
"created_at": "2024-01-15T10:35:00Z",
"completed_at": null
}
]
Response Codes:
| Status | Description |
|---|---|
| 200 | Success - Returns |
| 401 | Unauthorized - Invalid or missing |
| 404 | Not Found - |
Common Use Cases
POSTUse /inventory_device_name_diags/Case 1: Automated Connectivity Monitoring
Description:Schedule Createsperiodic 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:
Full URL Example:users.
https://control.zequenze.com/api/v1/inventory_device_name_diags/# Request Body Parameters:
downloaduploadippingudpechotraceroutednslookupwifi.neighborcURL Example - HTTP Download Test:
curl -Xtest
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-core-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": 25
}'
# Check results
GET /inventory_device_name_diags/?id=<transaction_id>
Use Case 2: Customer Support Troubleshooting
cURLWhen Examplea -customer WiFireports Neighborslow Scan:internet, initiate speed tests and traceroute diagnostics to identify the source of performance issues.
curl# -XRun download speed test
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"cpe-12345",
"operation": "download",
"target": "http://speedtest.example.com/100mb.local/100MB.bin",
"upload_size": null,
"count": null,
"size": null,
"timeout": null,
"max_hops": null,
"interface": "eth0"
}
Response Codes:
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 useRun traceroute to identify whererouting packetsissues
arePOST being/inventory_device_name_diags/
dropped{
or"name": delayed.
Use Case 3: WiFi Environment Analysis
For wireless network optimization, useAnalyze WiFi neighbornetworks diagnosticsin the area to scantroubleshoot interference issues or optimize channel selection.
# Scan for interferenceneighboring andWiFi analyzenetworks
channelPOST utilization./inventory_device_name_diags/
This{
helps"name": identify"office-ap-01",
optimal"operation": channel"wifi.neighbor",
assignments"target": and"2.4GHz"
detect}
rogue access points.Use Case 4: DNS Resolution MonitoringVerification
EnsureVerify reliablethat devices can properly resolve domain names, which is critical for internet accessconnectivity.
# testingTest DNS lookupresolution
performancePOST against/inventory_device_name_diags/
multiple{
DNS"name": servers."branch-router",
Use"operation": this"dnslookup",
to"target": identify"google.com",
DNS-related"count": connectivity3,
issues"timeout": and5
optimize}
DNS server configurations.Use Case 5: ScheduledNetwork HealthPerformance ChecksBaseline
ImplementEstablish automatedperformance network health monitoringbaselines by combiningrunning deviceregular statusupload/download updatestests withduring diagnosticdifferent operations.times Useof theday.
update_status# Upload speed test POST /inventory_device_name_diags/ { "name": "test-device", "operation": "upload", "target": "http://speedtest.local/upload", "upload_size": "50" }parameter to refresh device information before executing diagnostics.
Best Practices
-
Operation
Selection:Scheduling:ChooseAvoid scheduling multiple intensive operations (like speed tests) simultaneously on theappropriatesamediagnosticdeviceoperationtoforpreventyourresourceuse case. Useippingfor basic connectivity,traceroutefor routing analysis, anddownload/uploadfor performance testingconflicts -
ParameterTimeoutOptimization:Configuration:AdjustSet appropriate timeout values based on networkconditions.conditionsIncrease- use longer timeouts for satellite or high-latency connectionsand reduce packet counts for faster results -
Interface
Specification:Selection:Always specifySpecify the interface parameter when testing specific networkpaths,pathsespeciallyoron multi-homedwhen deviceswithhave multiple networkconnectionsinterfaces -
RateResultLimiting:Polling:AvoidWhen checking results with GET requests, implement reasonable polling intervals (30-60 seconds) to avoid overwhelmingdevicestheby spacing diagnostic operations appropriately. Consider device capabilities when scheduling multiple concurrent testsAPI -
Error
Handling:Handling:ImplementAlwaysretrychecklogictheforoperationfailedstatusoperations,beforebutprocessingincluderesultsexponential-backoffoperations may fail due topreventdeviceoverwhelming devicesconnectivity ornetworkconfigurationinfrastructureissues - Resource Management: Speed tests can consume significant bandwidth - schedule them during maintenance windows when possible
update_status=true parameter