Inventory Device Serial Diags
The Inventory Device Serial Diagnostics API provides access to diagnostic information and testing capabilities for devices in your inventory. These endpoints enable you to retrieve diagnostic data from devices and trigger new diagnostic tests to monitor device health and 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 is designed for managing and monitoring the diagnostic status of network devices in your inventory. This API category allows you to:
- Retrieve Diagnostic Information: Access current and historical diagnostic data for devices, including connection status, performance metrics, and error logs
- Trigger Diagnostic Tests: Initiate new diagnostic procedures to test device connectivity, functionality, and performance
- Monitor Device Health: Get real-time updates on device status and identify potential issues before they impact operations
These endpoints work together to provide comprehensive device monitoring capabilities. The GET endpoint retrieves existing diagnostic information, while the POST endpoint allows you to schedule new diagnostic tests. The update_status parameter enables real-time status updates by running configured diagnostic helpers before returning data.
Common scenarios include automated health monitoring, troubleshooting connectivity issues, and maintaining device inventory accuracy through regular diagnostic checks.
Endpoints
GET /inventory_device_serial_diags/
Description: Retrieves diagnostic information for inventory devices. This endpoint returns diagnostic data including device status, connectivity tests, performance metrics, and error logs. You can filter results by specific device IDs and optionally trigger real-time status updates.
Use Cases:
- Monitor device health across your entire inventory
- Retrieve diagnostic history for specific devices during troubleshooting
- Get real-time device status updates for critical infrastructure monitoring
- Generate reports on device performance and connectivity
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 device or scheduled transaction to retrieve diagnostics for |
| update_status | boolean | query | No | When true, runs configured diagnostic helpers to update device status before returning results. Useful for real-time monitoring but may increase response time |
cURL Example:
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_serial_diags/?id=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",
"device_id": "DEV-001",
"serial_number": "SN123456789",
"device_name": "Core Switch 01",
"diagnostic_type": "connectivity_test",
"status": "passed",
"last_updated": "2024-01-15T14:30:00Z",
"response_time_ms": 45,
"error_count": 0,
"details": {
"ping_test": "success",
"snmp_connectivity": "success",
"uptime_seconds": 2547600,
"cpu_usage_percent": 12.5,
"memory_usage_percent": 34.2
},
"scheduled_transaction_id": "ST-789"
},
{
"id": "12346",
"device_id": "DEV-002",
"serial_number": "SN987654321",
"device_name": "Access Point 02",
"diagnostic_type": "performance_test",
"status": "warning",
"last_updated": "2024-01-15T14:25:00Z",
"response_time_ms": 120,
"error_count": 2,
"details": {
"ping_test": "success",
"snmp_connectivity": "timeout",
"signal_strength_dbm": -65,
"client_count": 23,
"bandwidth_utilization_percent": 78
},
"scheduled_transaction_id": "ST-790"
}
]
}
Response Codes:
| Status | Description |
|---|---|
| 200 | Success - Returns diagnostic data for the specified devices |
| 401 | Unauthorized - Invalid or missing authentication token |
| 404 | Not Found - No diagnostic data found for the specified ID |
| 500 | Server Error - Diagnostic service temporarily unavailable |
POST /inventory_device_serial_diags/
Description: Creates a new diagnostic test request for one or more devices in your inventory. This endpoint schedules diagnostic procedures such as connectivity tests, performance monitoring, or custom diagnostic scripts. The diagnostic data provided should specify the devices to test and the type of diagnostics to perform.
Use Cases:
- Schedule regular diagnostic checks for critical network equipment
- Trigger immediate diagnostic tests when issues are reported
- Run batch diagnostics across multiple devices after maintenance
- Initiate custom diagnostic procedures for specific device types
Full URL Example:
https://control.zequenze.com/api/v1/inventory_device_serial_diags/
Parameters:
| Parameter | Type | In | Required | Description |
|---|---|---|---|---|
| data | string | body | Yes | JSON string containing diagnostic request information including device IDs, diagnostic types, and test parameters |
cURL Example:
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 '{
"devices": [
{
"device_id": "DEV-003",
"serial_number": "SN555666777"
}
],
"diagnostic_type": "full_system_check",
"priority": "high",
"schedule_immediately": true,
"test_parameters": {
"include_performance": true,
"include_connectivity": true,
"include_security_scan": false,
"timeout_seconds": 300
}
}'
Example Response:
{
"transaction_id": "ST-791",
"status": "scheduled",
"message": "Diagnostic test scheduled successfully",
"devices_count": 1,
"estimated_completion": "2024-01-15T15:15:00Z",
"diagnostic_details": {
"diagnostic_type": "full_system_check",
"priority": "high",
"created_at": "2024-01-15T15:00:00Z",
"scheduled_devices": [
{
"device_id": "DEV-003",
"serial_number": "SN555666777",
"device_name": "Router 03",
"test_status": "queued"
}
]
}
}
Response Codes:
| Status | Description |
|---|---|
| 201 | Created - Diagnostic test successfully scheduled |
| 400 | Bad Request - Invalid data format or missing required parameters |
| 401 | Unauthorized - Invalid or missing authentication token |
| 422 | Unprocessable Entity - Valid format but logical errors in request data |
| 500 | Server Error - Unable to schedule diagnostic test |
Common Use Cases
Use Case 1: Real-time Device Health Monitoring
Monitor critical network devices by regularly calling the GET endpoint with update_status=true to get current diagnostic information and identify devices that may need attention.
Use Case 2: Scheduled Maintenance Diagnostics
Before and after scheduled maintenance windows, use the POST endpoint to trigger comprehensive diagnostic tests, then monitor results through the GET endpoint to verify all systems are functioning properly.
Use Case 3: Troubleshooting Workflow
When users report connectivity issues, use the POST endpoint to immediately schedule diagnostic tests for affected devices, then poll the GET endpoint to retrieve detailed diagnostic results for troubleshooting.
Use Case 4: Inventory Health Reporting
Generate regular reports by retrieving diagnostic data for all devices using the GET endpoint, then analyzing the results to identify trends, recurring issues, or devices requiring replacement.
Use Case 5: Automated Alert System
Implement automated monitoring by combining both endpoints: use POST to schedule regular diagnostic tests, then GET to retrieve results and trigger alerts when devices fail diagnostic checks.
Best Practices
- Use Pagination: When retrieving diagnostics for large inventories, implement proper pagination to avoid timeouts and improve performance
- Monitor Rate Limits: Space out diagnostic requests to avoid overwhelming devices or the API service
- Handle Async Operations: Diagnostic tests may take time to complete; implement proper polling mechanisms when checking results after scheduling tests
- Cache Results: Cache diagnostic data when appropriate to reduce API calls, especially for devices that don't change frequently
- Error Handling: Implement robust error handling for network timeouts, device unavailability, and service interruptions
-
Selective Updates: Use the
update_statusparameter judiciously as it increases response time; only use when real-time data is essential - Batch Operations: When possible, include multiple devices in a single POST request rather than making individual calls for each device