Skip to main content

Inventory Device Diags

The inventory device diagnostics endpoints provide access to device diagnostic information and status updates within your inventory system. These endpoints allow you to retrieve diagnostic data for devices and create new diagnostic entries, with optional real-time status updates using configured helpers.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The inventory device diagnostics API enables comprehensive monitoring and management of device health and status information across your organization's inventory. This API category is essential for maintaining visibility into device performance, troubleshooting issues, and ensuring optimal device operations.

Key capabilities include:

  • Retrieving diagnostic data for specific devices or all devices in inventory
  • Creating new diagnostic entries to track device issues or maintenance activities
  • Real-time status updates using configured diagnostic helpers
  • Monitoring device health trends and identifying potential problems before they impact operations

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 integration scenarios:

  • Automated monitoring systems that periodically check device status
  • Help desk applications that need to view device diagnostic history
  • Maintenance management systems that create diagnostic records
  • Dashboard applications displaying real-time device health metrics

Endpoints

GET /inventory_device_diags/

Description: Retrieves diagnostic information for devices in your inventory. This endpoint supports filtering by specific device IDs and can optionally update device status in real-time using configured diagnostic helpers before returning the data.

Use Cases:

  • Monitor the health status of all devices in your inventory
  • Retrieve diagnostic history for a specific device during troubleshooting
  • Build dashboard displays showing current device status across your organization
  • Automated monitoring systems checking for device issues

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 ID of the specific device to retrieve diagnostics for. If omitted, returns diagnostics for all devices
update_status boolean query No When true, uses configured diagnostic helpers to update device status before returning data. Useful for real-time monitoring

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": "diag-001",
      "device_id": "device-12345",
      "device_name": "Office Printer HP-2024",
      "device_serial": "HP123456789",
      "diagnostic_type": "health_check",
      "status": "warning",
      "details": {
        "cpu_usage": 45,
        "memory_usage": 78,
        "disk_space": 23,
        "network_connectivity": "good",
        "last_ping": "2024-01-15T14:25:00Z"
      },
      "issues": [
        {
          "severity": "medium",
          "message": "Low disk space detected",
          "code": "DISK_LOW"
        }
      ],
      "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 diagnostic data for requested devices
401 Unauthorized - Invalid or missing API token
404 Not Found - Specified device ID does not exist
500 Server Error - Issue with 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-time Device Health Monitoring

Build a monitoring dashboard that displays current device status across your organization. Use the GET endpoint with update_status=true to ensure you're always showing the latest diagnostic information, and refresh the data every few minutes to maintain real-time visibility.

Use Case 2: Maintenance Workflow Integration

Integrate with your maintenance management system to automatically create diagnostic entries when maintenance is performed. Use the POST endpoint to log activities like firmware updates, hardware replacements, or routine inspections, creating a complete maintenance history.

Use Case 3: Incident Tracking and Resolution

When users report device issues, create diagnostic entries to track the problem from identification through resolution. Start with a POST request to log the initial issue, then use GET requests to retrieve the diagnostic history during troubleshooting.

Use Case 4: Automated Issue Detection

Set up automated monitoring that periodically checks device status and creates diagnostic entries when issues are detected. Combine both endpoints - use GET to check current status, then POST to create issue reports when problems are identified.

Use Case 5: Compliance and Audit Reporting

Generate compliance reports by 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.

Best Practices

  • Use pagination for large inventories - When retrieving diagnostics for many devices, implement proper pagination using limit and offset parameters to avoid timeouts and improve performance.

  • Leverage the update_status parameter judiciously - While real-time status updates provide current information, they can impact response times. Use update_status=true only when you need the most current data.

  • Structure diagnostic data consistently - When creating diagnostic entries, use consistent field names and data structures in the details object to enable better searching and reporting across your diagnostic history.

  • Implement proper error handling - Always check response codes and handle cases where devices might not exist or diagnostic helpers might be unavailable. Build retry logic for temporary network or service issues.

  • Cache diagnostic data appropriately - For dashboard applications, consider caching diagnostic data with appropriate TTL values to reduce API calls 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.

Back to top