Skip to main content

Inventory Device Diags

The inventoryInventory deviceDevice diagnosticsDiagnostics endpointsAPI provideenables accessyou to deviceconfigure and manage network diagnostic informationtests andon statusmanaged updates within your inventory system.devices. These endpoints allow you to retrieveschedule diagnostic dataoperations forlike devicesbandwidth tests, connectivity checks, and createnetwork newtroubleshooting diagnosticdirectly entries,on withcustomer optionalpremises real-timeequipment status(CPE) updatesfrom usingyour configuredcontrol helpers.platform.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The inventoryInventory deviceDevice diagnosticsDiagnostics API enablesprovides comprehensive monitoringnetwork anddiagnostic managementcapabilities offor devicemanaged healthdevices and status information acrossin your organization's inventory. This API category isallows essentialyou forto maintainingremotely visibilityexecute intovarious devicediagnostic tests on customer premises equipment (CPE) to troubleshoot connectivity issues, measure network performance, troubleshooting issues, and ensuringgather optimaldetailed devicenetwork operations.information.

Key capabilities include:Features:

  • RetrievingExecute multiple diagnostic dataoperations: forHTTP download/upload tests, ICMP ping, UDP echo tests, traceroute, DNS lookups, and WiFi neighbor scans
Configure test parameters like packet count, size, timeout values, and connection settings Target specific devicesnetwork orinterfaces allon devices in inventory Creating newRetrieve diagnostic entriesresults to trackand device issues or maintenance activities Real-time status updates using configured diagnostic helpers Monitoring device health trends and identifying potential problems before they impact operationsinformation

These endpoints work together to provide a complete diagnostic workflow - you can query existing diagnostic information to understand current device status, then create new diagnostic entries when issues are identified or maintenance is performed. The optional status update feature ensures you always have the most current device information available.

Common integrationUse scenarios:Cases:

  • Automated monitoringNetwork systemsTroubleshooting: thatWhen periodicallycustomers checkreport connectivity issues, quickly run ping, traceroute, or DNS lookup tests to identify problems
Performance Monitoring: Schedule regular bandwidth tests using download/upload operations to monitor service quality WiFi Environment Analysis: Use WiFi neighbor diagnostics to analyze interference and optimize wireless settings Service Validation: Verify network connectivity and performance after device statusinstallations or configuration changes Help desk applications that need to view device

The diagnostic historyoperations

Maintenanceare managementexecuted systemsdirectly thaton createthe diagnostictarget recordsdevices, Dashboard applications displayingproviding real-time devicenetwork healthinsights metricsfrom the customer's actual network environment.

Endpoints

GET /inventory_device_diags/

Description: Retrieves a list of configured diagnostic informationoperations for devices in your inventory. This endpoint supportsallows filteringyou byto specificview deviceexisting IDsdiagnostic configurations and can optionally update device status in real-time using configured diagnostic helpersinformation before returning theresults. data.Use this to monitor scheduled diagnostics or review diagnostic configurations across your managed devices.

Use Cases:

  • MonitorReview all configured diagnostic tests across your device inventory
Check the health status of all devices inbefore yourplanning inventorynew diagnostic operations RetrieveAudit diagnostic historyconfigurations for acompliance specific device duringor troubleshooting purposes BuildMonitor dashboardongoing displaysdiagnostic showingoperations currentand devicetheir status across your organization Automated monitoring systems checking for device issuesparameters

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_diags/?id=device-12345&update_status=true

Parameters:

Parameter Type In Required Description
id string query No IDFilter ofresults theto show diagnostics for a specific device toby retrieveits diagnostics for. If omitted, returns diagnostics for all devicesID
update_status boolean query No When set to true, uses configured diagnostic helpers to updaterefresh device status before returning data.diagnostic Useful for real-time monitoringinformation

cURL Example:

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

Example Response:

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
  {
    "id": 12345,
    "diag-001"operation": "download",
    "device_id"target": "device-12345"http://speedtest.example.com/download/test.bin",
    "device_name"upload_size": null,
    "count": null,
    "size": null,
    "timeout": null,
    "dns_server": null,
    "max_hops": null,
    "interface": "Office Printer HP-2024"eth0",
    "device_serial"number_of_connections": "HP123456789"4
  },
      "diagnostic_type": "health_check",
      "status": "warning",
      "details":
  {
    "cpu_usage"id": 45,12346,
    "memory_usage": 78,
        "disk_space": 23,
        "network_connectivity"operation": "good"ipping",
    "last_ping"target": "2024-01-15T14:25:00Z"8.8.8.8",
    "upload_size": null,
    "count": 10,
    "size": 64,
    "timeout": 3,
    "dns_server": null,
    "max_hops": null,
    "interface": "wan0",
    "number_of_connections": null
  },
  "issues": [
        {
    "severity"id": 12347,
    "operation": "medium"wifi.neighbor",
    "message"target": "Low disk space detected"channel_scan",
    "code"upload_size": null,
    "count": null,
    "size": null,
    "timeout": null,
    "dns_server": null,
    "max_hops": null,
    "interface": "DISK_LOW"wlan0",
    "number_of_connections": null
  }
],
      "created_at": "2024-01-15T14:25:00Z",
      "updated_at": "2024-01-15T14:25:00Z",
      "next_check_due": "2024-01-15T18:25:00Z"
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns array of diagnostic configurations
401 Unauthorized - Invalid or missing API token 500 Internal Server Error - Problem retrieving diagnostic data

POST /inventory_device_diags/

Description: Creates a new diagnostic operation configuration for requesteda devicesdevice. This endpoint allows you to schedule various network diagnostic tests including bandwidth measurements, connectivity tests, and network analysis operations. The diagnostic will be queued for execution on the target device according to the specified parameters.

Use Cases:

    Schedule bandwidth tests to measure download/upload speeds for service validation Configure ping tests to monitor connectivity to specific hosts or services Set up traceroute diagnostics to identify network path issues Create DNS lookup tests to troubleshoot name resolution problems Schedule WiFi neighbor scans to analyze wireless environment

    Full URL Example:

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

    Request Body Parameters:

    The request body should contain a JSON object with the diagnostic configuration:

    Parameter Type Required Description id integer Yes ID of the target device where the diagnostic will be executed operation string Yes Type of diagnostic operation. Allowed values: download, upload, ipping, udpecho, traceroute, dnslookup, wifi.neighbor target string Yes Target for the operation - URL for download/upload, IP for ping/traceroute, hostname for DNS lookup, or parameter for WiFi diagnostics upload_size string No Size in MB for upload operations (e.g., "10") 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 and DNS operations (default: 1) dns_server string No Specific DNS server IP for DNS lookup operations max_hops integer No Maximum hops for traceroute operations (default: 30) interface string No Network interface name to use for the operation number_of_connections integer No Number of concurrent connections for download/upload tests

    cURL Examples:

    Bandwidth Download Test:

    curl -X POST "https://control.zequenze.com/api/v1/inventory_device_diags/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 12345,
    "operation": "download",
    "target": "http://speedtest.example.com/download/100MB.bin",
    "interface": "eth0",
    "number_of_connections": 4
  }'

    Ping Connectivity Test:

    curl -X POST "https://control.zequenze.com/api/v1/inventory_device_diags/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 12346,
    "operation": "ipping",
    "target": "8.8.8.8",
    "count": 20,
    "size": 1024,
    "timeout": 3,
    "interface": "wan0"
  }'

    DNS Lookup Test:

    curl -X POST "https://control.zequenze.com/api/v1/inventory_device_diags/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 12347,
    "operation": "dnslookup",
    "target": "www.example.com",
    "count": 3,
    "timeout": 5,
    "dns_server": "1.1.1.1"
  }'

    Example Response:

    {
  "id": 12348,
  "operation": "download",
  "target": "http://speedtest.example.com/download/100MB.bin",
  "upload_size": null,
  "count": null,
  "size": null,
  "timeout": null,
  "dns_server": null,
  "max_hops": null,
  "interface": "eth0",
  "number_of_connections": 4
}

    Response Codes:

    Status Description 201 Created - Diagnostic operation successfully configured 400 Bad Request - Invalid parameters or missing required fields 401 Unauthorized - Invalid or missing API token 404 Not Found - Specified device ID does not exist 500 Internal Server Error - IssueProblem withcreating diagnostic helper configuration

    POST /inventory_device_diags/

    Description: Creates a new diagnostic entry for a device in your inventory. This endpoint allows you to record diagnostic information, maintenance activities, or issue reports for tracking device health over time.

    Use Cases:

      Log diagnostic results from manual device inspections Record maintenance activities performed on devices Create incident reports when device issues are discovered Integrate with automated monitoring tools to log diagnostic events

      Full URL Example:

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

      Parameters:

      Parameter Type In Required Description data string body Yes JSON string containing the diagnostic information to create. Must include device identification and diagnostic details

      cURL Example:

      curl -X POST "https://control.zequenze.com/api/v1/inventory_device_diags/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "device-12345",
    "diagnostic_type": "maintenance",
    "status": "completed",
    "details": {
      "action_performed": "firmware_update",
      "previous_version": "1.2.3",
      "new_version": "1.2.4",
      "duration_minutes": 15
    },
    "notes": "Firmware update completed successfully",
    "performed_by": "tech@company.com"
  }'

      Example Request Body:

      {
  "device_id": "device-12345",
  "diagnostic_type": "issue_report",
  "status": "open",
  "details": {
    "issue_category": "hardware",
    "symptoms": ["intermittent_connectivity", "slow_response"],
    "error_codes": ["ERR_NETWORK_001"],
    "impact_level": "medium"
  },
  "notes": "Device experiencing intermittent network connectivity issues. Users report slow response times during peak hours.",
  "reported_by": "helpdesk@company.com",
  "priority": "high"
}

      Example Response:

      {
  "id": "diag-002",
  "device_id": "device-12345",
  "device_name": "Office Printer HP-2024",
  "diagnostic_type": "issue_report",
  "status": "open",
  "details": {
    "issue_category": "hardware",
    "symptoms": ["intermittent_connectivity", "slow_response"],
    "error_codes": ["ERR_NETWORK_001"],
    "impact_level": "medium"
  },
  "notes": "Device experiencing intermittent network connectivity issues. Users report slow response times during peak hours.",
  "reported_by": "helpdesk@company.com",
  "priority": "high",
  "created_at": "2024-01-15T15:30:00Z",
  "updated_at": "2024-01-15T15:30:00Z"
}

      Response Codes:

      Status Description 201 Created - Diagnostic entry successfully created 400 Bad Request - Invalid or missing required data 401 Unauthorized - Invalid or missing API token 404 Not Found - Referenced device ID does not exist 422 Validation Error - Data format is incorrect

      Common Use Cases

      Use Case 1: Real-timeCustomer DeviceSpeed HealthComplaint MonitoringInvestigation

      BuildWhen a monitoringcustomer dashboardreports thatslow displaysinternet currentspeeds, create download and upload diagnostic tests to measure actual throughput from their device status acrossto your organization.test Useservers and identify if the GETissue endpointis with update_status=truedownload, toupload, ensureor you'reboth always showing the latest diagnostic information, and refresh the data every few minutes to maintain real-time visibility.directions.

      Use Case 2: MaintenanceConnectivity Workflow IntegrationTroubleshooting

      IntegrateIf a customer experiences intermittent connectivity issues, schedule ping tests to critical infrastructure (DNS servers, gateways, service endpoints) with yourincreased maintenancepacket managementcounts systemand varying sizes to automaticallyidentify createpacket diagnostic entries when maintenance is performed. Use the POST endpoint to log activities like firmware updates, hardware replacements,loss or routinelatency inspections, creating a complete maintenance history.patterns.

      Use Case 3: IncidentWiFi TrackingPerformance Optimization

      Before and Resolutionafter

      WhenWiFi usersconfiguration reportchanges, deviceuse issues,WiFi createneighbor diagnostic entriesdiagnostics to trackscan thefor probleminterference fromsources identificationand throughoptimal resolution.channel Startselection, with a POST requesthelping to logoptimize thewireless initialperformance issue,in thencrowded useRF GET requests to retrieve the diagnostic history during troubleshooting.environments.

      Use Case 4: AutomatedService IssueInstallation DetectionValidation

      SetAfter upinstalling automatednew monitoringequipment thator periodicallyservices, checksrun devicea statuscomprehensive diagnostic suite including ping tests to verify gateway connectivity, DNS lookups to confirm name resolution, and createsbandwidth diagnostic entries when issues are detected. Combine both endpoints - use GETtests to checkvalidate currentservice status,delivery then POST to create issue reports when problems are identified.speeds.

      Use Case 5: ComplianceProactive Network Monitoring

      Schedule regular diagnostic operations across your device inventory to proactively identify network degradation, plan capacity upgrades, and Auditmaintain Reportingservice

      Generatequality compliancebefore reportscustomers byexperience retrieving diagnostic history for specific devices or time periods. Use the GET endpoint with appropriate filtering to collect maintenance records and diagnostic data required for regulatory compliance or internal audits.issues.

      Best Practices

      Operation Selection:

      • Use paginationipping for largebasic inventoriesconnectivity -verification Whenand retrievinglatency diagnosticsmeasurement

      Use download/upload for manybandwidth devices, implement proper pagination using limitvalidation and offsetservice parametersspeed to avoid timeouts and improve performance. verification

      Leverage the update_status parameter judiciously - While real-time status updates provide current information, they can impact response times. Use update_status=truetraceroute only when you need to identify where in the mostnetwork currentpath data.

      issues occur Use wifi.neighbor for wireless environment analysis and channel optimization

      StructureParameter diagnosticConfiguration:

      data
      consistentlyFor ping operations, use count values of 10-20 for reliable statistics while avoiding network flooding Set appropriate timeouts based on expected network conditions (3-5 seconds for typical broadband) When testing bandwidth, use multiple connections (2-8) to better utilize available capacity Specify network interfaces when devices have multiple connection paths

      Error Handling:

      -
      WhenAlways validate device IDs exist before creating diagnostic entries, use consistent field names and data structures in the details object to enable better searching and reporting across your diagnostic history. operations Handle

      Implement404 properresponses errorgracefully handling - Always check response codes and handle cases wherewhen devices mightare not existoffline or diagnosticunreachable

      helpers might be unavailable. BuildImplement retry logic for temporary network orissues serviceduring issues.diagnostic execution Monitor diagnostic results and alert on repeated failures indicating persistent issues

      CachePerformance Considerations:

        Avoid scheduling too many simultaneous diagnostics on the same device Space out bandwidth-intensive tests (download/upload) to prevent network congestion Use the update_status parameter judiciously as it adds processing time to GET requests Consider rate limiting diagnostic data appropriately - For dashboard applications, consider caching diagnostic data with appropriate TTL valuescreation to reduceprevent APIoverwhelming callsdevice while maintaining reasonable data freshness.

        Use meaningful diagnostic types - Establish standard diagnostic_type values (like "health_check", "maintenance", "issue_report") to enable better filtering and categorization of diagnostic data.

        resources
        Back to top