Skip to main content

Inventory Device

The Inventory Device API provides comprehensive management capabilities for network devices within your infrastructure. These endpoints enable you to retrieve, create, update, and delete device records, monitor device status, and track organizational device inventory with advanced filtering options.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device API is the core interface for managing network devices in your infrastructure monitoring system. This API category allows you to maintain a complete inventory of network devices including routers, switches, servers, and other network equipment across different organizations.

Key Capabilities:

  • Device Management: Create, read, update, and delete device records with comprehensive metadata
  • Status Monitoring: Track device status (Up/Down) and monitor status changes over time
  • Organizational Filtering: Manage devices across multiple organizations with role-based access
  • Real-time Updates: Optionally update device status in real-time when retrieving device information
  • Pending Configuration Tracking: Monitor devices that have pending configuration changes

Common Integration Scenarios:

  • Network monitoring dashboards that need to display device inventory and status
  • Automated provisioning systems that register new devices
  • Maintenance workflows that update device configurations and track changes
  • Reporting systems that generate device inventory reports by organization or status
  • Alert systems that need to correlate device information with monitoring events

The API supports both individual device operations and bulk operations with advanced filtering, making it suitable for both real-time applications and batch processing workflows.

Endpoints

GET /inventory_device/

Description: Retrieves a paginated list of inventory devices with comprehensive filtering options. This endpoint is essential for building device dashboards, generating reports, and synchronizing device inventories with external systems.

Use Cases:

  • Building network monitoring dashboards that display device status across organizations
  • Generating inventory reports filtered by device type, status, or organization
  • Synchronizing device data with external CMDB or asset management systems
  • Monitoring devices with pending configuration changes

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device/?organization=123&status=true&limit=50&offset=0

Parameters:

Parameter Type In Required Description
type integer query No Filter devices by device type ID (e.g., router=1, switch=2, server=3)
status string query No Filter by device status. Use '1'/'true'/'True' for Up devices, '0'/'false'/'False' for Down devices
last_status_change_from string query No Filter devices with status changes after specified datetime (ISO format: 2000-01-01T00:01:00+00:00)
organization integer query No Filter devices by organization ID for multi-tenant environments
limit integer query No Number of results per page (default: 20, max: 100)
offset integer query No Starting index for pagination (use with limit for page navigation)
pending boolean query No Filter devices that have pending configuration changes (true/false)
update_status boolean query No Perform real-time status check before returning results (may increase response time)

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device/?organization=123&status=true&limit=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 156,
  "next": "https://control.zequenze.com/api/v1/inventory_device/?limit=20&offset=20&organization=123&status=true",
  "previous": null,
  "results": [
    {
      "id": 1001,
      "name": "core-router-01",
      "hostname": "192.168.1.1",
      "serial_number": "RT5500-ABC123",
      "type": {
        "id": 1,
        "name": "Router",
        "model": "Cisco ISR 4451"
      },
      "organization": {
        "id": 123,
        "name": "Headquarters Network"
      },
      "status": true,
      "last_status_change": "2024-01-15T08:30:00Z",
      "pending_config": false,
      "location": "Data Center A - Rack 10",
      "created_at": "2024-01-10T14:20:00Z",
      "updated_at": "2024-01-15T08:30:00Z"
    },
    {
      "id": 1002,
      "name": "access-switch-02", 
      "hostname": "192.168.1.10",
      "serial_number": "SW2960-DEF456",
      "type": {
        "id": 2,
        "name": "Switch",
        "model": "Cisco Catalyst 2960"
      },
      "organization": {
        "id": 123,
        "name": "Headquarters Network"
      },
      "status": true,
      "last_status_change": "2024-01-14T16:45:00Z",
      "pending_config": true,
      "location": "Floor 2 - IDF Room",
      "created_at": "2024-01-08T09:15:00Z",
      "updated_at": "2024-01-15T07:20:00Z"
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns paginated device list
400 Bad Request - Invalid filter parameters
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient permissions for requested organization

POST /inventory_device/

Description: Creates a new device record in the inventory system. This endpoint is used when provisioning new network equipment or registering existing devices for monitoring.

Use Cases:

  • Automated device provisioning during network expansion
  • Bulk device registration from discovery tools
  • Manual device registration through management interfaces
  • Integration with procurement systems for new equipment tracking

Full URL Example:

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

Parameters:

Parameter Type In Required Description
data object body Yes JSON object containing device information including name, hostname, type, organization, and optional metadata

cURL Example:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new-firewall-01",
    "hostname": "192.168.1.100",
    "serial_number": "FW7000-GHI789",
    "type": 3,
    "organization": 123,
    "location": "Data Center B - Rack 5",
    "status": true
  }'

Example Request Body:

{
  "name": "new-firewall-01",
  "hostname": "192.168.1.100", 
  "serial_number": "FW7000-GHI789",
  "type": 3,
  "organization": 123,
  "location": "Data Center B - Rack 5",
  "status": true,
  "description": "Primary firewall for DMZ network"
}

Example Response:

{
  "id": 1003,
  "name": "new-firewall-01",
  "hostname": "192.168.1.100",
  "serial_number": "FW7000-GHI789",
  "type": {
    "id": 3,
    "name": "Firewall",
    "model": "Fortinet FortiGate 600E"
  },
  "organization": {
    "id": 123,
    "name": "Headquarters Network"
  },
  "status": true,
  "last_status_change": "2024-01-15T10:45:00Z",
  "pending_config": false,
  "location": "Data Center B - Rack 5",
  "description": "Primary firewall for DMZ network",
  "created_at": "2024-01-15T10:45:00Z",
  "updated_at": "2024-01-15T10:45:00Z"
}

Response Codes:

Status Description
201 Created - Device successfully created
400 Bad Request - Invalid or missing required fields
401 Unauthorized - Invalid or missing API token
409 Conflict - Device with same hostname or serial number already exists

GET /inventory_device/{id}/

Description: Retrieves detailed information for a specific device by its unique identifier. This endpoint provides complete device metadata and supports real-time status updates.

Use Cases:

  • Device detail pages in management interfaces
  • Real-time device monitoring and status checking
  • Configuration management workflows
  • Troubleshooting and device diagnostics

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device/1001/?update_status=true&pending=true

Parameters:

Parameter Type In Required Description
id integer path Yes Unique identifier of the device to retrieve
pending boolean query No Include detailed information about pending configuration changes
update_status boolean query No Perform real-time status check before returning device information

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device/1001/?update_status=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "id": 1001,
  "name": "core-router-01",
  "hostname": "192.168.1.1",
  "serial_number": "RT5500-ABC123",
  "mac_address": "00:1B:44:11:3A:B7",
  "type": {
    "id": 1,
    "name": "Router",
    "model": "Cisco ISR 4451",
    "manufacturer": "Cisco Systems"
  },
  "organization": {
    "id": 123,
    "name": "Headquarters Network",
    "contact_email": "netadmin@company.com"
  },
  "status": true,
  "last_status_change": "2024-01-15T08:30:00Z",
  "uptime": "45 days, 12:30:15",
  "pending_config": false,
  "pending_details": [],
  "location": "Data Center A - Rack 10",
  "description": "Primary core router handling inter-VLAN routing",
  "firmware_version": "16.12.05",
  "management_ip": "192.168.100.1",
  "snmp_community": "public",
  "created_at": "2024-01-10T14:20:00Z",
  "updated_at": "2024-01-15T10:45:00Z",
  "last_seen": "2024-01-15T10:45:00Z"
}

Response Codes:

Status Description
200 Success - Returns complete device information
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient permissions to view this device
404 Not Found - Device with specified ID does not exist

PUT /inventory_device/{id}/

Description: Completely updates an existing device record, replacing all fields with the provided data. This endpoint requires all mandatory fields to be included in the request.

Use Cases:

  • Complete device reconfiguration after hardware replacement
  • Bulk device updates from configuration management systems
  • Device migration between organizations or locations
  • Comprehensive device metadata synchronization

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device/1001/

Parameters:

Parameter Type In Required Description
id integer path Yes Unique identifier of the device to update
data object body Yes Complete device object with all required fields

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device/1001/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "core-router-01-updated",
    "hostname": "192.168.1.1",
    "serial_number": "RT5500-ABC123",
    "type": 1,
    "organization": 123,
    "status": true,
    "location": "Data Center A - Rack 12",
    "description": "Updated primary core router with new firmware"
  }'

Example Request Body:

{
  "name": "core-router-01-updated",
  "hostname": "192.168.1.1",
  "serial_number": "RT5500-ABC123",
  "mac_address": "00:1B:44:11:3A:B7",
  "type": 1,
  "organization": 123,
  "status": true,
  "location": "Data Center A - Rack 12",
  "description": "Updated primary core router with new firmware",
  "firmware_version": "16.12.08",
  "management_ip": "192.168.100.1"
}

Example Response:

{
  "id": 1001,
  "name": "core-router-01-updated",
  "hostname": "192.168.1.1",
  "serial_number": "RT5500-ABC123",
  "mac_address": "00:1B:44:11:3A:B7",
  "type": {
    "id": 1,
    "name": "Router",
    "model": "Cisco ISR 4451"
  },
  "organization": {
    "id": 123,
    "name": "Headquarters Network"
  },
  "status": true,
  "last_status_change": "2024-01-15T08:30:00Z",
  "pending_config": false,
  "location": "Data Center A - Rack 12",
  "description": "Updated primary core router with new firmware",
  "firmware_version": "16.12.08",
  "management_ip": "192.168.100.1",
  "created_at": "2024-01-10T14:20:00Z",
  "updated_at": "2024-01-15T11:30:00Z"
}

Response Codes:

Status Description
200 Success - Device successfully updated
400 Bad Request - Invalid or missing required fields
401 Unauthorized - Invalid or missing API token
404 Not Found - Device with specified ID does not exist

PATCH /inventory_device/{id}/

Description: Partially updates specific fields of an existing device record without affecting other fields. This endpoint is ideal for targeted updates such as status changes, location moves, or individual field corrections.

Use Cases:

  • Status updates from monitoring systems
  • Location changes during device moves
  • Firmware version updates after upgrades
  • Individual field corrections without full record replacement

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device/1001/

Parameters:

Parameter Type In Required Description
id integer path Yes Unique identifier of the device to update
data object body Yes JSON object containing only the fields to be updated

cURL Example:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device/1001/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": false,
    "location": "Data Center C - Rack 15",
    "firmware_version": "16.12.09"
  }'

Example Request Body:

{
  "status": false,
  "location": "Data Center C - Rack 15", 
  "firmware_version": "16.12.09",
  "description": "Router relocated to backup data center"
}

Example Response:

{
  "id": 1001,
  "name": "core-router-01-updated",
  "hostname": "192.168.1.1",
  "serial_number": "RT5500-ABC123",
  "mac_address": "00:1B:44:11:3A:B7",
  "type": {
    "id": 1,
    "name": "Router",
    "model": "Cisco ISR 4451"
  },
  "organization": {
    "id": 123,
    "name": "Headquarters Network"
  },
  "status": false,
  "last_status_change": "2024-01-15T12:15:00Z",
  "pending_config": false,
  "location": "Data Center C - Rack 15",
  "description": "Router relocated to backup data center",
  "firmware_version": "16.12.09",
  "management_ip": "192.168.100.1",
  "created_at": "2024-01-10T14:20:00Z",
  "updated_at": "2024-01-15T12:15:00Z"
}

Response Codes:

Status Description
200 Success - Device fields successfully updated
400 Bad Request - Invalid field values
401 Unauthorized - Invalid or missing API token
404 Not Found - Device with specified ID does not exist

DELETE /inventory_device/{id}/

Description: Permanently removes a device record from the inventory system. This action is irreversible and should be used carefully, typically during device decommissioning or cleanup operations.

Use Cases:

  • Device decommissioning and retirement
  • Cleanup of duplicate or invalid device records
  • Automated cleanup during device lifecycle management
  • Data purging for compliance or storage optimization

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device/1001/

Parameters:

Parameter Type In Required Description
id integer path Yes Unique identifier of the device to delete

cURL Example:

curl -X DELETE "https://control.zequenze.com/api/v1/inventory_device/1001/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response Codes:

Status Description
204 No Content - Device successfully deleted
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient permissions to delete this device
404 Not Found - Device with specified ID does not exist
409 Conflict - Device cannot be deleted due to dependencies

Common Use Cases

Use Case 1: Network Monitoring Dashboard

Build a real-time network monitoring dashboard that displays device status across multiple organizations. Use GET /inventory_device/ with organization, status, and update_status=true parameters to fetch current device states, then use PATCH /inventory_device/{id}/ to update device status based on monitoring results.

Use Case 2: Automated Device Provisioning

Implement an automated provisioning workflow for new network equipment. Use POST /inventory_device/ to register new devices during deployment, then GET /inventory_device/{id}/ to retrieve device details for configuration management systems.

Use Case 3: Device Lifecycle Management

Create a comprehensive device lifecycle management system using GET /inventory_device/ with type and last_status_change_from filters to identify devices needing maintenance, PUT /inventory_device/{id}/ for major updates during hardware refresh, and DELETE /inventory_device/{id}/ for device retirement.

Use Case 4: Configuration Change Tracking

Track pending configuration changes across your network infrastructure by using GET /inventory_device/ with pending=true to identify devices with pending changes, then PATCH /inventory_device/{id}/ to update device status after configuration deployment.

Use Case 5: Multi-Tenant Device Management

Manage devices across multiple organizations or departments using the organization filter in GET /inventory_device/ requests, ensuring proper access control and data segregation for different business units.

Best Practices

  • Pagination: Always use limit and offset parameters for large device inventories to optimize performance and memory usage. Start with reasonable page sizes (20-50 devices) and adjust based on your application needs.

  • Status Updates: Use update_status=true sparingly as it performs real-time device checks that can significantly increase response time. Consider caching mechanisms for frequently accessed device status information.

  • Error Handling: Implement robust error handling for network timeout scenarios, especially when using real-time status updates. Always check response codes and provide meaningful feedback to users.

  • Batch Operations: For bulk device updates, use individual PATCH requests for targeted field updates rather than full PUT requests to minimize data transfer and reduce the risk of data conflicts.

  • Security: Never expose API tokens in client-side code. Always validate device data on the server side before submission, and implement proper access controls based on organization boundaries.

  • Data Integrity: Use serial numbers and MAC addresses as natural keys for device identification to prevent duplicate entries. Validate IP addresses and hostnames before creating or updating device records.

Back to top