Skip to main content

Inventory Device

Endpoints Summary

Method Path Swagger GET /inventory_device/ Swagger ↗ POST /inventory_device/ Swagger ↗ GET /inventory_device/{id}/ Swagger ↗ PUT /inventory_device/{id}/ Swagger ↗ PATCH /inventory_device/{id}/ Swagger ↗ DELETE /inventory_device/{id}/ Swagger ↗

The Inventory Device API provides comprehensivecomplete deviceCRUD managementoperations capabilities,for allowingmanaging network devices in your infrastructure. These endpoints allow you to performcreate, CRUDretrieve, operationsupdate, onand networkdelete devices,device monitorrecords, including their status,configuration profiles, location data, firmware management, and executeoperational status. Common use cases include device operationsonboarding, likebulk rebootsdevice management, status monitoring, and factoryconfiguration resets. These endpoints are essential for managing device inventories, tracking device health, and performing remote device administration in network management systems.synchronization.

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 of device management operations, providing full lifecycle managementinterface for managing network devices.devices in the control platform. This API category enableshandles youall to:aspects of device lifecycle management, from initial registration through ongoing configuration and monitoring.

Key Capabilities:

  • Device Inventory ManagementManagement:: Create, read, update, and delete device records with comprehensive metadata including serial numbers, locations, firmware versions, and organizational assignments
  • Status MonitoringMonitoring:: Track device operational status, connection history, and configuration states with real-time updates
  • RemoteOrganization Device& OperationsLocation:: ExecuteOrganize criticaldevices by organization and geographical location
Firmware Management: Control firmware images and upgrade operations Configuration Control: Manage device operations like reboots, factory resets, configurationsettings, synchronization, and firmwarefactory updatesresets OrganizationalAuthentication: Control: Manage devices across different organizations with proper filtering and access controls Location & Asset Tracking: MaintainHandle device locationscredentials withfor GPSCWMP/TR-069 coordinatesagent and location hierarchiescommunication

Device Lifecycle: Devices typically follow a lifecycle of registration → configuration → monitoring → maintenance. These endpoints support each phase with appropriate status tracking, pending settings management, and operational controls like reboot, sync, and factory reset capabilities.

Integration Points: The APIdevice supportsinventory bothintegrates bulkwith operationsdevice profiles (types), organizations, locations, and firmware images through thereference listfields, endpointenabling with advanced filtering, and individualcomprehensive device management through the detail endpoints. Device operations are designed to work with CWMP/TR-069 protocols for remote device management, making it ideal for ISP and enterprise network management scenarios.

Key concepts include device types (profiles/templates), pending settings tracking, firmware management, and comprehensive audit trails for all device interactions.workflows.

Endpoints

GET /inventory_device/

Description: Retrieves a paginated list of inventory devices with comprehensive filtering capabilities.options. This endpoint is essential for device discovery, status monitoring, and bulk device management operations. It supports real-timefiltering statusby updatesorganization, device type, status, and pendingrecent settingschanges, detection.making it ideal for dashboard displays and automated monitoring systems.

Use Cases:

  • DashboardDisplay displaysdevice showinginventory allin management dashboards
Monitor device status across organizations Find devices with current status Filtering devices by organization for multi-tenant management Finding devices that need firmware updates or have pending configurations MonitoringFilter devicedevices connectivityby andlocation healthor acrosstype thefor networkmaintenance operations

Full URL Example:

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

Parameters:

Parameter Type In Required Description
type integer query No Filter devices by device type/profile ID
status string query No Filter by deviceoperational status. Use '0'/, 'false'/, 'False' for Down devices, or '1'/, 'true'/, 'True' for Up devices
last_status_change_from string query No Filter devices withby status changeschange afterdate/time specifiedin datetimeISO format (ISO format:e.g., 2000-01-01T00:01, 2000-01-01 00:01:00+00:00)
organization integer query No Filter devices by organization ID
limit integer query No Number of results per page (default:default systempagination configured)limit applies)
offset integer query No Starting index for paginationresults (used for pagination)
pending boolean query No Include information about pending device settings information in response
update_status boolean query No Refresh deviceForce status fromupdate remoteusing agentsconfigured helpers before returning data

cURL Example:

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

Example Response:

{
  "count": 150,245,
  "next": "https://control.zequenze.com/api/v1/inventory_device/?limit=25&offset=25&organization=5123&status=1&update_status=true",
  "previous": null,
  "results": [
    {
      "id": 1001,
      "uuid": "550e8400-e29b-41d4-a716-446655440001"f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Router-Branch-Office-001"Main-Office",
      "customer_id": "CUST-2024-001",
      "is_active": true,
      "status": "Up",
      "status_change": "2024-01-15T09:30:15Z"00Z",
      "type": 12,15,
      "type_short_name": "enterprise_router"enterprise-router",
      "software_version": "2.4.1",
      "hardware_version": "v1.2"v3.0",
      "manufacturer": "Zequenze Systems"Networks",
      "serial_number": "ZEQ240100001"ZN2024001001",
      "description": "Main branchoffice officegateway router",
      "organization_id": 5,123,
      "location_name": "New York Branch Office",
      "location": 25,
      "location_short_name": "ny_branch",45,
      "latitude": "40.7128",
      "longitude": "-74.0060",
      "address": "192.168.1.1",
      "last_connection": "2024-01-15T14:22:30Z"15T10:45:00Z",
      "last_configuration": "2024-01-14T10:15:14T16:20:00Z",
      "created": "2024-01-10T08:01T08:00:00Z",
      "pending_settings": "firmware_update,reboot_scheduled"none"
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns paginated device list
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient permissions for requestedorganization organizationfilter

POST /inventory_device/

Description: Creates a new inventory device record in the inventory system. This endpoint is used forduring device onboarding,onboarding bulkto establish the device imports,profile, authentication credentials, and integratinginitial newconfiguration. networkThe equipmentsystem intowill generate a unique UUID for the device and set up the basic management platform.structure.

Use Cases:

  • AddingOnboard new devices during network expansiondeployment
  • Bulk importingdevice devicesregistration from spreadsheetsCSV or other systemsimports
  • Pre-configuringAutomated device recordsprovisioning in workflows
Create device placeholders before physical deployment Setting up device credentials for CWMP/TR-069 authenticationinstallation

Full URL Example:

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

Request Body Example:

{
  "name": "Router-Branch-Office-Seattle",
  "customer_id": "CUST-045",
  "is_active": true,
  "type": 15,
  "serial_number": "ZN2024001156",
  "description": "Seattle branch office gateway",
  "organization_id": 123,
  "location_name": "Seattle Branch",
  "location": 67,
  "latitude": "47.6062",
  "longitude": "-122.3321",
  "username": "device-seattle-001",
  "password": "SecurePassword123!",
  "update_frequency": 300
}

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": "Router-Branch-Office-002"Seattle",
    "customer_id": "CUST-2024-002"045",
    "type": 15,
    "serial_number": "ZEQ240100002"ZN2024001156",
    "type": 12,
    "organization_id": 5,
    "location_name": "Boston Branch Office",
    "description": "Secondary branch office router",123,
    "username": "device_admin"device-seattle-001",
    "password": "secure_password_123",
    SecurePassword123!"update_frequency": 300
  }'

Example Request Body:

{
  "name": "Router-Branch-Office-002",
  "customer_id": "CUST-2024-002",
  "serial_number": "ZEQ240100002",
  "serial_number_alt": "ALT-ZEQ240100002",
  "type": 12,
  "organization_id": 5,
  "location_name": "Boston Branch Office",
  "latitude": "42.3601",
  "longitude": "-71.0589",
  "description": "Secondary branch office router",
  "username": "device_admin",
  "password": "secure_password_123",
  "update_frequency": 300
}

Example Response:

{
  "id": 1002,1156,
  "uuid": "550e8400-e29b-41d4-a716-446655440002"a1b2c3d4-5678-9abc-def0-123456789abc",
  "name": "Router-Branch-Office-002"Seattle",
  "customer_id": "CUST-2024-002"045",
  "is_active": false,true,
  "status": "Down",
  "status_change": "2024-01-15T15:15T14:30:00Z",
  "type": 12,15,
  "type_short_name": "enterprise_router"enterprise-router",
  "software_version": null,
  "hardware_version": null,
  "manufacturer": null,
  "serial_number": "ZEQ240100002",
  "serial_number_alt": "ALT-ZEQ240100002"ZN2024001156",
  "description": "SecondarySeattle branch office router"gateway",
  "organization_id": 5,123,
  "location_name": "BostonSeattle Branch Office"Branch",
  "latitude": "42.3601"47.6062",
  "longitude": "-71.0589"122.3321",
  "username": "device_admin"device-seattle-001",
  "update_frequency": 300,
  "created": "2024-01-15T15:15T14:30:00Z",
  "pending_settings": null"initial"
}

Response Codes:

Status Description
201 Created - Device successfully created
400 Bad Request - Invalid input data or missing required fields
401 Unauthorized - Invalid or missing API token
403409 ForbiddenConflict - InsufficientDevice permissionswith tosame createserial devicesnumber already exists

GET /inventory_device/{id}/

Description: Retrieves detailed information aboutfor a specific inventory device by its ID. This endpoint provides complete device metadata, operational status, and configuration detailsstate. Use this for individual device management.detail views, configuration management interfaces, and troubleshooting workflows.

Use Cases:

  • DeviceDisplay detaildevice viewsdetails in management interfaces
  • RetrievingRetrieve device informationinfo forbefore configuration operationschanges
  • Checking specificCheck device status and connection history
Audit device settings and pending operations Gathering device data for reporting and diagnostics

Full URL Example:

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

Parameters:

Parameter Type In Required Description
id integer path Yes Unique device IDidentifier
pending boolean query No Include detailed pending settings information in response
update_status boolean query No RefreshForce devicereal-time status from remote agentupdate before returning data

cURL Example:

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

Example Response:

{
  "id": 1001,
  "uuid": "550e8400-e29b-41d4-a716-446655440001"f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "Router-Branch-Office-001"Main-Office",
  "customer_id": "CUST-2024-001",
  "is_active": true,
  "status": "Up",
  "status_change": "2024-01-15T09:30:15Z"00Z",
  "type": 12,15,
  "type_short_name": "enterprise_router"enterprise-router",
  "software_version": "2.4.1",
  "hardware_version": "v1.2"v3.0",
  "manufacturer": "Zequenze Systems"Networks",
  "unique_identifier": "ZEQ:ENT:RTR:240100001"ZN-ENT-RTR-001",
  "product_class": "EnterpriseRouter"Enterprise Router",
  "serial_number": "ZEQ240100001"ZN2024001001",
  "serial_number_alt": "ALT-ZEQ240100001"ZN001001",
  "description": "Main branch office router"gateway router with redundant WAN",
  "organization_id": 5,123,
  "firmware_image": 45,25,
  "firmware_image_is_pending": true,false,
  "location_name": "New York Branch Office",
  "location": 25,45,
  "location_short_name": "ny_branch"NYC-Main",
  "latitude": "40.7128",
  "longitude": "-74.0060",
  "username": "device_admin"main-office-gw",
  "update_frequency": 300,
  "address": "192.168.1.1",
  "last_connection": "2024-01-15T14:22:30Z"15T10:45:00Z",
  "last_configuration": "2024-01-14T10:15:14T16:20:00Z",
  "last_change": "2024-01-15T12:45:20Z"14T16:20:00Z",
  "created": "2024-01-10T08:01T08:00:00Z",
  "debug": false,
  "pending_settings": "firmware_update:pending,reboot_scheduled:2024-01-16T02:00:00Z"wifi_config,port_forwarding"
}

Response Codes:

Status Description
200 Success - Returns device details
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: UpdatesCompletely all fields ofupdates an existing inventory device record.record with new data. This endpoint performsreplaces aall completedevice replacementfields ofwith the deviceprovided recordvalues, andmaking isit usedsuitable for comprehensive device updates, configuration changes, and administrative modifications. Use PATCH for partial updates and bulk data corrections.instead.

Use Cases:

  • Complete device reconfiguration during network changes
  • UpdatingUpdate device profiles whenafter hardware is replacedreplacement
  • Bulk device updates from external inventory systems
  • CorrectingAdministrative changes to device information after physical auditsprofiles

Full URL Example:

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

Request Body Example:

{
  "name": "Router-Main-Office-Updated",
  "customer_id": "CUST-001",
  "is_active": true,
  "type": 15,
  "serial_number": "ZN2024001001",
  "description": "Updated main office gateway with new configuration",
  "organization_id": 123,
  "location_name": "New York Office - Floor 5",
  "location": 45,
  "latitude": "40.7128",
  "longitude": "-74.0060",
  "username": "main-office-gw",
  "password": "NewSecurePassword456!",
  "update_frequency": 600,
  "debug": false,
  "sync": true
}

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": "Router-Branch-Main-Office-001-Updated",
    "customer_id": "CUST-2024-001",
    "serial_number"is_active": "ZEQ240100001",true,
    "type": 15,
    "organization_id": 5,123,
    "location_name"sync": true
  }'

Example Response:

{
  "id": 1001,
  "uuid": "Newf47ac10b-58cc-4372-a567-0e02b2c3d479",
  York"name": Main"Router-Main-Office-Updated",
  Office""customer_id": "CUST-001",
  "is_active": true,
  "status": "Up",
  "type": 15,
  "type_short_name": "enterprise-router",
  "serial_number": "ZN2024001001",
  "description": "Updated main office routergateway with new configuration",
  "latitude"organization_id": 123,
  "location_name": "40.7589",New "longitude":York "Office -73.9851" Floor 5",
  "update_frequency": 180600,
  "last_change": "2024-01-15T14:45:00Z",
  "pending_settings": "sync_requested"
}'

Response Codes:

Status Description
200 Success - Device updated successfully
400 Bad Request - Invalid inputdata dataformat or missing required fields
401 Unauthorized - Invalid or missing API token
403
Forbidden - Insufficient permissions to update this device 404 Not Found - Device with specified ID does not exist

PATCH /inventory_device/{id}/

Description: Performs partialPartially updates onspecific fields of an existing inventory device record. This endpoint allowsis youideal tofor updatetargeted specificchanges fieldslike status updates, configuration flags, or operational commands without affecting other device propertiesproperties. Use this for incremental updates and isdevice ideal for targeted operations like status changes, configuration updates, or devicemanagement operations.

Use Cases:

  • TriggeringToggle device operationsdebug (reboot,mode factoryor reset,administrative sync)state
  • UpdatingUpdate device location or description without changing credentials
  • SettingSet firmwareoperational flags (reboot, sync, factory reset)
Modify device credentials or update flags and scheduling operations Enabling debug mode or changing administrative statefrequency

Full URL Example:

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

Request Body Example:

{
  "description": "Updated description after maintenance",
  "debug": true,
  "reboot": true
}

cURL Example for Device Reboot: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 '{
    "debug": true,
    "reboot": true,
    "debug"description": true"Rebooting for maintenance"
  }'

cURL Example for Firmware Update:Response:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device/1001/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "firmware_image"id": 47,1001,
  "firmware_image_is_pending"uuid": true
  }'

cURL Example for Configuration Sync:

curl -X PATCH"f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "https://control.zequenze.com/api/v1/inventory_device/1001/" \
  -Hname": "Authorization: Bearer YOUR_API_TOKEN" \
  -HRouter-Main-Office",
  "Content-Type: application/json" \
  -d '{customer_id": "sync"CUST-001",
  "is_active": true,
  "reconf"status": true"Up",
  "description": "Rebooting for maintenance",
  "debug": true,
  "reboot": true,
  "last_change": "2024-01-15T15:00:00Z",
  "pending_settings": "reboot_requested"
}'

Device Operation Parameters:

Parameter Type Description reboot boolean Triggers a device reboot operation factory boolean Performs factory reset with configuration wipe device_factory boolean Device-only factory reset (keeps stored config) sync boolean Synchronizes settings with device's active configuration reconf boolean Re-applies all existing settings to the device debug boolean Enables/disables debug mode on the device

Response Codes:

Status Description
200 Success - Device partially updated successfully
400 Bad Request - Invalid operation or field values
401 Unauthorized - Invalid or missing API token
403
Forbidden - Insufficient permissions to update this device 404 Not Found - Device with specified ID does not exist

DELETE /inventory_device/{id}/

Description: Permanently removes an inventorya device record from the inventory system. This operationendpoint isshould irreversiblebe used carefully as it completely deletes the device and will delete all associated deviceconfiguration data,data. configurations,Consider anddeactivating history.devices Useinstead withof cautiondeletion infor productionaudit environments.trail purposes.

Use Cases:

  • RemovingRemove decommissioned devices from inventory
  • CleaningClean up test or duplicate device records
Device lifecycle management for retired equipmententries Bulk cleanup operations duringfor systemold maintenancedevices Remove devices that were created in error

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 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: Device Health Monitoring Dashboard

Create a real-time monitoring dashboard by using the list endpoint with status filtering and automatic updates. Combine GET /inventory_device/ with status=1&update_status=true to show all active devices, then use status=0 to identify down devices requiring attention.

Use Case 2: Remote Device Operations

Execute remote device management by using PATCH operations to trigger device actions. Use the detail endpoint to check pending operations, then PATCH with specific operation flags like reboot=true or sync=true to perform maintenance tasks.

Use Case 3: Firmware ManagementOnboarding Workflow

ImplementWhen firmwaredeploying updatesnew bynetwork firstequipment, using GET to identify devices needing updates, then PATCH to set firmware_image and firmware_image_is_pending=true flags. Monitor the process through the pending_settings field in subsequent GET requests.

Use Case 4: Multi-Tenant Device Management

Manage devices across multiple organizations using the organization filter parameter. Combine with proper API token scoping to ensure users only access devices within their authorized organizations.

Use Case 5: Device Onboarding Automation

Automate device deployment by usinguse POST to create device records with pre-configuredinitial credentialsconfiguration, then PATCH to update status and settings,settings as devices come online and are configured.

Use Case 2: Status Dashboard

Use GET with organization and status filters to build real-time dashboards showing device health across different locations and organizations, with pagination for large deployments.

Use Case 3: Bulk Device Management

Combine GET for device discovery with PATCH operations to perform bulk updates like firmware scheduling, configuration synchronization, or maintenance mode activation across multiple devices.

Use Case 4: Device Maintenance Operations

Use PATCH with operational flags (reboot, sync, factory) to perform remote device management tasks, then monitorGET firstwith connectionupdate_status=true throughto theverify last_connectionoperation fieldcompletion.

using

Use Case 5: Inventory Cleanup

Use GET requests with update_status=true.appropriate filters to identify inactive or obsolete devices, then DELETE to remove decommissioned equipment from active inventory management.

Best Practices

  • Pagination ManagementPagination:: Always use limit and limit/offset parameters for large device inventories. Start with reasonable page sizes (25-50 devices)inventories to balancemaintain API performance and usability.

    avoid timeouts

  • Status Update OptimizationUpdates:: Use update_status=true judiciouslyparameter sparingly as it triggers real-time device queries.communication Enableand itmay forimpact criticalresponse monitoring but avoid it in high-frequency polling scenarios to prevent network overhead.

    times

  • DeviceOperational OperationsFlags:: When performingusing deviceoperational operationscommands via(reboot, PATCH,sync, factory), monitor the pending_settings field to track operation completion. Operations are asynchronous and may take time to complete.

    status

  • BatchFiltering OperationsEfficiency:: ForUse bulkorganization-level devicefiltering management,when implementpossible properto errorreduce handlingdata transfer and retryimprove logic.response Use the list endpoint with appropriate filters to identify target devices before performing batch updates.

    times

  • SecurityError ConsiderationsHandling:: Implement retry logic for device operations as network devices may be temporarily unreachable

Security: Store device passwords securely and rotate them regularly. Use strong authentication credentials andregularly considerusing thePATCH security implications of debug mode when troubleshooting. operations

ErrorBulk HandlingOperations:: ImplementFor comprehensivelarge-scale errorupdates, handlingimplement forbatch deviceprocessing operations,with especiallyappropriate fordelays remotebetween operationsAPI that may fail duecalls to networkavoid connectivityrate or device state issues.

limiting
Back to top