CONTROL API Reference

User Guide - Control API Reference

Overview

Complete API reference for CONTROL API with 66 endpoints across 30 categories.

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

Zequenze CONTROL platform API documentation

Authentication

All API endpoints require authentication using a Bearer token in the request header:

Authorization: Bearer <your-api-token>

You can obtain your API token from the portal administration panel.

Available Endpoints

Category Endpoints Methods
Inventory Connection Profile 2 GET
Inventory Device 6 DELETE GET PATCH POST PUT
Inventory Device Diags 2 GET POST
Inventory Device Headless Operation 2 GET POST
Inventory Device Ipping 1 GET
Inventory Device Log 2 GET
Inventory Device Name 6 DELETE GET PATCH POST PUT
Inventory Device Name Diags 2 GET POST
Inventory Device Name Headless Operation 2 GET POST
Inventory Device Name Ipping 1 GET
Inventory Device Name Operation 1 PUT
Inventory Device Name Setting 3 GET PATCH PUT
Inventory Device Name Variables 2 GET PUT
Inventory Device Operation 1 PUT
Inventory Device Serial 6 DELETE GET PATCH POST PUT
Inventory Device Serial Diags 2 GET POST
Inventory Device Serial Headless Operation 2 GET POST
Inventory Device Serial Ipping 1 GET
Inventory Device Serial Operation 1 PUT
Inventory Device Serial Setting 3 GET PATCH PUT
Inventory Device Serial Variables 2 GET PUT
Inventory Device Setting 3 GET PATCH PUT
Inventory Device Variables 2 GET PUT
Inventory Device Whip 1 GET
Inventory Metric 2 GET
Inventory Metric Log 2 GET
Inventory Parameter 2 GET
Inventory Type 2 GET
Securedns Categoryget 1 GET
Securedns Hostcheck 1 GET

All Endpoints

Method Path Documentation
GET /inventory_connection_profile/ Inventory Connection Profile
GET /inventory_connection_profile/{id}/ Inventory Connection Profile
GET /inventory_device/ Inventory Device
POST /inventory_device/ Inventory Device
GET /inventory_device/{id}/ Inventory Device
PUT /inventory_device/{id}/ Inventory Device
PATCH /inventory_device/{id}/ Inventory Device
DELETE /inventory_device/{id}/ Inventory Device
POST /inventory_device_diags/ Inventory Device Diags
GET /inventory_device_diags/ Inventory Device Diags
GET /inventory_device_headless_operation/ Inventory Device Headless Operation
POST /inventory_device_headless_operation/ Inventory Device Headless Operation
GET /inventory_device_ipping/{id}/ Inventory Device Ipping
GET /inventory_device_log/ Inventory Device Log
GET /inventory_device_log/{id}/ Inventory Device Log
GET /inventory_device_name/ Inventory Device Name
POST /inventory_device_name/ Inventory Device Name
GET /inventory_device_name/{name}/ Inventory Device Name
PUT /inventory_device_name/{name}/ Inventory Device Name
PATCH /inventory_device_name/{name}/ Inventory Device Name
DELETE /inventory_device_name/{name}/ Inventory Device Name
POST /inventory_device_name_diags/ Inventory Device Name Diags
GET /inventory_device_name_diags/ Inventory Device Name Diags
GET /inventory_device_name_headless_operation/ Inventory Device Name Headless Operation
POST /inventory_device_name_headless_operation/ Inventory Device Name Headless Operation
GET /inventory_device_name_ipping/{name}/ Inventory Device Name Ipping
PUT /inventory_device_name_operation/{name}/ Inventory Device Name Operation
GET /inventory_device_name_setting/ Inventory Device Name Setting
PUT /inventory_device_name_setting/{parent__name}/ Inventory Device Name Setting
PATCH /inventory_device_name_setting/{parent__name}/ Inventory Device Name Setting
GET /inventory_device_name_variables/ Inventory Device Name Variables
PUT /inventory_device_name_variables/{parent__name}/ Inventory Device Name Variables
PUT /inventory_device_operation/{id}/ Inventory Device Operation
GET /inventory_device_serial/ Inventory Device Serial
POST /inventory_device_serial/ Inventory Device Serial
GET /inventory_device_serial/{serial_number}/ Inventory Device Serial
PUT /inventory_device_serial/{serial_number}/ Inventory Device Serial
PATCH /inventory_device_serial/{serial_number}/ Inventory Device Serial
DELETE /inventory_device_serial/{serial_number}/ Inventory Device Serial
POST /inventory_device_serial_diags/ Inventory Device Serial Diags
GET /inventory_device_serial_diags/ Inventory Device Serial Diags
GET /inventory_device_serial_headless_operation/ Inventory Device Serial Headless Operation
POST /inventory_device_serial_headless_operation/ Inventory Device Serial Headless Operation
GET /inventory_device_serial_ipping/{serial_number}/ Inventory Device Serial Ipping
PUT /inventory_device_serial_operation/{serial_number}/ Inventory Device Serial Operation
GET /inventory_device_serial_setting/ Inventory Device Serial Setting
PUT /inventory_device_serial_setting/{parent__serial_number}/ Inventory Device Serial Setting
PATCH /inventory_device_serial_setting/{parent__serial_number}/ Inventory Device Serial Setting
GET /inventory_device_serial_variables/ Inventory Device Serial Variables
PUT /inventory_device_serial_variables/{parent__serial_number}/ Inventory Device Serial Variables
GET /inventory_device_setting/ Inventory Device Setting
PUT /inventory_device_setting/{parent_id}/ Inventory Device Setting
PATCH /inventory_device_setting/{parent_id}/ Inventory Device Setting
GET /inventory_device_variables/ Inventory Device Variables
PUT /inventory_device_variables/{parent_id}/ Inventory Device Variables
GET /inventory_device_whip/{id}/ Inventory Device Whip
GET /inventory_metric/ Inventory Metric
GET /inventory_metric/{id}/ Inventory Metric
GET /inventory_metric_log/ Inventory Metric Log
GET /inventory_metric_log/{id}/ Inventory Metric Log
GET /inventory_parameter/ Inventory Parameter
GET /inventory_parameter/{id}/ Inventory Parameter
GET /inventory_type/ Inventory Type
GET /inventory_type/{id}/ Inventory Type
GET /securedns_categoryget/ Securedns Categoryget
GET /securedns_hostcheck/ Securedns Hostcheck

Quick Start

1. Authentication

Obtain your API token from the portal and include it in all requests.

2. Make a Request

curl -X GET "https://control.zequenze.com/api/v1/endpoint/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

3. Handle the Response

All responses are in JSON format. List endpoints include pagination.

Response Codes

Code Status Description
200 OK Request successful
201 Created Resource created successfully
204 No Content Request successful (DELETE operations)
400 Bad Request Invalid request parameters
401 Unauthorized Missing or invalid authentication token
403 Forbidden Insufficient permissions
404 Not Found Resource not found
500 Server Error Internal server error

Pagination

List endpoints return paginated results:

{
  "count": 150,
  "next": "https://api.example.com/endpoint/?offset=50",
  "previous": null,
  "results": [...]
}

Use limit and offset query parameters to navigate through results.

Inventory Connection Profile

Endpoints Summary

Method Path Swagger
GET /inventory_connection_profile/ Swagger ↗
GET /inventory_connection_profile/{id}/ Swagger ↗

The Inventory Connection Profile API manages connection profiles that define how the system communicates with and collects data from devices and applications in your inventory. These profiles specify connection services for device communication, collection services for metrics gathering, and storage services for data persistence.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

Inventory Connection Profiles serve as configuration templates that define how the Zequenze Control system establishes connections with various devices and applications in your network infrastructure. Each profile combines three key service types:

These profiles are essential for inventory management workflows, allowing you to standardize connection methods across similar device types while maintaining flexibility for different environments. By creating reusable profiles, you can ensure consistent data collection and device management across your infrastructure.

Common scenarios include creating profiles for different device categories (network equipment, servers, IoT devices), environment types (production, staging, development), or organizational units with specific compliance requirements.

Endpoints

GET /inventory_connection_profile/

Description: Retrieves a paginated list of all inventory connection profiles in your organization. This endpoint supports filtering by profile name and includes pagination controls for managing large datasets.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_connection_profile/?name=production&limit=20&offset=0

Parameters:

Parameter Type In Required Description
name string query No Filter profiles by name (supports partial matching)
limit integer query No Number of results to return per page (default: 20, max: 100)
offset integer query No The initial index from which to return results for pagination

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_connection_profile/?name=network&limit=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 25,
  "next": "https://control.zequenze.com/api/v1/inventory_connection_profile/?limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Network Equipment Profile",
      "connection_service": 101,
      "collection_service": 201,
      "storage_service": 301
    },
    {
      "id": 2,
      "name": "Server Monitoring Profile",
      "connection_service": 102,
      "collection_service": 202,
      "storage_service": 301
    },
    {
      "id": 3,
      "name": "IoT Device Profile",
      "connection_service": 103,
      "collection_service": 203,
      "storage_service": 302
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns the list of connection profiles
401 Unauthorized - Invalid or missing authentication token
403 Forbidden - Insufficient permissions to access profiles
500 Internal Server Error - Server-side error occurred

GET /inventory_connection_profile/{id}/

Description: Retrieves detailed information about a specific inventory connection profile by its unique identifier. This endpoint provides complete profile configuration including all associated service references.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_connection_profile/1/

Parameters:

Parameter Type In Required Description
id integer path Yes Unique identifier of the connection profile to retrieve

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_connection_profile/1/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "id": 1,
  "name": "Production Network Equipment Profile",
  "connection_service": 101,
  "collection_service": 201,
  "storage_service": 301
}

Response Codes:

Status Description
200 Success - Returns the connection profile details
401 Unauthorized - Invalid or missing authentication token
403 Forbidden - Insufficient permissions to access this profile
404 Not Found - Connection profile with specified ID does not exist
500 Internal Server Error - Server-side error occurred

Common Use Cases

Use Case 1: Profile Discovery and Selection

When setting up new devices in your inventory, use the list endpoint to discover available connection profiles that match your requirements. Filter by name to find profiles specific to your device type or environment.

Use Case 2: Profile Configuration Verification

Before applying a connection profile to critical infrastructure, retrieve the specific profile details to verify the connection, collection, and storage service configurations align with your operational requirements.

Use Case 3: Inventory Management Dashboard

Build administrative dashboards that display all available connection profiles with their configurations, allowing infrastructure teams to understand the standardized connection methods available across the organization.

Use Case 4: Automated Device Onboarding

Integrate these endpoints into automated device onboarding workflows where the system automatically selects appropriate connection profiles based on device characteristics or organizational policies.

Use Case 5: Compliance and Auditing

Use the list endpoint to regularly audit connection profile configurations, ensuring they comply with security policies and operational standards across different environments or organizational units.

Best Practices

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 complete CRUD operations for managing network devices in your infrastructure. These endpoints allow you to create, retrieve, update, and delete device records, including their configuration profiles, location data, firmware management, and operational status. Common use cases include device onboarding, bulk device management, status monitoring, and configuration 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 interface for managing network devices in the control platform. This API category handles all aspects of device lifecycle management, from initial registration through ongoing configuration and monitoring.

Key Capabilities:

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 device inventory integrates with device profiles (types), organizations, locations, and firmware images through reference fields, enabling comprehensive device management workflows.

Endpoints

GET /inventory_device/

Description: Retrieves a paginated list of inventory devices with comprehensive filtering options. This endpoint is essential for device discovery, status monitoring, and bulk operations. It supports filtering by organization, device type, status, and recent changes, making it ideal for dashboard displays and automated monitoring systems.

Use Cases:

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/profile ID
status string query No Filter by operational status. Use '0', 'false', 'False' for Down devices, or '1', 'true', 'True' for Up devices
last_status_change_from string query No Filter by status change date/time in ISO format (e.g., 2000-01-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 pagination limit applies)
offset integer query No Starting index for results (used for pagination)
pending boolean query No Include information about pending device settings
update_status boolean query No Force status update using configured helpers before returning data

cURL Example:

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

Example Response:

{
  "count": 245,
  "next": "https://control.zequenze.com/api/v1/inventory_device/?limit=25&offset=25&organization=123&status=true",
  "previous": null,
  "results": [
    {
      "id": 1001,
      "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Router-Main-Office",
      "customer_id": "CUST-001",
      "is_active": true,
      "status": "Up",
      "status_change": "2024-01-15T09:30:00Z",
      "type": 15,
      "type_short_name": "enterprise-router",
      "software_version": "2.4.1",
      "hardware_version": "v3.0",
      "manufacturer": "Zequenze Networks",
      "serial_number": "ZN2024001001",
      "description": "Main office gateway router",
      "organization_id": 123,
      "location_name": "New York Office",
      "location": 45,
      "latitude": "40.7128",
      "longitude": "-74.0060",
      "address": "192.168.1.1",
      "last_connection": "2024-01-15T10:45:00Z",
      "last_configuration": "2024-01-14T16:20:00Z",
      "created": "2024-01-01T08:00:00Z",
      "pending_settings": "none"
    }
  ]
}

Response Codes:

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

POST /inventory_device/

Description: Creates a new device record in the inventory system. This endpoint is used during device onboarding to establish the device profile, authentication credentials, and initial configuration. The system will generate a unique UUID for the device and set up the basic management structure.

Use Cases:

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-Seattle",
    "customer_id": "CUST-045",
    "type": 15,
    "serial_number": "ZN2024001156",
    "organization_id": 123,
    "username": "device-seattle-001",
    "password": "SecurePassword123!"
  }'

Example Response:

{
  "id": 1156,
  "uuid": "a1b2c3d4-5678-9abc-def0-123456789abc",
  "name": "Router-Branch-Office-Seattle",
  "customer_id": "CUST-045",
  "is_active": true,
  "status": "Down",
  "status_change": "2024-01-15T14:30:00Z",
  "type": 15,
  "type_short_name": "enterprise-router",
  "serial_number": "ZN2024001156",
  "description": "Seattle branch office gateway",
  "organization_id": 123,
  "location_name": "Seattle Branch",
  "latitude": "47.6062",
  "longitude": "-122.3321",
  "username": "device-seattle-001",
  "update_frequency": 300,
  "created": "2024-01-15T14:30:00Z",
  "pending_settings": "initial"
}

Response Codes:

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

GET /inventory_device/{id}/

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

Use Cases:

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 identifier
pending boolean query No Include pending settings information in response
update_status boolean query No Force real-time status update before returning data

cURL Example:

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

Example Response:

{
  "id": 1001,
  "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "Router-Main-Office",
  "customer_id": "CUST-001",
  "is_active": true,
  "status": "Up",
  "status_change": "2024-01-15T09:30:00Z",
  "type": 15,
  "type_short_name": "enterprise-router",
  "software_version": "2.4.1",
  "hardware_version": "v3.0",
  "manufacturer": "Zequenze Networks",
  "unique_identifier": "ZN-ENT-RTR-001",
  "product_class": "Enterprise Router",
  "serial_number": "ZN2024001001",
  "serial_number_alt": "ALT-ZN001001",
  "description": "Main office gateway router with redundant WAN",
  "organization_id": 123,
  "firmware_image": 25,
  "firmware_image_is_pending": false,
  "location_name": "New York Office",
  "location": 45,
  "location_short_name": "NYC-Main",
  "latitude": "40.7128",
  "longitude": "-74.0060",
  "username": "main-office-gw",
  "update_frequency": 300,
  "address": "192.168.1.1",
  "last_connection": "2024-01-15T10:45:00Z",
  "last_configuration": "2024-01-14T16:20:00Z",
  "last_change": "2024-01-14T16:20:00Z",
  "created": "2024-01-01T08:00:00Z",
  "debug": false,
  "pending_settings": "wifi_config,port_forwarding"
}

Response Codes:

Status Description
200 Success - Returns device details
401 Unauthorized - Invalid or missing API token
404 Not Found - Device ID does not exist

PUT /inventory_device/{id}/

Description: Completely updates an existing device record with new data. This endpoint replaces all device fields with the provided values, making it suitable for comprehensive device updates, configuration changes, and administrative modifications. Use PATCH for partial updates instead.

Use Cases:

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-Main-Office-Updated",
    "customer_id": "CUST-001",
    "is_active": true,
    "type": 15,
    "organization_id": 123,
    "sync": true
  }'

Example Response:

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

Response Codes:

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

PATCH /inventory_device/{id}/

Description: Partially updates specific fields of an existing device record. This endpoint is ideal for targeted changes like status updates, configuration flags, or operational commands without affecting other device properties. Use this for incremental updates and device management operations.

Use Cases:

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:

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,
    "description": "Rebooting for maintenance"
  }'

Example Response:

{
  "id": 1001,
  "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "Router-Main-Office",
  "customer_id": "CUST-001",
  "is_active": true,
  "status": "Up",
  "description": "Rebooting for maintenance",
  "debug": true,
  "reboot": true,
  "last_change": "2024-01-15T15:00:00Z",
  "pending_settings": "reboot_requested"
}

Response Codes:

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

DELETE /inventory_device/{id}/

Description: Permanently removes a device record from the inventory system. This endpoint should be used carefully as it completely deletes the device and all associated configuration data. Consider deactivating devices instead of deletion for audit trail purposes.

Use Cases:

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
404 Not Found - Device ID does not exist
409 Conflict - Device cannot be deleted due to dependencies

Common Use Cases

Use Case 1: Device Onboarding Workflow

When deploying new network equipment, use POST to create device records with initial configuration, then PATCH to update status and 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 GET with update_status=true to verify operation completion.

Use Case 5: Inventory Cleanup

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

Best Practices

Inventory Device Diags

Endpoints Summary

Method Path Swagger
POST /inventory_device_diags/ Swagger ↗
GET /inventory_device_diags/ Swagger ↗

The Inventory Device Diagnostics API enables you to create and monitor network diagnostic operations for devices in your inventory. These endpoints allow you to schedule various network tests like ping, traceroute, speed tests, and WiFi diagnostics, then retrieve results and status information for troubleshooting and network performance analysis.

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 provides comprehensive network diagnostic capabilities for managed devices. This API category allows network administrators and developers to programmatically execute various diagnostic operations including connectivity tests, performance measurements, and network discovery tools.

Key Features:

Common Use Cases:

The diagnostic operations are executed asynchronously on the target devices, allowing you to schedule multiple tests and check their progress using the list endpoint.

Endpoints

POST /inventory_device_diags/

Description: Creates a new diagnostic operation for a specific device. This endpoint schedules various types of network diagnostics that will be executed on the target device, including connectivity tests, performance measurements, and network discovery operations.

Use Cases:

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 from your inventory
operation string Yes Type of diagnostic operation. Options: download, upload, ipping, udpecho, traceroute, dnslookup, wifi.neighbor
target string Yes Target URL (download/upload), IP address (ping/traceroute), hostname (DNS lookup), or parameter (WiFi diagnostics)
upload_size string No File size in MB for upload operations (e.g., "100")
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/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 Concurrent connections for download/upload tests

cURL Example - Ping 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": "ipping",
    "target": "8.8.8.8",
    "count": 10,
    "size": 64,
    "timeout": 2
  }'

cURL Example - Speed 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/100MB.bin",
    "number_of_connections": 4,
    "interface": "eth0"
  }'

Example Response:

{
  "id": 12345,
  "operation": "ipping",
  "target": "8.8.8.8",
  "count": 10,
  "size": 64,
  "timeout": 2,
  "interface": "eth0",
  "upload_size": null,
  "dns_server": null,
  "max_hops": null,
  "number_of_connections": null
}

Response Codes:

Status Description
201 Created - Diagnostic operation scheduled successfully
400 Bad Request - Invalid parameters or missing required fields
401 Unauthorized - Invalid or missing API token
404 Not Found - Device ID not found in inventory

GET /inventory_device_diags/

Description: Retrieves a list of diagnostic operations, either all operations or filtered by specific criteria. This endpoint allows you to monitor the status of scheduled diagnostics and retrieve results from completed operations.

Use Cases:

Full URL Example:

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

Parameters:

Parameter Type In Required Description
id string query No ID of a specific scheduled diagnostic transaction to retrieve
update_status boolean query No Whether to refresh device status using configured helpers before returning data

cURL Example - List All Diagnostics:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_diags/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

cURL Example - Get Specific Diagnostic:

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

Example Response:

[
  {
    "id": 12345,
    "operation": "ipping",
    "target": "8.8.8.8",
    "count": 10,
    "size": 64,
    "timeout": 2,
    "interface": "eth0",
    "upload_size": null,
    "dns_server": null,
    "max_hops": null,
    "number_of_connections": null
  },
  {
    "id": 12346,
    "operation": "download",
    "target": "http://speedtest.example.com/100MB.bin",
    "count": null,
    "size": null,
    "timeout": null,
    "interface": "wlan0",
    "upload_size": null,
    "dns_server": null,
    "max_hops": null,
    "number_of_connections": 4
  },
  {
    "id": 12347,
    "operation": "traceroute",
    "target": "google.com",
    "count": null,
    "size": null,
    "timeout": null,
    "interface": null,
    "upload_size": null,
    "dns_server": null,
    "max_hops": 20,
    "number_of_connections": null
  }
]

Response Codes:

Status Description
200 Success - Returns list of diagnostic operations
401 Unauthorized - Invalid or missing API token
404 Not Found - Specific diagnostic ID not found (when using id parameter)

Common Use Cases

Use Case 1: Automated Network Health Monitoring

Schedule regular ping and connectivity tests for critical devices to monitor network health. Use the POST endpoint to create recurring diagnostic jobs and the GET endpoint to retrieve results for dashboard displays or alerting systems.

Use Case 2: Bandwidth Performance Testing

Conduct periodic speed tests using download and upload operations to ensure devices meet SLA requirements. Configure multiple connections to test maximum throughput capabilities and identify performance degradation.

Use Case 3: Troubleshooting Connectivity Issues

When users report network problems, use traceroute and DNS lookup diagnostics to identify routing issues or DNS resolution problems. The interface parameter allows testing specific network paths.

Use Case 4: WiFi Site Survey and Optimization

Execute WiFi neighbor diagnostics to analyze wireless environments, identify interference sources, and optimize channel assignments for better performance in dense deployment scenarios.

Use Case 5: Compliance and SLA Reporting

Regularly schedule comprehensive diagnostic suites and use the results for compliance reporting, SLA verification, and network performance documentation required by regulatory or contractual obligations.

Best Practices

Inventory Device Headless Operation

Endpoints Summary

Method Path Swagger
GET /inventory_device_headless_operation/ Swagger ↗
POST /inventory_device_headless_operation/ Swagger ↗

The Inventory Device Headless Operation API enables automated device management operations on network devices through programmatic control. These endpoints allow you to schedule and execute device operations such as retrieving parameters, setting configurations, and managing objects without manual intervention, making them ideal for bulk device management and automated workflows.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Headless Operation API provides a powerful interface for managing network devices programmatically. This API category focuses on executing operations on devices that are part of your inventory without requiring direct user interaction.

Key Capabilities:

Common Use Cases:

The operations are designed to work with TR-069/CWMP compatible devices and support standard device management protocols. All operations can be tracked and their status updated using the built-in helpers.

Endpoints

GET /inventory_device_headless_operation/

Description: Retrieves a list of scheduled headless operations for devices in your inventory. This endpoint allows you to monitor existing operations, check their configuration, and optionally update device status before returning the information. Use this to track ongoing operations or verify operation parameters before execution.

Use Cases:

Full URL Example:

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

Parameters:

Parameter Type In Required Description
id string query No ID of the specific scheduled transaction to retrieve. If provided, returns only that operation
update_status boolean query No When true, uses configured helpers to update device status before returning information

cURL Example:

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

Example Response:

[
  {
    "id": 12345,
    "operation": "get",
    "variables": [
      {
        "variable_name": "Device.ManagementServer.PeriodicInformInterval"
      },
      {
        "variable_name": "Device.WiFi.SSID.1.SSID"
      },
      {
        "variable_name": "Device.DeviceInfo.SerialNumber"
      }
    ]
  },
  {
    "id": 12346,
    "operation": "set",
    "variables": [
      {
        "variable_name": "Device.ManagementServer.PeriodicInformInterval",
        "value": "300",
        "value_type": "integer"
      },
      {
        "variable_name": "Device.ManagementServer.PeriodicInformEnable",
        "value": "1",
        "value_type": "boolean"
      }
    ]
  }
]

Response Codes:

Status Description
200 Success - Returns the list of scheduled operations
401 Unauthorized - Invalid or missing token
404 Not Found - Specific operation ID not found

POST /inventory_device_headless_operation/

Description: Creates a new headless operation for a device in your inventory. This endpoint schedules operations to be executed on network devices, including parameter retrieval, configuration updates, and object management. The operation will be queued and executed according to your system's scheduling configuration.

Use Cases:

Full URL Example:

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

Parameters:

Parameter Type In Required Description
data string body Yes JSON payload containing the operation details including device ID, operation type, and variables

Request Body Structure:

{
  "id": 12345,
  "operation": "get|set|add.obj|del.obj",
  "variables": [
    {
      "variable_name": "Device.Parameter.Name",
      "value": "parameter_value",
      "value_type": "string|integer|boolean"
    }
  ]
}

cURL Example - Get Operation:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_headless_operation/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 12345,
    "operation": "get",
    "variables": [
      {"variable_name": "Device.ManagementServer.PeriodicInformInterval"},
      {"variable_name": "Device.WiFi.SSID.1.SSID"},
      {"variable_name": "Device.DeviceInfo.ModelName"}
    ]
  }'

cURL Example - Set Operation:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_headless_operation/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 12345,
    "operation": "set",
    "variables": [
      {
        "variable_name": "Device.ManagementServer.PeriodicInformInterval",
        "value": "300",
        "value_type": "integer"
      },
      {
        "variable_name": "Device.WiFi.SSID.1.SSID",
        "value": "MyNewNetwork",
        "value_type": "string"
      }
    ]
  }'

Example Response:

{
  "id": 12345,
  "operation": "set",
  "variables": [
    {
      "variable_name": "Device.ManagementServer.PeriodicInformInterval",
      "value": "300",
      "value_type": "integer"
    },
    {
      "variable_name": "Device.WiFi.SSID.1.SSID",
      "value": "MyNewNetwork",
      "value_type": "string"
    }
  ]
}

Response Codes:

Status Description
201 Created - Operation successfully scheduled
400 Bad Request - Invalid operation parameters
401 Unauthorized - Invalid or missing token
404 Not Found - Device ID not found in inventory

Common Use Cases

Use Case 1: Bulk Wi-Fi Configuration Update

Schedule configuration updates across multiple access points to change SSID names, passwords, or security settings. Use the set operation with Wi-Fi related parameters to update network configurations remotely.

Use Case 2: Device Health Monitoring

Set up automated parameter collection using get operations to monitor device status, performance metrics, and configuration drift. Schedule regular retrieval of key parameters like uptime, memory usage, and connection statistics.

Use Case 3: Dynamic Network Object Management

Use add.obj and del.obj operations to dynamically manage network configurations such as creating new SSID instances, adding firewall rules, or managing VLAN configurations based on business requirements.

Use Case 4: Compliance Auditing

Implement automated compliance checking by retrieving configuration parameters and comparing them against organizational standards. Use get operations to collect current settings for security auditing purposes.

Use Case 5: Remote Troubleshooting

Schedule diagnostic operations to collect device information and statistics when issues are reported. Use a combination of get operations to gather comprehensive device state information for troubleshooting.

Best Practices

Inventory Device Ipping

Endpoints Summary

Method Path Swagger
GET /inventory_device_ipping/{id}/ Swagger ↗

The Inventory Device IP Ping API provides functionality to retrieve ping test information for network devices in your inventory. This endpoint allows you to monitor network connectivity and troubleshoot device accessibility issues across your infrastructure.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device IP Ping API category enables you to access ping test results and network connectivity data for devices in your inventory management system. This API is essential for network monitoring, device health checks, and troubleshooting connectivity issues.

Key capabilities include:

This endpoint is commonly used by network administrators, monitoring systems, and automated scripts that need to verify device connectivity status. The ping data helps identify network issues, validate device configurations, and ensure infrastructure reliability.

The API follows RESTful conventions and returns detailed ping information including response times, packet loss statistics, and connection status indicators.

Endpoints

GET /inventory_device_ipping/{id}/

Description: Retrieves ping test information for a specific inventory device. This endpoint returns detailed network connectivity data including ping response times, packet loss statistics, and overall connection status for the specified device.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_ipping/123/

Parameters:

Parameter Type In Required Description
id integer path Yes The unique identifier of the device ping record to retrieve

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_ipping/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "id": 123,
  "device_id": 456,
  "device_name": "Core Switch 01",
  "ip_address": "192.168.1.10",
  "status": "online",
  "last_ping_time": "2024-01-15T10:30:00Z",
  "response_time_ms": 2.45,
  "packet_loss_percent": 0.0,
  "ping_count": 4,
  "successful_pings": 4,
  "average_response_time": 2.38,
  "min_response_time": 2.12,
  "max_response_time": 2.67,
  "is_reachable": true,
  "last_successful_ping": "2024-01-15T10:30:00Z",
  "last_failed_ping": null,
  "consecutive_failures": 0,
  "uptime_percentage": 99.95
}

Response Codes:

Status Description
200 Success - Returns the ping data for the specified device
401 Unauthorized - Invalid or missing API token
404 Not Found - Device ping record with specified ID does not exist
403 Forbidden - Insufficient permissions to access this device

Common Use Cases

Use Case 1: Network Health Monitoring

Monitor the connectivity status of critical network infrastructure devices by regularly checking their ping statistics. This helps identify devices that may be experiencing intermittent connectivity issues or degraded performance.

Use Case 2: Troubleshooting Network Issues

When users report connectivity problems, retrieve ping data for affected devices to quickly identify whether the issue is related to network connectivity, high latency, or packet loss.

Use Case 3: Maintenance Planning

Before performing maintenance on network devices, check their current ping status to ensure they are accessible and functioning properly. This helps avoid scheduling maintenance during existing outages.

Use Case 4: Performance Analysis

Analyze ping response times and packet loss statistics over time to identify trends in network performance and plan infrastructure improvements.

Use Case 5: Automated Alerting

Integrate ping data into monitoring systems to trigger alerts when devices become unreachable or when response times exceed acceptable thresholds.

Best Practices

Inventory Device Log

Endpoints Summary

Method Path Swagger
GET /inventory_device_log/ Swagger ↗
GET /inventory_device_log/{id}/ Swagger ↗

The Inventory Device Log API provides comprehensive access to device operation logs, settings changes, and command execution history. These endpoints allow you to track all device interactions, monitor pending operations, and audit configuration changes across your device inventory.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Log API is essential for monitoring and auditing device operations within your network infrastructure. These endpoints provide detailed logging capabilities that track every interaction between your management system and devices, including configuration changes, command executions, alerts, and operational events.

Key Features:

Common Use Cases:

The API uses pagination for efficient data retrieval and supports comprehensive filtering to help you find specific log entries quickly.

Endpoints

GET /inventory_device_log/

Description: Retrieves a paginated list of device operation logs with comprehensive filtering capabilities. This endpoint is essential for monitoring device activities, tracking configuration changes, and analyzing operational patterns across your device inventory.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_log/?parent__id=123&action=sv&datetime__gte=2024-01-01&limit=50

Parameters:

Parameter Type In Required Description
datetime__gte string query No Filter logs from this date/time onwards. Accepts ISO format: 2024-01-01, 2024-01-01 10:30:00, or 2024-01-01T10:30:00+00:00
datetime__lte string query No Filter logs up to this date/time. Accepts ISO format: 2024-01-31, 2024-01-31 23:59:59, or 2024-01-31T23:59:59+00:00
parent__id string query No Filter logs for a specific device by device ID
action string query No Filter by action type: sv (Set), uv (Unset), gv (Get), sa (Set attribute), cr (Create), de (Delete), cm (Command), ev (Event), er (Error), ar (Alert raised), ac (Alert cleared)
is_pending boolean query No Filter for operations that are still pending execution
is_applied boolean query No Filter for operations that have been successfully applied
variable_name string query No Filter by specific parameter or variable name
cursor string query No Pagination cursor for retrieving next/previous pages
limit integer query No Number of results per page (default: 100, max: 1000)

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_log/?parent__id=123&action=sv&datetime__gte=2024-01-01&limit=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "next": "https://control.zequenze.com/api/v1/inventory_device_log/?cursor=cD0yMDI0LTA0LTI0KzAwJTNBMDA%3D",
  "previous": null,
  "results": [
    {
      "id": 1001,
      "created": "2024-01-15T14:30:00Z",
      "last_change": "2024-01-15T14:30:15Z",
      "user": 5,
      "parent": 123,
      "type": "string",
      "action": "sv",
      "command": "Reconf",
      "name": "WiFi Configuration Update",
      "variable_name": "Device.WiFi.SSID.1.SSID",
      "value": "CorporateNetwork_2024",
      "is_pending": false,
      "is_applied": true,
      "status": 200,
      "message": "Configuration applied successfully"
    },
    {
      "id": 1002,
      "created": "2024-01-15T14:25:00Z",
      "last_change": "2024-01-15T14:25:30Z",
      "user": 3,
      "parent": 124,
      "type": "boolean",
      "action": "cm",
      "command": "Reboot",
      "name": "Scheduled Device Reboot",
      "variable_name": null,
      "value": null,
      "is_pending": true,
      "is_applied": false,
      "status": 100,
      "message": "Reboot command sent to device"
    },
    {
      "id": 1003,
      "created": "2024-01-15T14:20:00Z",
      "last_change": "2024-01-15T14:20:05Z",
      "user": null,
      "parent": 125,
      "type": null,
      "action": "ar",
      "command": "Parameter Threshold",
      "name": "High CPU Usage Alert",
      "variable_name": "Device.DeviceInfo.ProcessStatus.Process.1.CPUUsage",
      "value": "89.5",
      "is_pending": false,
      "is_applied": true,
      "status": 200,
      "message": "CPU usage exceeded threshold of 80%"
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns paginated list of device logs
401 Unauthorized - Invalid or missing authentication token
403 Forbidden - Insufficient permissions to access device logs
400 Bad Request - Invalid filter parameters or date format

GET /inventory_device_log/{id}/

Description: Retrieves detailed information about a specific device log entry. This endpoint provides complete details about a single operation, including execution status, timestamps, and any error messages.

Use Cases:

Full URL Example:

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

Parameters:

Parameter Type In Required Description
id integer path Yes Unique identifier of the device log entry
datetime__gte string query No Additional filter by date range (rarely used for single record retrieval)
datetime__lte string query No Additional filter by date range (rarely used for single record retrieval)
parent__id string query No Additional filter by device ID
variable_name string query No Additional filter by variable name
action string query No Additional filter by action type
is_pending boolean query No Additional filter by pending status
is_applied boolean query No Additional filter by applied status

cURL Example:

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

Example Response:

{
  "id": 1001,
  "created": "2024-01-15T14:30:00Z",
  "last_change": "2024-01-15T14:30:15Z",
  "user": 5,
  "parent": 123,
  "type": "string",
  "action": "sv",
  "command": "Reconf",
  "name": "WiFi Configuration Update",
  "variable_name": "Device.WiFi.SSID.1.SSID",
  "value": "CorporateNetwork_2024",
  "is_pending": false,
  "is_applied": true,
  "status": 200,
  "message": "Configuration applied successfully"
}

Response Codes:

Status Description
200 Success - Returns the requested device log entry
401 Unauthorized - Invalid or missing authentication token
403 Forbidden - Insufficient permissions to access this log entry
404 Not Found - Log entry with specified ID does not exist

Data Models

Device Log Entry Fields

Field Type Description
id integer Unique identifier for the log entry (read-only)
created datetime Timestamp when the log entry was created
last_change datetime Timestamp of the last status update (read-only)
user integer ID of the user who initiated the action (null for system-initiated)
parent integer ID of the device this log entry belongs to
type string Data type of the parameter being modified
action string Type of action performed (see Action Codes below)
command string Specific command or event type (see Command Types below)
name string Human-readable description of the operation
variable_name string Technical parameter name as expected by the device
value string Parameter value or command data
is_pending boolean Whether the operation is awaiting execution
is_applied boolean Whether the operation has been successfully applied
status integer Operational status code (see Status Codes below)
message string Detailed message from the device or system

Action Codes

Code Description Usage
sv Set Value Setting a parameter value
uv Unset Value Removing or clearing a parameter
gv Get Value Retrieving a parameter value
sa Set Attribute Modifying parameter attributes
cr Create Creating new objects or instances
de Delete Deleting objects or instances
cm Command Executing device commands
ev Event System or device events
er Error Error conditions
ar Alert Raised Alert notifications
ac Alert Cleared Alert resolution

Status Codes

Code Description
0 Pending - Operation queued for execution
100 Sent - Command sent to device
200 OK - Operation completed successfully
400 Invalid Parameter - Parameter name or format invalid
401 Authentication Error - Device authentication failed
403 Forbidden - Operation not permitted
404 Invalid Request - Request format invalid
406 Invalid Value - Parameter value invalid
500 Error - General operation error
504 Timeout - Operation timed out

Common Use Cases

Use Case 1: Monitor Recent Device Activities

Track all recent operations across devices to maintain operational awareness.

# Get logs from the last 24 hours
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_log/?datetime__gte=2024-01-15T00:00:00Z&limit=100" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 2: Troubleshoot Failed Operations

Identify and investigate operations that failed or are stuck in pending status.

# Find failed operations (status >= 400)
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_log/?is_applied=false&datetime__gte=2024-01-15" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 3: Audit Configuration Changes

Generate reports of all configuration changes for compliance purposes.

# Get all configuration changes (set/unset actions)
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_log/?action=sv&datetime__gte=2024-01-01&datetime__lte=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 4: Monitor Device Alerts

Track alert patterns and frequencies across your device fleet.

# Get all raised alerts in the last week
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_log/?action=ar&datetime__gte=2024-01-08" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 5: Track Specific Device History

Review complete operational history for a specific device.

# Get all logs for device ID 123
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_log/?parent__id=123&limit=500" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Best Practices

Efficient Filtering:

Pagination Management:

Performance Optimization:

Error Handling:

Security Considerations:

Monitoring and Alerting:

Inventory Device Name

Endpoints Summary

Method Path Swagger
GET /inventory_device_name/ Swagger ↗
POST /inventory_device_name/ Swagger ↗
GET /inventory_device_name/{name}/ Swagger ↗
PUT /inventory_device_name/{name}/ Swagger ↗
PATCH /inventory_device_name/{name}/ Swagger ↗
DELETE /inventory_device_name/{name}/ Swagger ↗

The Inventory Device Name API provides comprehensive management capabilities for network devices in the Zequenze Control platform. These endpoints enable full CRUD operations for device inventory management, including device registration, configuration, monitoring, and control operations like reboots and factory resets.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Name API is the core interface for managing network devices within the Zequenze Control system. This API category handles device lifecycle management, from initial registration through ongoing monitoring and maintenance operations.

Key capabilities include:

The API uses device names as the primary identifier for individual device operations, while supporting various filtering options for bulk operations. All device data includes both user-configurable fields (name, location, credentials) and system-generated information (status, connection history, hardware details).

Endpoints

GET /inventory_device_name/

Description: Retrieves a paginated list of all devices in your inventory. This endpoint supports extensive filtering options to help you find specific devices based on status, type, organization, or recent activity. It's the primary endpoint for building device dashboards, monitoring systems, and bulk operations.

Use Cases:

Full URL Example:

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

Parameters:

Parameter Type In Required Description
type integer query No Filter devices by device profile/type ID
status string query No Filter by device status. Use '0', 'false', 'False' for Down devices; '1', 'true', 'True' for Up devices
last_status_change_from string query No Filter devices with status changes after specified datetime (ISO format: 2000-01-01 or 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 pagination applies)
offset integer query No Starting index for pagination
pending boolean query No Include information about pending device settings
update_status boolean query No Refresh device status from configured helpers before returning data

cURL Example:

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

Example Response:

{
  "count": 847,
  "next": "https://control.zequenze.com/api/v1/inventory_device_name/?limit=25&offset=25",
  "previous": null,
  "results": [
    {
      "id": 1001,
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Router-Office-Main",
      "customer_id": "CUST-12345",
      "is_active": true,
      "status": "Up",
      "status_change": "2024-01-15T08:30:00Z",
      "type": 5,
      "type_short_name": "CPE-Router",
      "software_version": "1.4.2",
      "hardware_version": "Rev C",
      "manufacturer": "TechCorp",
      "unique_identifier": "MAC:00:1B:44:11:3A:B7",
      "product_class": "InternetGatewayDevice",
      "serial_number": "TC240115001",
      "serial_number_alt": "ALT-240115-001",
      "description": "Main office internet router",
      "organization_id": 123,
      "firmware_image": 89,
      "firmware_image_is_pending": false,
      "location_name": "Corporate Headquarters",
      "location": 45,
      "location_short_name": "HQ-Main",
      "latitude": "40.7128",
      "longitude": "-74.0060",
      "username": "device_001",
      "update_frequency": 300,
      "address": "192.168.1.1",
      "last_connection": "2024-01-15T14:22:33Z",
      "last_configuration": "2024-01-15T09:15:20Z",
      "last_change": "2024-01-15T09:15:20Z",
      "created": "2024-01-10T10:00:00Z",
      "debug": false,
      "reboot": false,
      "factory": false,
      "device_factory": false,
      "sync": false,
      "reconf": false,
      "pending_settings": "None"
    }
  ]
}

Response Codes:

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

POST /inventory_device_name/

Description: Creates a new device in your inventory. This endpoint registers a new device with the system, allowing you to set initial configuration, assign it to an organization and location, and configure management credentials. The device will be available for management operations once created.

Use Cases:

Full URL Example:

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

cURL Example:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_name/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Router-Branch-Office-A",
    "customer_id": "CUST-67890",
    "is_active": true,
    "type": 5,
    "serial_number": "TC240116002",
    "description": "Branch office A primary router",
    "organization_id": 124,
    "location": 46,
    "latitude": "34.0522",
    "longitude": "-118.2437",
    "username": "branch_router_a",
    "password": "secure_password_123",
    "update_frequency": 300
  }'

Example Response:

{
  "id": 1002,
  "uuid": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Router-Branch-Office-A",
  "customer_id": "CUST-67890",
  "is_active": true,
  "status": null,
  "status_change": null,
  "type": 5,
  "type_short_name": "CPE-Router",
  "software_version": null,
  "hardware_version": null,
  "manufacturer": null,
  "unique_identifier": null,
  "product_class": null,
  "serial_number": "TC240116002",
  "serial_number_alt": null,
  "description": "Branch office A primary router",
  "organization_id": 124,
  "firmware_image": null,
  "firmware_image_is_pending": false,
  "location_name": null,
  "location": 46,
  "location_short_name": "Branch-A",
  "latitude": "34.0522",
  "longitude": "-118.2437",
  "username": "branch_router_a",
  "password": "secure_password_123",
  "update_frequency": 300,
  "address": null,
  "last_connection": null,
  "last_configuration": null,
  "last_change": null,
  "created": "2024-01-16T10:30:00Z",
  "debug": false,
  "reboot": false,
  "factory": false,
  "device_factory": false,
  "sync": false,
  "reconf": false,
  "pending_settings": "None"
}

Response Codes:

Status Description
201 Created - Device successfully added to inventory
400 Bad Request - Invalid device data or missing required fields
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient permissions
409 Conflict - Device name already exists

GET /inventory_device_name/{name}/

Description: Retrieves detailed information for a specific device identified by its name. This endpoint provides complete device information including current status, configuration, hardware details, and connection history. Use this for device-specific monitoring and troubleshooting.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name/Router-Office-Main/?pending=true&update_status=true

Parameters:

Parameter Type In Required Description
name string path Yes Device name (URL encoded if contains special characters)
pending boolean query No Include pending settings information in response
update_status boolean query No Update device status from helpers before returning data

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_name/Router-Office-Main/?pending=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "id": 1001,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Router-Office-Main",
  "customer_id": "CUST-12345",
  "is_active": true,
  "status": "Up",
  "status_change": "2024-01-15T08:30:00Z",
  "type": 5,
  "type_short_name": "CPE-Router",
  "software_version": "1.4.2",
  "hardware_version": "Rev C",
  "manufacturer": "TechCorp",
  "unique_identifier": "MAC:00:1B:44:11:3A:B7",
  "product_class": "InternetGatewayDevice",
  "serial_number": "TC240115001",
  "serial_number_alt": "ALT-240115-001",
  "description": "Main office internet router",
  "organization_id": 123,
  "firmware_image": 89,
  "firmware_image_is_pending": false,
  "location_name": "Corporate Headquarters",
  "location": 45,
  "location_short_name": "HQ-Main",
  "latitude": "40.7128",
  "longitude": "-74.0060",
  "username": "device_001",
  "update_frequency": 300,
  "address": "192.168.1.1",
  "last_connection": "2024-01-16T14:22:33Z",
  "last_configuration": "2024-01-15T09:15:20Z",
  "last_change": "2024-01-15T09:15:20Z",
  "created": "2024-01-10T10:00:00Z",
  "debug": false,
  "reboot": false,
  "factory": false,
  "device_factory": false,
  "sync": false,
  "reconf": false,
  "pending_settings": "WiFi password update, Firmware upgrade to v1.4.3"
}

Response Codes:

Status Description
200 Success - Returns device details
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient permissions
404 Not Found - Device with specified name does not exist

PUT /inventory_device_name/{name}/

Description: Completely updates a device's configuration by replacing all editable fields. This endpoint requires all writable fields to be provided and will overwrite the existing device configuration. Use for complete device reconfiguration or when you need to ensure all fields are set to specific values.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name/Router-Office-Main/

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_name/Router-Office-Main/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Router-Office-Main",
    "customer_id": "CUST-12345-UPDATED",
    "is_active": true,
    "type": 5,
    "serial_number": "TC240115001",
    "serial_number_alt": "ALT-240115-001-UPD",
    "description": "Main office internet router - Updated configuration",
    "organization_id": 123,
    "firmware_image": 92,
    "firmware_image_is_pending": true,
    "location_name": "Corporate Headquarters - Building A",
    "location": 45,
    "latitude": "40.7128",
    "longitude": "-74.0060",
    "username": "device_001_updated",
    "password": "new_secure_password_456",
    "update_frequency": 600,
    "debug": false,
    "reboot": false,
    "factory": false,
    "device_factory": false,
    "sync": true,
    "reconf": false
  }'

Example Response:

{
  "id": 1001,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Router-Office-Main",
  "customer_id": "CUST-12345-UPDATED",
  "is_active": true,
  "status": "Up",
  "status_change": "2024-01-15T08:30:00Z",
  "type": 5,
  "type_short_name": "CPE-Router",
  "software_version": "1.4.2",
  "hardware_version": "Rev C",
  "manufacturer": "TechCorp",
  "unique_identifier": "MAC:00:1B:44:11:3A:B7",
  "product_class": "InternetGatewayDevice",
  "serial_number": "TC240115001",
  "serial_number_alt": "ALT-240115-001-UPD",
  "description": "Main office internet router - Updated configuration",
  "organization_id": 123,
  "firmware_image": 92,
  "firmware_image_is_pending": true,
  "location_name": "Corporate Headquarters - Building A",
  "location": 45,
  "location_short_name": "HQ-Main",
  "latitude": "40.7128",
  "longitude": "-74.0060",
  "username": "device_001_updated",
  "update_frequency": 600,
  "address": "192.168.1.1",
  "last_connection": "2024-01-16T14:22:33Z",
  "last_configuration": "2024-01-16T15:45:12Z",
  "last_change": "2024-01-16T15:45:12Z",
  "created": "2024-01-10T10:00:00Z",
  "debug": false,
  "reboot": false,
  "factory": false,
  "device_factory": false,
  "sync": true,
  "reconf": false,
  "pending_settings": "Sync requested, Firmware upgrade to v1.4.5 pending"
}

Response Codes:

Status Description
200 Success - Device configuration updated
400 Bad Request - Invalid data or missing required fields
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient permissions
404 Not Found - Device with specified name does not exist

PATCH /inventory_device_name/{name}/

Description: Partially updates a device's configuration by modifying only the specified fields. This endpoint allows you to update individual device properties without affecting other settings. It's ideal for making targeted changes like updating credentials, triggering operations, or modifying specific configuration parameters.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name/Router-Office-Main/

cURL Example:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device_name/Router-Office-Main/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description for main office router",
    "firmware_image": 95,
    "firmware_image_is_pending": true,
    "reboot": true,
    "sync": true
  }'

Example Response:

{
  "id": 1001,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Router-Office-Main",
  "customer_id": "CUST-12345-UPDATED",
  "is_active": true,
  "status": "Up",
  "status_change": "2024-01-15T08:30:00Z",
  "type": 5,
  "type_short_name": "CPE-Router",
  "software_version": "1.4.2",
  "hardware_version": "Rev C",
  "manufacturer": "TechCorp",
  "unique_identifier": "MAC:00:1B:44:11:3A:B7",
  "product_class": "InternetGatewayDevice",
  "serial_number": "TC240115001",
  "serial_number_alt": "ALT-240115-001-UPD",
  "description": "Updated description for main office router",
  "organization_id": 123,
  "firmware_image": 95,
  "firmware_image_is_pending": true,
  "location_name": "Corporate Headquarters - Building A",
  "location": 45,
  "location_short_name": "HQ-Main",
  "latitude": "40.7128",
  "longitude": "-74.0060",
  "username": "device_001_updated",
  "update_frequency": 600,
  "address": "192.168.1.1",
  "last_connection": "2024-01-16T14:22:33Z",
  "last_configuration": "2024-01-16T15:45:12Z",
  "last_change": "2024-01-16T16:20:30Z",
  "created": "2024-01-10T10:00:00Z",
  "debug": false,
  "reboot": true,
  "factory": false,
  "device_factory": false,
  "sync": true,
  "reconf": false,
  "pending_settings": "Reboot requested, Sync requested, Firmware upgrade to v1.4.7 pending"
}

Response Codes:

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

DELETE /inventory_device_name/{name}/

Description: Permanently removes a device from your inventory. This operation cannot be undone and will delete all associated device configuration, history, and settings. Use with caution and ensure the device is no longer needed in your management system.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name/Router-Office-Main/

Parameters:

Parameter Type In Required Description
name string path Yes Device name to delete (URL encoded if contains special characters)

cURL Example:

curl -X DELETE "https://control.zequenze.com/api/v1/inventory_device_name/Router-Old-Decommissioned/" \
  -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 device
404 Not Found - Device with specified name does not exist
409 Conflict - Device cannot be deleted (may have active connections or dependencies)

Common Use Cases

Device Status Dashboard

Build a real-time dashboard showing device health across your network by using the GET list endpoint with status filtering and regular polling.

# Get all online devices
https://control.zequenze.com/api/v1/inventory_device_name/?status=1&update_status=true

# Get devices that recently went offline
https://control.zequenze.com/api/v1/inventory_device_name/?status=0&last_status_change_from=2024-01-15T00:00:00

Bulk Firmware Management

Manage firmware updates across multiple devices by filtering by device type and organization, then using PATCH to assign firmware images.

# Find all CPE routers in organization 123
https://control.zequenze.com/api/v1/inventory_device_name/?type=5&organization=123

# Update firmware for specific devices using PATCH with firmware_image and firmware_image_is_pending

Device Provisioning Workflow

Automate device deployment by creating devices with POST, configuring initial settings, then using device operations to sync and activate.

# 1. Create device with POST
# 2. Use PATCH to set sync=true to synchronize initial configuration
# 3. Monitor device status until it comes online

Remote Device Operations

Execute remote operations on devices using PATCH with operation flags like reboot, sync, factory reset.

# Reboot a device
PATCH /inventory_device_name/device-name/ with {"reboot": true}

# Factory reset and reconfigure
PATCH /inventory_device_name/device-name/ with {"factory": true, "reconf": true}

Location-Based Device Management

Organize and manage devices by geographic location using location fields and filtering for field technician workflows.

# Get all devices at a specific location
https://control.zequenze.com/api/v1/inventory_device_name/?location=45

# Update device location
PATCH /inventory_device_name/device-name/ with {"location": 46, "latitude": "34.0522", "longitude": "-118.2437"}

Best Practices

Inventory Device Name Diags

Endpoints Summary

Method Path Swagger
POST /inventory_device_name_diags/ Swagger ↗
GET /inventory_device_name_diags/ Swagger ↗

The Inventory Device Name Diagnostics API provides endpoints for scheduling and monitoring network diagnostic operations on specific network devices. These endpoints allow you to initiate various network tests such as ping, traceroute, speed tests, and WiFi diagnostics, as well as retrieve the status and results of previously scheduled diagnostic operations.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Name Diagnostics API enables network administrators and developers to perform comprehensive network diagnostics on managed devices remotely. This API category is essential for network monitoring, troubleshooting connectivity issues, and performing routine network health checks.

Key Features:

Common Integration Scenarios:

The API follows a simple pattern: use POST to schedule new diagnostic operations and GET to retrieve status updates and results. Each diagnostic operation is tied to a specific device name and can be configured with operation-specific parameters.

Endpoints

POST /inventory_device_name_diags/

Description: Schedules a new network diagnostic operation on a specified device. This endpoint allows you to initiate various types of network tests including connectivity checks, performance measurements, and WiFi diagnostics. The operation is queued and executed asynchronously on the target device.

Use Cases:

Full URL Example:

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

Request Body Schema:

Field Type Required Description
name string Yes Name of the target device to run diagnostics on
operation string Yes Type of diagnostic operation (download, upload, ipping, udpecho, traceroute, dnslookup, wifi.neighbor)
target string Yes Target for the operation (URL for speed tests, IP for ping/traceroute, hostname for DNS lookup)
upload_size string No File size in MB for upload tests (e.g., "10")
count integer No Number of packets/repetitions (default: 5 for ping, 1 for DNS)
size integer No Packet size in bytes for ping operations (default: 64)
timeout integer No Timeout in seconds for ping and DNS operations (default: 1)
max_hops integer No Maximum hops for traceroute operations (default: 30)
interface string No Network interface name to use for the operation

cURL Example (Ping Test):

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_name_diags/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "router-main-office",
    "operation": "ipping",
    "target": "8.8.8.8",
    "count": 10,
    "size": 64,
    "timeout": 2
  }'

cURL Example (Speed Test):

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_name_diags/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "cpe-customer-001",
    "operation": "download",
    "target": "http://speedtest.example.com/test-file.zip",
    "interface": "eth0"
  }'

Example Response:

{
  "name": "router-main-office",
  "operation": "ipping",
  "target": "8.8.8.8",
  "count": 10,
  "size": 64,
  "timeout": 2,
  "upload_size": null,
  "max_hops": null,
  "interface": null
}

Response Codes:

Status Description
201 Created - Diagnostic operation scheduled successfully
400 Bad Request - Invalid operation type or missing required fields
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Device name not found in inventory

GET /inventory_device_name_diags/

Description: Retrieves the status and results of scheduled diagnostic operations. This endpoint can return all diagnostic operations or filter by specific transaction ID. Use this to monitor the progress of tests and collect results once operations are complete.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_diags/?id=diag_12345&update_status=true

Parameters:

Parameter Type In Required Description
id string query No Filter results by specific diagnostic transaction ID
update_status boolean query No Refresh device status before returning results (may increase response time)

cURL Example (All Operations):

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_name_diags/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

cURL Example (Specific Operation):

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

Example Response:

[
  {
    "name": "router-main-office",
    "operation": "ipping",
    "target": "8.8.8.8",
    "count": 10,
    "size": 64,
    "timeout": 2,
    "upload_size": null,
    "max_hops": null,
    "interface": null,
    "status": "completed",
    "results": {
      "packets_sent": 10,
      "packets_received": 10,
      "packet_loss": "0%",
      "avg_rtt": "12.5ms",
      "min_rtt": "11.2ms",
      "max_rtt": "15.1ms"
    },
    "created_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T10:30:15Z"
  },
  {
    "name": "cpe-customer-001",
    "operation": "download",
    "target": "http://speedtest.example.com/test-file.zip",
    "upload_size": null,
    "count": null,
    "size": null,
    "timeout": null,
    "max_hops": null,
    "interface": "eth0",
    "status": "running",
    "results": null,
    "created_at": "2024-01-15T10:35:00Z",
    "completed_at": null
  }
]

Response Codes:

Status Description
200 Success - Returns diagnostic operation data
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Specified diagnostic ID not found

Common Use Cases

Use Case 1: Automated Connectivity Monitoring

Schedule periodic ping tests to critical infrastructure and monitor results to detect connectivity issues before they impact users.

# Schedule ping test
POST /inventory_device_name_diags/
{
  "name": "core-router-01",
  "operation": "ipping", 
  "target": "8.8.8.8",
  "count": 5
}

# Check results
GET /inventory_device_name_diags/?id=<transaction_id>

Use Case 2: Customer Support Troubleshooting

When a customer reports slow internet, initiate speed tests and traceroute diagnostics to identify the source of performance issues.

# Run download speed test
POST /inventory_device_name_diags/
{
  "name": "customer-cpe-12345",
  "operation": "download",
  "target": "http://speedtest.local/100MB.bin"
}

# Run traceroute to identify routing issues  
POST /inventory_device_name_diags/
{
  "name": "customer-cpe-12345", 
  "operation": "traceroute",
  "target": "google.com"
}

Use Case 3: WiFi Environment Analysis

Analyze WiFi networks in the area to troubleshoot interference issues or optimize channel selection.

# Scan for neighboring WiFi networks
POST /inventory_device_name_diags/
{
  "name": "office-ap-01",
  "operation": "wifi.neighbor",
  "target": "2.4GHz"
}

Use Case 4: DNS Resolution Verification

Verify that devices can properly resolve domain names, which is critical for internet connectivity.

# Test DNS resolution
POST /inventory_device_name_diags/
{
  "name": "branch-router",
  "operation": "dnslookup", 
  "target": "google.com",
  "count": 3,
  "timeout": 5
}

Use Case 5: Network Performance Baseline

Establish performance baselines by running regular upload/download tests during different times of day.

# Upload speed test
POST /inventory_device_name_diags/  
{
  "name": "test-device",
  "operation": "upload",
  "target": "http://speedtest.local/upload",
  "upload_size": "50"
}

Best Practices

Inventory Device Name Headless Operation

Endpoints Summary

Method Path Swagger
GET /inventory_device_name_headless_operation/ Swagger ↗
POST /inventory_device_name_headless_operation/ Swagger ↗

The Inventory Device Name Headless Operation API enables automated remote management of network devices through headless operations. These endpoints allow you to schedule and execute device operations such as getting parameter values, setting configurations, adding objects, and deleting objects without manual intervention.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Name Headless Operation API provides programmatic control over device management operations in your network infrastructure. This API is designed for network administrators and developers who need to automate device configuration, monitoring, and maintenance tasks across multiple devices simultaneously.

Key Features:

Common Use Cases:

The API operates on TR-069/CWMP protocol standards, allowing you to interact with device parameters using standard device model paths (e.g., Device.ManagementServer.PeriodicInformInterval).

Endpoints

GET /inventory_device_name_headless_operation/

Description: Retrieves a list of scheduled headless operations for network devices. This endpoint allows you to monitor existing operations, check their status, and optionally update device status information before returning results.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_headless_operation/?id=txn_12345&update_status=true

Parameters:

Parameter Type In Required Description
id string query No ID of the specific scheduled transaction to retrieve
update_status boolean query No When true, uses configured helpers to update device status before returning information

cURL Example:

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

Example Response:

[
  {
    "name": "router-office-001",
    "operation": "get",
    "variables": [
      {
        "variable_name": "Device.ManagementServer.PeriodicInformInterval"
      },
      {
        "variable_name": "Device.WiFi.SSID.1.Stats.BytesReceived"
      }
    ]
  },
  {
    "name": "router-office-002",
    "operation": "set",
    "variables": [
      {
        "variable_name": "Device.ManagementServer.PeriodicInformInterval",
        "value": "300",
        "value_type": "integer"
      },
      {
        "variable_name": "Device.ManagementServer.PeriodicInformEnable",
        "value": "1",
        "value_type": "boolean"
      }
    ]
  }
]

Response Codes:

Status Description
200 Success - Returns list of scheduled operations
401 Unauthorized - Invalid or missing API token
404 Not Found - Specified transaction ID does not exist
500 Internal Server Error - Server processing error

POST /inventory_device_name_headless_operation/

Description: Creates a new scheduled headless operation for a network device. This endpoint allows you to define device operations including parameter retrieval, configuration changes, object management, and variable assignments.

Use Cases:

Full URL Example:

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

Parameters:

Parameter Type In Required Description
data object body Yes Complete operation definition including device name, operation type, and variables

Request Body Schema:

{
  "name": "string (required) - Name of the target device",
  "operation": "string (required) - Operation type: get, set, add.obj, del.obj",
  "variables": [
    {
      "variable_name": "string (required) - Device parameter path",
      "value": "string (optional) - Value for set operations",
      "value_type": "string (optional) - Data type: integer, boolean, string"
    }
  ]
}

cURL Example (GET Operation):

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_name_headless_operation/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "router-branch-005",
    "operation": "get",
    "variables": [
      {"variable_name": "Device.ManagementServer.PeriodicInformInterval"},
      {"variable_name": "Device.WiFi.SSID.1.Enable"}
    ]
  }'

cURL Example (SET Operation):

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_name_headless_operation/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "router-branch-005",
    "operation": "set",
    "variables": [
      {
        "variable_name": "Device.ManagementServer.PeriodicInformInterval",
        "value": "600",
        "value_type": "integer"
      },
      {
        "variable_name": "Device.WiFi.SSID.1.Enable",
        "value": "true",
        "value_type": "boolean"
      }
    ]
  }'

Example Response:

{
  "name": "router-branch-005",
  "operation": "set",
  "variables": [
    {
      "variable_name": "Device.ManagementServer.PeriodicInformInterval",
      "value": "600",
      "value_type": "integer"
    },
    {
      "variable_name": "Device.WiFi.SSID.1.Enable",
      "value": "true",
      "value_type": "boolean"
    }
  ]
}

Response Codes:

Status Description
201 Created - Operation successfully scheduled
400 Bad Request - Invalid operation parameters or malformed JSON
401 Unauthorized - Invalid or missing API token
404 Not Found - Specified device does not exist
422 Unprocessable Entity - Valid JSON but invalid operation configuration

Common Use Cases

Use Case 1: Automated Device Monitoring

Regularly collect device statistics and performance metrics from multiple network devices for monitoring dashboards and alerting systems.

Endpoints: GET to check existing operations, POST to schedule new monitoring tasks

Use Case 2: Bulk Configuration Deployment

Deploy standardized configuration settings across multiple devices in a network, such as updating security parameters or Wi-Fi settings.

Endpoints: POST to create set operations with standardized variable values

Use Case 3: Network Maintenance Automation

Automate routine maintenance tasks like clearing statistics, updating inform intervals, or managing device objects during scheduled maintenance windows.

Endpoints: POST with add.obj and del.obj operations for object management

Use Case 4: Device Status Verification

Verify current device configurations and settings after deployment or troubleshooting to ensure consistency across the network.

Endpoints: GET with update_status=true to retrieve real-time device information

Use Case 5: Integration with Network Management Systems

Integrate with existing NMS platforms to provide automated device management capabilities through API calls.

Endpoints: Both GET and POST for comprehensive device operation management

Best Practices

Operation Types:

Error Handling:

Performance Optimization:

Security Considerations:

Data Type Guidelines:

Inventory Device Name Ipping

Endpoints Summary

Method Path Swagger
GET /inventory_device_name_ipping/{name}/ Swagger ↗

The inventory device name ipping endpoint provides functionality to retrieve device information by name, specifically focused on IP ping capabilities and network connectivity status for inventory management systems.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The inventory device name ipping API category is designed for network administrators and IT teams who need to retrieve device information based on device names, with a specific focus on IP ping capabilities and network connectivity monitoring. This endpoint is particularly useful for inventory management systems that need to verify device connectivity status, perform network diagnostics, or retrieve device information for monitoring dashboards.

Common scenarios include automated network health checks, device discovery processes, and integration with monitoring systems that need to correlate device names with their ping status and connectivity information. The endpoint provides essential device data that can be used to determine if a device is reachable on the network and retrieve its current operational status.

This API is typically used in conjunction with other inventory management endpoints to provide a complete picture of device status and network topology within an organization's infrastructure.

Endpoints

GET /inventory_device_name_ipping/{name}/

Description: Retrieves device information and ping status for a specific device identified by its name. This endpoint is essential for network monitoring applications that need to check device connectivity and retrieve basic device information for inventory management purposes.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_ipping/server-01/

Parameters:

Parameter Type In Required Description
name string path Yes The unique name identifier of the device to retrieve ping information for

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_name_ipping/server-01/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "id": 1247,
  "name": "server-01",
  "ip_address": "192.168.1.100",
  "ping_status": "active",
  "last_ping_time": "2024-01-15T14:30:25Z",
  "response_time_ms": 12,
  "device_type": "server",
  "location": "Data Center A",
  "status": "online",
  "uptime_percentage": 99.8
}

Response Codes:

Status Description
200 Success - Returns device information and ping status
401 Unauthorized - Invalid or missing API token
404 Not Found - Device with specified name does not exist
500 Internal Server Error - Server error occurred while retrieving device data

Common Use Cases

Use Case 1: Network Health Dashboard

Monitor the connectivity status of critical infrastructure devices by querying their ping status and response times. Use this endpoint to populate real-time network health dashboards that display device availability and performance metrics.

Use Case 2: Automated Network Diagnostics

Implement automated scripts that check device connectivity as part of routine network maintenance. The endpoint can be used to identify devices that may be experiencing network issues or are unreachable.

Use Case 3: Inventory Verification

Validate that devices listed in your inventory system are actually accessible on the network. This is particularly useful during asset audits or when onboarding new devices to ensure proper network configuration.

Use Case 4: Troubleshooting Integration

Integrate with helpdesk or ticketing systems to automatically check device connectivity when support tickets are created, providing technicians with immediate network status information.

Best Practices

Inventory Device Name Operation

Endpoints Summary

Method Path Swagger
PUT /inventory_device_name_operation/{name}/ Swagger ↗

The Inventory Device Name Operation API enables remote device management operations on specific devices in your inventory. This endpoint allows you to execute critical device operations such as rebooting, factory resets, configuration sync, and device reconfiguration by targeting devices using their unique names.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Name Operation API provides a powerful interface for performing remote management operations on devices within your inventory system. This API is specifically designed for network administrators, IT operations teams, and automated systems that need to execute device management commands remotely.

Key capabilities include:

This endpoint is particularly valuable in scenarios such as troubleshooting network issues, performing scheduled maintenance, deploying configuration changes, or recovering devices that have become unresponsive. The API supports various operation types including standard reboots, factory resets, configuration synchronization, and complete device reconfiguration.

The operations are executed asynchronously, allowing your applications to continue processing while device operations complete in the background. This makes it ideal for integration with monitoring systems, ticketing platforms, and automated incident response workflows.

Endpoints

PUT /inventory_device_name_operation/{name}/

Description: Executes a specified operation on a device identified by its name. This endpoint allows you to perform critical device management tasks remotely, including reboots, factory resets, configuration sync, and reconfiguration operations. The operation is executed immediately upon successful API call.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_operation/office-router-01/

Parameters:

Parameter Type In Required Description
name string path Yes The unique name/identifier of the device to perform the operation on
data string body Yes JSON payload containing the operation details and parameters

Request Body Schema:

Field Type Required Description Allowed Values
operation string Yes The operation to perform on the device reboot, factory, device_factory, sync, reconf

Operation Types:

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_name_operation/office-router-01/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "reboot"
  }'

Example Request (Reboot Operation):

{
  "operation": "reboot"
}

Example Request (Configuration Sync):

{
  "operation": "sync"
}

Example Response:

{
  "id": 12345,
  "operation": "reboot",
  "device_name": "office-router-01",
  "status": "initiated",
  "timestamp": "2024-01-15T14:30:25Z",
  "execution_id": "op_67890abcdef",
  "estimated_completion": "2024-01-15T14:32:25Z"
}

Response Codes:

Status Description
200 Success - Operation initiated successfully
400 Bad Request - Invalid operation type or malformed request
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Device with specified name does not exist
409 Conflict - Device is currently offline or another operation is in progress
500 Internal Server Error - Failed to initiate operation

Common Use Cases

Use Case 1: Automated Incident Response

When monitoring systems detect device connectivity issues, automatically trigger a reboot operation using the reboot operation type. This can resolve many common network issues without manual intervention.

Use Case 2: Scheduled Maintenance Operations

Integrate with scheduling systems to perform configuration sync operations (sync) during maintenance windows, ensuring all devices have the latest approved configurations.

Use Case 3: Device Deployment Pipeline

Use the reconf operation as part of automated device deployment workflows when devices need to be reconfigured for new roles or locations.

Use Case 4: Security Incident Recovery

Execute factory or device_factory operations on compromised devices to ensure complete removal of potentially malicious configurations or software.

Use Case 5: Configuration Drift Remediation

Regularly use the sync operation to detect and correct configuration drift across your device inventory, maintaining compliance with organizational standards.

Best Practices

Operation Planning:

Error Handling:

Security Considerations:

Performance Optimization:

Monitoring Integration:

Inventory Device Name Setting

Endpoints Summary

Method Path Swagger
GET /inventory_device_name_setting/ Swagger ↗
PUT /inventory_device_name_setting/{parent__name}/ Swagger ↗
PATCH /inventory_device_name_setting/{parent__name}/ Swagger ↗

The Device Name Settings API provides endpoints to manage configuration parameters and settings for specific devices in your inventory. These endpoints allow you to retrieve, update, and modify device-specific parameters such as network configurations, operational settings, and custom properties identified by the device name. This is essential for device configuration management and monitoring in network infrastructure.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Name Setting API category enables comprehensive management of device configuration parameters within your network infrastructure. These endpoints are designed to work with individual devices identified by their names, allowing you to retrieve current settings, update configurations, and perform partial modifications to device parameters.

Key Concepts:

Common Integration Patterns:

These endpoints work together to provide a complete device configuration lifecycle, from initial setup through ongoing management and updates.

Endpoints

GET /inventory_device_name_setting/

Description: Retrieves a paginated list of configuration settings for a specified device. This endpoint is essential for viewing current device configurations, auditing settings, and preparing for configuration updates. It supports extensive filtering capabilities to narrow down results based on parameter characteristics.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_setting/?parent__name=router-01&parameter__name=ip_address&pending=false

Parameters:

Parameter Type In Required Description
parent__name string query Yes The exact name of the device whose settings you want to retrieve
parameter_id string query No Filter by specific parameter ID to retrieve a particular setting
parameter__variable_name string query No Filter settings by the parameter's variable name (technical identifier)
parameter__name string query No Filter settings by the parameter's display name (human-readable)
parameter__short_name string query No Filter settings by the parameter's abbreviated name
limit integer query No Number of results to return per page (default varies, typically 20-100)
offset integer query No Starting index for pagination (use with limit for page navigation)
pending boolean query No Filter to show only settings with pending changes (true/false)

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_name_setting/?parent__name=switch-main-floor&parameter__name=vlan&limit=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 125,
  "next": "https://control.zequenze.com/api/v1/inventory_device_name_setting/?limit=50&offset=50&parent__name=switch-main-floor",
  "previous": null,
  "results": [
    {
      "id": 1001,
      "parent_id": "dev_12345",
      "parent__name": "switch-main-floor",
      "parameter": {
        "id": 45,
        "name": "VLAN Configuration",
        "short_name": "vlan-config",
        "variable_name": "vlan_settings",
        "type": "table",
        "position": 10,
        "required": true,
        "read_only": false,
        "metric": false,
        "group": {
          "id": 5,
          "name": "Network Configuration"
        }
      },
      "value": "100,200,300",
      "extra": false,
      "extra_value": null,
      "created": "2024-01-15T08:30:00Z",
      "last_change": "2024-01-20T14:22:33Z",
      "pending": false
    },
    {
      "id": 1002,
      "parent_id": "dev_12345",
      "parent__name": "switch-main-floor",
      "parameter": {
        "id": 46,
        "name": "Management IP Address",
        "short_name": "mgmt-ip",
        "variable_name": "management_ip",
        "type": "string",
        "position": 5,
        "required": true,
        "read_only": false,
        "metric": true,
        "group": {
          "id": 5,
          "name": "Network Configuration"
        }
      },
      "value": "192.168.1.100",
      "extra": false,
      "extra_value": null,
      "created": "2024-01-15T08:30:00Z",
      "last_change": "2024-01-18T09:15:22Z",
      "pending": true
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns device settings with pagination metadata
400 Bad Request - Missing required parent__name parameter or invalid filter values
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Device with specified name does not exist

PUT /inventory_device_name_setting/{parent__name}/

Description: Performs a complete update of device settings for the specified device. This endpoint replaces all existing settings with the provided configuration data. Use this for full device reconfiguration or when you need to ensure the device has exactly the settings you specify, removing any not included in the request.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_setting/firewall-dmz-01/

Parameters:

Parameter Type In Required Description
parent__name string path Yes The exact name of the device to update (must match existing device)
data object body Yes Complete configuration data object containing all device settings

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_name_setting/firewall-dmz-01/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": [
      {
        "parameter_id": 10,
        "value": "192.168.100.1"
      },
      {
        "parameter_id": 11,
        "value": "enabled"
      }
    ]
  }'

Example Response:

{
  "id": 2001,
  "parent_id": "dev_67890",
  "parent__name": "firewall-dmz-01",
  "parameter": {
    "id": 10,
    "name": "External Interface IP",
    "short_name": "ext-ip",
    "variable_name": "external_interface_ip",
    "type": "string",
    "position": 1,
    "required": true,
    "read_only": false,
    "metric": true,
    "group": {
      "id": 8,
      "name": "Interface Configuration",
      "service": null,
      "discovery_group": null,
      "title": "Network Interfaces"
    }
  },
  "value": "192.168.100.1",
  "extra": false,
  "extra_value": null,
  "created": "2024-01-15T08:30:00Z",
  "last_change": "2024-01-22T16:45:12Z",
  "pending": true
}

Response Codes:

Status Description
200 Success - Device settings updated successfully
400 Bad Request - Invalid configuration data or parameter values
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Device with specified name does not exist
422 Validation Error - Configuration data fails validation rules

PATCH /inventory_device_name_setting/{parent__name}/

Description: Performs a partial update of device settings, modifying only the specified parameters while leaving other settings unchanged. This endpoint is ideal for targeted configuration changes and incremental updates without affecting the entire device configuration.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_setting/router-branch-office/

Parameters:

Parameter Type In Required Description
parent__name string path Yes The exact name of the device to partially update
data object body Yes Partial configuration data containing only the settings to modify

cURL Example:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device_name_setting/router-branch-office/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameter_id": 25,
    "value": "300"
  }'

Example Response:

{
  "id": 3001,
  "parent_id": "dev_11223",
  "parent__name": "router-branch-office",
  "parameter": {
    "id": 25,
    "name": "OSPF Hello Interval",
    "short_name": "ospf-hello",
    "variable_name": "ospf_hello_interval",
    "type": "positive",
    "position": 15,
    "required": false,
    "read_only": false,
    "metric": true,
    "group": {
      "id": 12,
      "name": "Routing Protocol Configuration",
      "service": null,
      "discovery_group": null,
      "title": "Dynamic Routing"
    }
  },
  "value": "300",
  "extra": false,
  "extra_value": null,
  "created": "2024-01-15T08:30:00Z",
  "last_change": "2024-01-22T17:20:45Z",
  "pending": true
}

Response Codes:

Status Description
200 Success - Specified settings updated successfully
400 Bad Request - Invalid parameter data or unsupported parameter type
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Device or specified parameter does not exist
422 Validation Error - Parameter value fails validation constraints

Common Use Cases

Use Case 1: Device Configuration Audit

Retrieve all settings for multiple devices to ensure compliance with organizational standards. Use the GET endpoint with specific parameter filters to check critical security and network configurations across your infrastructure.

Use Case 2: Bulk Network Configuration Update

When network policies change, use the PATCH endpoint to update specific parameters (like VLAN assignments or routing settings) across multiple devices without disrupting other configurations.

Use Case 3: Device Deployment Automation

During new device installations, use the PUT endpoint to apply complete, standardized configurations based on device role and location, ensuring consistent setup across your network infrastructure.

Use Case 4: Configuration Change Monitoring

Regularly poll devices using the GET endpoint with the pending=true filter to identify devices with pending configuration changes, enabling proactive change management and deployment tracking.

Use Case 5: Parameter-Specific Troubleshooting

When investigating network issues, use filtered GET requests to examine specific parameter types (like routing or interface settings) across affected devices to identify configuration discrepancies.

Best Practices

Inventory Device Name Variables

Endpoints Summary

Method Path Swagger
GET /inventory_device_name_variables/ Swagger ↗
PUT /inventory_device_name_variables/{parent__name}/ Swagger ↗

The Inventory Device Name Variables API enables management of device configuration variables in the Zequenze Control platform. These endpoints allow you to retrieve and update device-specific settings and parameters, making it easy to configure and monitor device variables across your inventory.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Name Variables API provides comprehensive access to device configuration settings within your inventory management system. These endpoints are essential for:

This API category works with device settings that have configurable variables, allowing you to maintain consistent configurations across your device inventory. The endpoints support both read and write operations, enabling complete lifecycle management of device variables from initial setup through ongoing maintenance.

Key concepts to understand:

Endpoints

GET /inventory_device_name_variables/

Description: Retrieves device configuration variables and settings based on specified filters. This endpoint is essential for querying current device configurations, checking parameter values, and monitoring pending changes across your inventory.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_variables/?parent__name=router-01&parameter__variable_name=hostname,ip_address&extra=true

Parameters:

Parameter Type In Required Description
parent__name string query Yes Filter settings by device name. Identifies which device's variables to retrieve
parameter__variable_name string query No Comma-separated list of variable names to retrieve (e.g., "hostname,ip_address,vlan_id")
parameter__name string query No Comma-separated list of human-readable parameter names to filter by
parameter__short_name string query No Comma-separated list of parameter short names for compact identification
limit integer query No Number of results per page (default pagination limit applies if not specified)
offset integer query No Starting index for pagination (use with limit for page navigation)
pending boolean query No When true, returns only variables with pending changes awaiting deployment
wildcard boolean query No Enable wildcard (*) matching in variable_name or parameter_name fields
force_update boolean query No Forces device settings refresh before returning data (may increase response time)
extra boolean query No Include additional metadata and context information for each parameter
dates boolean query No Include timestamp information showing when parameters were last modified

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_name_variables/?parent__name=switch-core-01&parameter__variable_name=management_ip,snmp_community&extra=true&dates=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1547,
      "name": "Management IP Address",
      "variable_name": "management_ip",
      "value": "192.168.1.100",
      "type": "ipv4_address",
      "short_name": "mgmt_ip",
      "extra": false,
      "extra_value": "Primary management interface",
      "pending": false
    },
    {
      "id": 1548,
      "name": "SNMP Community String",
      "variable_name": "snmp_community",
      "value": "public",
      "type": "string",
      "short_name": "snmp_comm",
      "extra": true,
      "extra_value": "Read-only community for monitoring",
      "pending": true
    },
    {
      "id": 1549,
      "name": "Device Location",
      "variable_name": "device_location",
      "value": "Data Center Rack 15",
      "type": "string",
      "short_name": "location",
      "extra": false,
      "extra_value": null,
      "pending": false
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns device variables matching the specified criteria
400 Bad Request - Invalid parameter values or missing required parent__name
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Specified device name does not exist

PUT /inventory_device_name_variables/{parent__name}/

Description: Updates device configuration variables for a specific device. This endpoint allows you to modify device settings in bulk, applying new values to one or more parameters simultaneously. Changes may be applied immediately or marked as pending depending on your system configuration.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_name_variables/router-branch-05/

Parameters:

Parameter Type In Required Description
parent__name string path Yes Name of the device whose variables will be updated
data string body Yes JSON payload containing the variable updates to apply

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_name_variables/switch-access-12/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "variable_name": "management_ip",
    "value": "192.168.1.125"
  }'

Example Request Body:

{
  "variable_name": "management_ip",
  "value": "192.168.1.125",
  "name": "Management IP Address"
}

Example Response:

{
  "id": 1892,
  "name": "Management IP Address",
  "variable_name": "management_ip",
  "value": "192.168.1.125",
  "type": "ipv4_address",
  "short_name": "mgmt_ip",
  "extra": false,
  "extra_value": "Primary management interface",
  "pending": true
}

Response Codes:

Status Description
200 Success - Variable updated successfully
400 Bad Request - Invalid data format or variable name
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Device or variable does not exist
422 Unprocessable Entity - Valid JSON but invalid parameter values

Common Use Cases

Use Case 1: Device Configuration Audit

Retrieve all configuration variables for devices requiring compliance verification. Use the GET endpoint with extra=true and dates=true to get complete configuration history and metadata for audit trails.

Use Case 2: Bulk IP Address Management

Query devices by IP-related variable names using wildcard matching (wildcard=true with parameter__variable_name=*ip*) to inventory all IP assignments across your network infrastructure.

Use Case 3: Pending Changes Review

Monitor configuration changes awaiting deployment by using pending=true parameter to identify devices with staged but not yet applied settings, ensuring proper change management workflows.

Use Case 4: Standardized Device Provisioning

Update multiple configuration parameters for new devices using the PUT endpoint to apply organization-specific settings like SNMP communities, NTP servers, and management credentials.

Use Case 5: Emergency Configuration Updates

Force real-time configuration refresh using force_update=true during network incidents to ensure you're working with the most current device state before making critical changes.

Best Practices

Inventory Device Operation

Endpoints Summary

Method Path Swagger
PUT /inventory_device_operation/{id}/ Swagger ↗

The Inventory Device Operation API enables you to perform remote operations on devices in your inventory, such as rebooting, factory resetting, or syncing device configurations. This endpoint is essential for device lifecycle management and troubleshooting network devices remotely.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Operation API provides a centralized way to execute administrative operations on network devices within your inventory. This API is particularly valuable for network administrators and IT teams who need to perform remote device management tasks without physical access to the hardware.

Key capabilities include:

This API follows an update-based pattern where you specify the operation to perform on a specific device by its ID. Operations are executed asynchronously, allowing you to trigger multiple device operations without blocking your application workflow.

Common scenarios include bulk device management during network maintenance windows, automated remediation of device issues, and streamlined device provisioning workflows.

Endpoints

PUT /inventory_device_operation/{id}/

Description: Executes a specific operation on an inventory device identified by its ID. This endpoint allows you to perform various administrative tasks remotely, including rebooting, factory resetting, syncing configurations, or reconfiguring devices. The operation is typically executed asynchronously, making it suitable for automation workflows.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_operation/12345/

Parameters:

Parameter Type In Required Description
id integer path Yes The unique identifier of the device in your inventory
data string body Yes JSON payload containing the operation to perform

Request Body Schema:

Field Type Required Description
operation string Yes The operation to perform. Valid values: reboot, factory, device_factory, sync, reconf

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_operation/12345/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "reboot"
  }'

Request Examples:

Reboot Device:

{
  "operation": "reboot"
}

Factory Reset:

{
  "operation": "factory"
}

Sync Configuration:

{
  "operation": "sync"
}

Example Response:

{
  "id": 12345,
  "operation": "reboot"
}

Operation Types:

Operation Code Description
Reboot reboot Restarts the device, useful for applying configuration changes or resolving connectivity issues
Factory Reset factory Resets device to factory defaults, removing all custom configurations
Device Factory Reset device_factory Performs a device-specific factory reset operation
Device Config Sync sync Synchronizes the device configuration with the central management system
Device Reconfigure reconf Applies new configuration settings to the device

Response Codes:

Status Description
200 Success - Operation has been initiated successfully
400 Bad Request - Invalid operation type or malformed request body
401 Unauthorized - Invalid or missing API token
404 Not Found - Device with specified ID does not exist
422 Unprocessable Entity - Device is not in a state that allows the requested operation

Common Use Cases

Use Case 1: Scheduled Maintenance Window

During planned maintenance, you might need to reboot multiple devices after applying configuration updates. Use the reboot operation to restart devices in sequence, ensuring each device properly applies new settings and reconnects to the network.

Use Case 2: Device Redeployment

When moving devices between locations or reassigning them to different network segments, use the factory operation to completely reset devices to their original state, then reconf to apply location-specific configurations.

Use Case 3: Configuration Drift Remediation

If monitoring systems detect configuration drift, use the sync operation to ensure devices match their intended configuration state as defined in your management system.

Use Case 4: Automated Troubleshooting

Integrate with monitoring tools to automatically trigger reboot operations when devices become unresponsive, providing a first-level automated remediation before escalating to manual intervention.

Use Case 5: Bulk Device Provisioning

For large deployments, use device_factory followed by reconf operations to prepare multiple devices with standardized configurations efficiently.

Best Practices

Inventory Device Serial

Endpoints Summary

Method Path Swagger
GET /inventory_device_serial/ Swagger ↗
POST /inventory_device_serial/ Swagger ↗
GET /inventory_device_serial/{serial_number}/ Swagger ↗
PUT /inventory_device_serial/{serial_number}/ Swagger ↗
PATCH /inventory_device_serial/{serial_number}/ Swagger ↗
DELETE /inventory_device_serial/{serial_number}/ Swagger ↗

The Inventory Device Serial API provides comprehensive device management capabilities, allowing you to perform CRUD operations on network devices using their serial numbers as identifiers. This API is essential for managing device inventory, monitoring device status, performing remote operations like reboots and factory resets, and maintaining device configurations across your organization's infrastructure.

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 API enables complete lifecycle management of network devices within the Zequenze Control platform. This API category is specifically designed for organizations that need to manage large inventories of network equipment, IoT devices, or CWMP/TR-069 compatible devices.

Key Capabilities:

Common Use Cases:

The API uses serial numbers as the primary identifier for individual device operations, making it ideal for scenarios where devices are tracked by their hardware serial numbers rather than internal database IDs.

Endpoints

GET /inventory_device_serial/

Description: Retrieves a paginated list of all inventory devices with comprehensive filtering options. This endpoint is essential for building device dashboards, generating reports, and implementing device discovery workflows.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial/?organization=123&status=true&limit=50&update_status=true

Parameters:

Parameter Type In Required Description
type integer query No Filter devices by device type/profile ID
status string query No Filter by device status. Use '0', 'false', 'False' for Down status or '1', 'true', 'True' for Up status
last_status_change_from string query No Filter by status change datetime in ISO format (e.g., 2024-01-01, 2024-01-01 00:01:00+00:00)
organization integer query No Filter devices by organization ID
limit integer query No Number of results to return per page (default pagination applies)
offset integer query No Starting index for pagination
pending boolean query No Include information about pending device settings
update_status boolean query No Trigger real-time status update from devices before returning data

cURL Example:

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

Example Response:

{
  "count": 156,
  "next": "https://control.zequenze.com/api/v1/inventory_device_serial/?limit=25&offset=25&organization=123&status=true",
  "previous": null,
  "results": [
    {
      "id": 1001,
      "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Office Router - Main Floor",
      "customer_id": "CUST-12345",
      "is_active": true,
      "status": "Up",
      "status_change": "2024-01-15T08:30:00Z",
      "type": 5,
      "type_short_name": "enterprise_router",
      "software_version": "1.2.3",
      "hardware_version": "v2.1",
      "manufacturer": "Zequenze Networks",
      "serial_number": "ZN123456789",
      "serial_number_alt": "ALT-789",
      "description": "Primary internet gateway for main office",
      "organization_id": 123,
      "location_name": "Headquarters - Building A",
      "location": 45,
      "location_short_name": "HQ_BLDG_A",
      "latitude": "37.7749",
      "longitude": "-122.4194",
      "address": "192.168.1.1",
      "last_connection": "2024-01-15T14:25:30Z",
      "last_configuration": "2024-01-15T09:15:00Z",
      "created": "2024-01-10T10:00:00Z",
      "pending_settings": "firmware_upgrade,location_update"
    }
  ]
}

Response Codes:

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

POST /inventory_device_serial/

Description: Creates a new device in the inventory system. This endpoint is used for device registration, either during initial deployment or when adding discovered devices to your management platform.

Use Cases:

Full URL Example:

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

cURL Example:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_serial/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Branch Office Router",
    "serial_number": "ZN987654321",
    "customer_id": "CUST-67890",
    "type": 5,
    "organization_id": 123,
    "location_name": "Branch Office - Seattle",
    "description": "Primary router for Seattle branch",
    "username": "device_admin",
    "password": "secure_password_123",
    "is_active": true
  }'

Example Request Body:

{
  "name": "Branch Office Router",
  "serial_number": "ZN987654321",
  "customer_id": "CUST-67890",
  "type": 5,
  "organization_id": 123,
  "location_name": "Branch Office - Seattle",
  "description": "Primary router for Seattle branch",
  "username": "device_admin",
  "password": "secure_password_123",
  "is_active": true,
  "latitude": "47.6062",
  "longitude": "-122.3321"
}

Example Response:

{
  "id": 1002,
  "uuid": "a1b2c3d4-e5f6-4789-a012-3456789abcdef",
  "name": "Branch Office Router",
  "serial_number": "ZN987654321",
  "customer_id": "CUST-67890",
  "is_active": true,
  "status": "Down",
  "type": 5,
  "type_short_name": "enterprise_router",
  "organization_id": 123,
  "location_name": "Branch Office - Seattle",
  "description": "Primary router for Seattle branch",
  "username": "device_admin",
  "latitude": "47.6062",
  "longitude": "-122.3321",
  "created": "2024-01-15T15:30:00Z",
  "pending_settings": null
}

Response Codes:

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

GET /inventory_device_serial/{serial_number}/

Description: Retrieves detailed information for a specific device using its serial number. This endpoint provides complete device details including current status, configuration state, and operational metrics.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial/ZN123456789/?update_status=true&pending=true

Parameters:

Parameter Type In Required Description
serial_number string path Yes Device serial number (URL path parameter)
pending boolean query No Include detailed information about pending device settings
update_status boolean query No Force real-time status check before returning device information

cURL Example:

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

Example Response:

{
  "id": 1001,
  "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "Office Router - Main Floor",
  "customer_id": "CUST-12345",
  "is_active": true,
  "status": "Up",
  "status_change": "2024-01-15T08:30:00Z",
  "type": 5,
  "type_short_name": "enterprise_router",
  "software_version": "1.2.3",
  "hardware_version": "v2.1",
  "manufacturer": "Zequenze Networks",
  "unique_identifier": "ZN:ROUTER:12345",
  "product_class": "InternetGatewayDevice",
  "serial_number": "ZN123456789",
  "serial_number_alt": "ALT-789",
  "description": "Primary internet gateway for main office",
  "organization_id": 123,
  "firmware_image": 15,
  "firmware_image_is_pending": false,
  "location_name": "Headquarters - Building A",
  "location": 45,
  "location_short_name": "HQ_BLDG_A",
  "latitude": "37.7749",
  "longitude": "-122.4194",
  "username": "admin_user",
  "update_frequency": 300,
  "address": "192.168.1.1",
  "last_connection": "2024-01-15T14:25:30Z",
  "last_configuration": "2024-01-15T09:15:00Z",
  "last_change": "2024-01-15T13:45:00Z",
  "created": "2024-01-10T10:00:00Z",
  "debug": false,
  "pending_settings": "location_update"
}

Response Codes:

Status Description
200 Success - Returns complete device information
401 Unauthorized - Invalid or missing API token
404 Not Found - Device with specified serial number does not exist

PUT /inventory_device_serial/{serial_number}/

Description: Completely updates a device's configuration by replacing all updatable fields. This endpoint performs a full update operation, requiring all fields to be specified in the request body.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial/ZN123456789/

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_serial/ZN123456789/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Office Router - Main Floor",
    "customer_id": "CUST-12345",
    "is_active": true,
    "type": 5,
    "description": "Updated description - Primary internet gateway",
    "organization_id": 123,
    "location_name": "Headquarters - Building A - Floor 2",
    "latitude": "37.7749",
    "longitude": "-122.4194",
    "username": "admin_user",
    "password": "new_secure_password",
    "update_frequency": 600
  }'

Response Codes:

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

PATCH /inventory_device_serial/{serial_number}/

Description: Partially updates specific device fields without affecting other properties. This endpoint is ideal for targeted updates like changing device status, location, or performing remote operations.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial/ZN123456789/

cURL Example (Location Update):

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device_serial/ZN123456789/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "location_name": "Headquarters - Building B",
    "latitude": "37.7750",
    "longitude": "-122.4195"
  }'

cURL Example (Remote Reboot):

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device_serial/ZN123456789/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reboot": true
  }'

cURL Example (Configuration Sync):

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device_serial/ZN123456789/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sync": true,
    "debug": true
  }'

Response Codes:

Status Description
200 Success - Device partially updated
400 Bad Request - Invalid field values or unsupported operation
401 Unauthorized - Invalid or missing API token
404 Not Found - Device with specified serial number does not exist

DELETE /inventory_device_serial/{serial_number}/

Description: Permanently removes a device from the inventory system. This operation cannot be undone and will delete all associated configuration data, history, and settings for the specified device.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial/ZN123456789/

cURL Example:

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

Response Codes:

Status Description
204 No Content - Device successfully deleted
401 Unauthorized - Invalid or missing API token
404 Not Found - Device with specified serial number does not exist
409 Conflict - Device cannot be deleted due to dependencies

Common Use Cases

Use Case 1: Device Health Monitoring Dashboard

Build a real-time dashboard showing device status across your organization by using the GET list endpoint with status filtering and automatic status updates.

# Get all active devices with current status
https://control.zequenze.com/api/v1/inventory_device_serial/?is_active=true&update_status=true&limit=100

Use Case 2: Remote Device Troubleshooting

When troubleshooting connectivity issues, retrieve device details, perform a configuration sync, and optionally reboot the device.

# 1. Get device details
GET /inventory_device_serial/ZN123456789/?update_status=true

# 2. Sync configuration
PATCH /inventory_device_serial/ZN123456789/ {"sync": true}

# 3. Reboot if necessary
PATCH /inventory_device_serial/ZN123456789/ {"reboot": true}

Use Case 3: Bulk Device Deployment

During large deployments, use POST to register devices and PATCH to configure them in batches.

Use Case 4: Organization Migration

Transfer devices between organizations by updating the organization_id field and related location information.

Use Case 5: Firmware Update Campaign

Identify devices needing updates, set firmware images, and monitor the upgrade process using the firmware_image and firmware_image_is_pending fields.

Best Practices

Pagination Management:

Status Updates:

Error Handling:

Security Considerations:

Remote Operations:

Inventory Device Serial Diags

Endpoints Summary

Method Path Swagger
POST /inventory_device_serial_diags/ Swagger ↗
GET /inventory_device_serial_diags/ Swagger ↗

The Inventory Device Serial Diagnostics API enables remote execution of network diagnostic operations on specific devices using their serial numbers. These endpoints allow you to schedule diagnostic tests like ping, traceroute, speed tests, and WiFi neighbor scans, then retrieve results to troubleshoot connectivity issues and monitor network 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 provides powerful remote diagnostic capabilities for network devices in your inventory. This API enables technicians and network administrators to remotely execute various diagnostic operations on Customer Premises Equipment (CPE) and other managed devices without requiring physical access.

Key capabilities include:

How it works:

  1. Schedule diagnostic operations using the POST endpoint with specific test parameters
  2. The system queues the diagnostic request for the target device
  3. Retrieve diagnostic results and status using the GET endpoint
  4. Operations are executed asynchronously when the device connects to the management system

This API is essential for remote troubleshooting, proactive network monitoring, and validating service quality without dispatching field technicians.

Endpoints

POST /inventory_device_serial_diags/

Description: Schedules a new network diagnostic operation on a device identified by its serial number. This endpoint queues diagnostic tests that will be executed when the target device next communicates with the management platform. Use this to initiate remote troubleshooting or performance testing.

Use Cases:

Full URL Example:

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

Request Body Parameters:

Parameter Type Required Description
serial_number string Yes Serial number of the target device to diagnose
operation string Yes Type of diagnostic test. Options: download, upload, ipping, udpecho, traceroute, dnslookup, wifi.neighbor
target string Yes Test target - URL for speed tests, IP address for ping/traceroute, hostname for DNS lookup, or parameter for WiFi scans
upload_size string No File size in MB for upload tests (e.g., "10", "100")
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/DNS operations (default: 1)
max_hops integer No Maximum hops for traceroute operations (default: 30)
interface string No Specific network interface to use for the diagnostic operation

cURL Example - Speed Test:

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 '{
    "serial_number": "SN123456789",
    "operation": "download",
    "target": "http://speedtest.example.com/1GB.bin"
  }'

cURL Example - Connectivity Test:

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 '{
    "serial_number": "SN123456789",
    "operation": "ipping",
    "target": "8.8.8.8",
    "count": 10,
    "size": 64,
    "timeout": 2
  }'

Example Response:

{
  "serial_number": "SN123456789",
  "operation": "download",
  "target": "http://speedtest.example.com/1GB.bin",
  "upload_size": null,
  "count": null,
  "size": null,
  "timeout": null,
  "max_hops": null,
  "interface": null,
  "id": "diag_12345",
  "status": "scheduled",
  "created_at": "2024-01-15T10:30:00Z"
}

Response Codes:

Status Description
201 Created - Diagnostic operation successfully scheduled
400 Bad Request - Invalid parameters or operation type
401 Unauthorized - Invalid or missing API token
404 Not Found - Device with specified serial number not found

GET /inventory_device_serial_diags/

Description: Retrieves diagnostic operation results and status information. Use this endpoint to check the progress and results of previously scheduled diagnostic tests. You can query for specific operations or list all diagnostics for monitoring purposes.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_diags/?id=diag_12345&update_status=true

Parameters:

Parameter Type In Required Description
id string query No Specific diagnostic operation ID to retrieve results for
update_status boolean query No Whether to refresh device status before returning results (default: false)

cURL Example - Get Specific Diagnostic:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_serial_diags/?id=diag_12345" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

cURL Example - List All Diagnostics:

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

Example Response - Speed Test Results:

[
  {
    "id": "diag_12345",
    "serial_number": "SN123456789",
    "operation": "download",
    "target": "http://speedtest.example.com/1GB.bin",
    "status": "completed",
    "created_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T10:32:15Z",
    "results": {
      "download_speed_mbps": 95.4,
      "bytes_downloaded": 1073741824,
      "duration_seconds": 89.2,
      "success": true
    }
  },
  {
    "id": "diag_12346",
    "serial_number": "SN987654321",
    "operation": "ipping",
    "target": "8.8.8.8",
    "count": 5,
    "size": 64,
    "timeout": 1,
    "status": "completed",
    "created_at": "2024-01-15T11:15:00Z",
    "completed_at": "2024-01-15T11:15:08Z",
    "results": {
      "packets_sent": 5,
      "packets_received": 5,
      "packet_loss_percent": 0,
      "min_rtt_ms": 12.4,
      "max_rtt_ms": 15.8,
      "avg_rtt_ms": 14.1,
      "success": true
    }
  }
]

Example Response - WiFi Neighbor Scan:

[
  {
    "id": "diag_12347",
    "serial_number": "SN555666777",
    "operation": "wifi.neighbor",
    "target": "2.4GHz",
    "status": "completed",
    "created_at": "2024-01-15T12:00:00Z",
    "completed_at": "2024-01-15T12:00:45Z",
    "results": {
      "networks_found": 12,
      "strongest_signal_dbm": -35,
      "channel_utilization": {
        "1": 25,
        "6": 60,
        "11": 45
      },
      "recommended_channel": 1,
      "success": true
    }
  }
]

Response Codes:

Status Description
200 Success - Returns diagnostic operation data
401 Unauthorized - Invalid or missing API token
404 Not Found - Specified diagnostic ID not found
500 Internal Server Error - System error processing request

Common Use Cases

Use Case 1: Customer Speed Complaint Troubleshooting

When customers report slow internet speeds, schedule download and upload tests to measure actual throughput, then compare results against service level agreements to identify if the issue is network-related or device-specific.

Use Case 2: Device Connectivity Verification

For devices that appear offline or unreachable, execute ping tests to multiple targets (gateway, DNS servers, public IPs) to isolate whether the issue is local network connectivity, ISP routing, or device configuration.

Use Case 3: WiFi Performance Optimization

Before deploying new wireless equipment or when customers report WiFi issues, scan neighboring networks to identify channel congestion and interference sources, then recommend optimal channel configurations.

Use Case 4: Proactive Network Monitoring

Schedule regular diagnostic tests across your device fleet to establish baseline performance metrics and identify degrading connections before customers experience service issues.

Use Case 5: DNS Resolution Troubleshooting

When customers experience web browsing issues, test DNS lookup performance against multiple DNS servers to identify resolution failures or slow response times that could impact user experience.

Best Practices

Inventory Device Serial Headless Operation

Endpoints Summary

Method Path Swagger
GET /inventory_device_serial_headless_operation/ Swagger ↗
POST /inventory_device_serial_headless_operation/ Swagger ↗

The Inventory Device Serial Headless Operation endpoints allow you to schedule and manage automated device operations on network devices using their serial numbers. These endpoints enable you to perform TR-069/CWMP operations like getting device parameters, setting configuration values, and managing objects without manual intervention.

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 Headless Operation API provides a powerful way to manage network devices programmatically through scheduled operations. This API category is specifically designed for automating device management tasks on TR-069/CWMP compatible devices using their serial numbers as identifiers.

Key Capabilities:

Common Use Cases:

The operations are executed asynchronously, allowing you to schedule tasks that will be performed when devices next communicate with the management server. The optional update_status parameter enables real-time status updates before returning operation results.

Endpoints

GET /inventory_device_serial_headless_operation/

Description: Retrieves a list of scheduled headless operations for devices. This endpoint allows you to view pending, completed, or filtered operations based on transaction ID. Use this to monitor the status of your scheduled device operations and retrieve results.

Use Cases:

Full URL Example:

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

Parameters:

Parameter Type In Required Description
id string query No ID of the scheduled transaction to filter results
update_status boolean query No Use configured helpers to update device status before returning the information

cURL Example:

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

Example Response:

[
  {
    "serial_number": "DV001234567890",
    "operation": "get",
    "variables": [
      {
        "variable_name": "Device.ManagementServer.PeriodicInformInterval",
        "value": "300",
        "status": "completed"
      },
      {
        "variable_name": "Device.WiFi.SSID.1.Stats.BytesReceived",
        "value": "1048576000",
        "status": "completed"
      }
    ]
  },
  {
    "serial_number": "DV001234567891",
    "operation": "set",
    "variables": [
      {
        "variable_name": "Device.ManagementServer.PeriodicInformInterval",
        "value": "60",
        "value_type": "integer",
        "status": "pending"
      }
    ]
  }
]

Response Codes:

Status Description
200 Success - Returns the list of scheduled operations
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient permissions
500 Internal Server Error - Server processing error

POST /inventory_device_serial_headless_operation/

Description: Creates a new scheduled headless operation for one or more devices. This endpoint allows you to queue device operations that will be executed when the target devices next communicate with the management server. Support for get, set, add object, and delete object operations.

Use Cases:

Full URL Example:

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

Parameters:

Parameter Type In Required Description
data object body Yes JSON object containing the operation details

Request Body Schema:

{
  "serial_number": "string",
  "operation": "get|set|add.obj|del.obj",
  "variables": [
    {
      "variable_name": "string",
      "value": "string",
      "value_type": "string|integer|boolean"
    }
  ]
}

cURL Example - Get Operation:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_serial_headless_operation/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serial_number": "DV001234567890",
    "operation": "get",
    "variables": [
      {"variable_name": "Device.ManagementServer.PeriodicInformInterval"},
      {"variable_name": "Device.WiFi.SSID.1.Stats.BytesReceived"}
    ]
  }'

cURL Example - Set Operation:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_serial_headless_operation/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serial_number": "DV001234567890",
    "operation": "set",
    "variables": [
      {
        "variable_name": "Device.ManagementServer.PeriodicInformInterval",
        "value": "60",
        "value_type": "integer"
      },
      {
        "variable_name": "Device.ManagementServer.PeriodicInformEnable",
        "value": "1",
        "value_type": "boolean"
      }
    ]
  }'

Example Response:

{
  "id": "txn_789012345",
  "serial_number": "DV001234567890",
  "operation": "set",
  "variables": [
    {
      "variable_name": "Device.ManagementServer.PeriodicInformInterval",
      "value": "60",
      "value_type": "integer"
    },
    {
      "variable_name": "Device.ManagementServer.PeriodicInformEnable",
      "value": "1",
      "value_type": "boolean"
    }
  ],
  "status": "scheduled",
  "created_at": "2024-01-15T10:30:00Z"
}

Response Codes:

Status Description
201 Created - Operation successfully scheduled
400 Bad Request - Invalid operation parameters or malformed request
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient permissions
404 Not Found - Device with specified serial number not found
422 Unprocessable Entity - Valid JSON but invalid operation data

Common Use Cases

Use Case 1: Bulk Device Configuration Monitoring

Schedule periodic retrieval of key configuration parameters across multiple devices to ensure compliance with corporate policies. Use GET operations to collect parameters like periodic inform intervals, WiFi settings, and security configurations.

Use Case 2: Automated Device Onboarding

When new devices are deployed, use SET operations to automatically configure management server settings, WiFi credentials, and other essential parameters without requiring manual intervention.

Use Case 3: WiFi Network Management

Use ADD.OBJ operations to deploy new WiFi SSIDs across all access points, or DEL.OBJ operations to remove obsolete network configurations during network updates.

Use Case 4: Performance Monitoring and Analytics

Schedule GET operations to collect device statistics like bytes transmitted/received, connection counts, and performance metrics for analysis and reporting.

Use Case 5: Security Configuration Updates

Use SET operations to update security parameters, change default passwords, or modify firewall settings across multiple devices simultaneously.

Best Practices

Inventory Device Serial Ipping

Endpoints Summary

Method Path Swagger
GET /inventory_device_serial_ipping/{serial_number}/ Swagger ↗

The Inventory Device Serial Mapping API provides endpoints for retrieving device information by serial number. This endpoint is essential for device identification, inventory tracking, and asset management workflows where you need to quickly lookup device details using only the serial number.

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 Mapping API category contains endpoints specifically designed for device lookup and identification operations. This API is particularly useful when you have a device's serial number and need to retrieve its corresponding system information or verify its existence in your inventory.

Common scenarios include:

This endpoint serves as a bridge between physical devices (identified by serial numbers) and your digital inventory management system, enabling efficient device tracking and management workflows.

Endpoints

GET /inventory_device_serial_ipping/{serial_number}/

Description: Retrieves device information by serial number. This endpoint allows you to look up a specific device in your inventory using its serial number as the identifier. It returns the internal system ID and other relevant device details associated with that serial number.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_ipping/ABC123456789/

Path Parameters:

Parameter Type In Required Description
serial_number string path Yes The serial number of the device to lookup. Should be URL-encoded if it contains special characters

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_serial_ipping/ABC123456789/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "id": 12345
}

Response Codes:

Status Description
200 Success - Returns the device information for the specified serial number
401 Unauthorized - Invalid or missing API token
404 Not Found - No device found with the specified serial number
400 Bad Request - Invalid serial number format

Common Use Cases

Use Case 1: Device Audit Verification

During physical inventory audits, use this endpoint to verify that devices found on-site are properly registered in your system. Scan or manually enter serial numbers to confirm each device's presence in your inventory database.

Use Case 2: Customer Support Lookup

When customers contact support and provide a device serial number, use this endpoint to quickly retrieve the internal device ID, which can then be used with other inventory endpoints to get complete device details, warranty information, or service history.

Use Case 3: Asset Integration

When integrating with external asset management systems or importing device data, use this endpoint to check if devices already exist in your inventory before creating duplicates, helping maintain data integrity.

Use Case 4: Device Registration Validation

Before registering new devices, verify that their serial numbers aren't already in use in your system, preventing duplicate entries and ensuring accurate inventory tracking.

Best Practices

Inventory Device Serial Operation

Endpoints Summary

Method Path Swagger
PUT /inventory_device_serial_operation/{serial_number}/ Swagger ↗

The inventory device serial operation endpoint allows you to perform remote management operations on specific devices in your inventory using their serial numbers. This API enables critical device management tasks like rebooting, factory resets, configuration syncing, and device reconfiguration through a simple REST interface.

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 operation API provides a powerful interface for remote device management within your organization's inventory system. This endpoint allows administrators and automated systems to execute critical operations on devices without requiring physical access or manual intervention.

The primary purpose of this API is to enable centralized device lifecycle management, allowing you to:

This endpoint is particularly valuable in scenarios where devices are deployed in remote locations, managed at scale, or when quick remediation is needed to maintain operational continuity. The serial number-based approach ensures precise targeting of specific devices, preventing accidental operations on unintended equipment.

Endpoints

PUT /inventory_device_serial_operation/{serial_number}/

Description: Executes a management operation on a specific device identified by its serial number. This endpoint allows you to remotely control device behavior, perform maintenance operations, and manage device configurations without requiring physical access to the hardware.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_operation/ABC123456789/

Parameters:

Parameter Type In Required Description
serial_number string path Yes The unique serial number of the device to perform the operation on
operation string body Yes The specific operation to execute. Valid operations include: 'reboot' (restart device), 'factory' (complete factory reset), 'device_factory' (device-specific factory reset), 'sync' (synchronize configuration), 'reconf' (reconfigure device settings)

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_serial_operation/ABC123456789/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "reboot"
  }'

Example Request Body:

{
  "operation": "reboot"
}

Example Response:

{
  "id": 12345,
  "operation": "reboot"
}

Response Codes:

Status Description
200 Success - Operation has been initiated successfully
400 Bad Request - Invalid operation type or malformed request
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Device with specified serial number not found
422 Unprocessable Entity - Device exists but cannot perform requested operation

Operation Types Reference

Operation Code Operation Name Description
reboot Device Reboot Performs a graceful restart of the device, maintaining current configuration
factory Factory Reset Complete factory reset, removing all custom configurations and returning to default state
device_factory Device Factory Reset Device-specific factory reset that may preserve certain manufacturer settings
sync Configuration Sync Synchronizes device configuration with centralized management system
reconf Device Reconfigure Applies new configuration settings to the device

Common Use Cases

Use Case 1: Remote Device Troubleshooting

When devices become unresponsive or exhibit connectivity issues, use the reboot operation to restart the device remotely. This is often the first step in troubleshooting before escalating to more intensive operations.

Use Case 2: Device Repurposing and Deployment

Before deploying devices to new locations or users, perform a factory reset to ensure clean configuration state, followed by sync operations to apply appropriate settings for the new deployment environment.

Use Case 3: Fleet Configuration Management

Use the sync and reconf operations to maintain configuration consistency across device fleets, ensuring all devices comply with organizational security policies and operational requirements.

Use Case 4: Automated Maintenance Workflows

Integrate these operations into automated maintenance schedules, performing regular configuration syncs or implementing automated recovery procedures when device monitoring systems detect issues.

Use Case 5: Emergency Response and Recovery

In case of security incidents or widespread configuration issues, use factory reset operations to quickly return devices to known-good states, followed by reconfiguration to restore proper operational settings.

Best Practices

Inventory Device Serial Setting

Endpoints Summary

Method Path Swagger
GET /inventory_device_serial_setting/ Swagger ↗
PUT /inventory_device_serial_setting/{parent__serial_number}/ Swagger ↗
PATCH /inventory_device_serial_setting/{parent__serial_number}/ Swagger ↗

The Inventory Device Serial Setting endpoints provide comprehensive management of device configuration parameters and settings. These endpoints allow you to retrieve, update, and modify device-specific settings using the device's serial number as the primary identifier, making it easy to manage configuration parameters across your device inventory.

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 Setting API category enables you to manage configuration parameters and settings for devices in your inventory using their serial numbers. This API is essential for device configuration management, allowing you to:

These endpoints are particularly useful for network management systems, IoT device management platforms, and any application that needs to configure and monitor device parameters at scale. The API supports various parameter types including strings, integers, booleans, and complex data types, with built-in support for read-only parameters, metrics tracking, and parameter grouping.

The serial number-based approach ensures precise device targeting, while the flexible filtering system allows for efficient parameter management across large device inventories.

Endpoints

GET /inventory_device_serial_setting/

Description: Retrieves a paginated list of device settings and configuration parameters for a specific device identified by its serial number. This endpoint is essential for viewing current device configurations, monitoring parameter values, and identifying pending setting changes.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_setting/?parent__serial_number=SN123456789&limit=50&pending=true

Parameters:

Parameter Type In Required Description
parent__serial_number string query Yes The serial number of the parent device whose settings you want to retrieve
parameter_id string query No Filter results by specific parameter ID
parameter__variable_name string query No Filter settings by the parameter's variable name field
parameter__name string query No Filter settings by the parameter's display name field
parameter__short_name string query No Filter settings by the parameter's short name field
limit integer query No Number of results to return per page (default varies by server configuration)
offset integer query No The initial index from which to return results for pagination
pending boolean query No When true, only returns settings that have pending changes waiting to be applied

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_serial_setting/?parent__serial_number=SN123456789&parameter__name=wifi_password&limit=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 25,
  "next": "https://control.zequenze.com/api/v1/inventory_device_serial_setting/?limit=10&offset=10&parent__serial_number=SN123456789",
  "previous": null,
  "results": [
    {
      "id": 1001,
      "parent_id": "SN123456789",
      "parent__name": "Router_Building_A",
      "parameter": {
        "id": 45,
        "name": "WiFi Password",
        "short_name": "wifi-pass",
        "variable_name": "wifi_password",
        "type": "password",
        "position": 10,
        "required": true,
        "read_only": false,
        "metric": false,
        "group": {
          "id": 5,
          "name": "Wireless Configuration",
          "service": "WiFi Management",
          "discovery_group": "network",
          "title": "WiFi Settings"
        }
      },
      "value": "SecurePassword123!",
      "extra": false,
      "extra_value": null,
      "created": "2024-01-15T10:30:00Z",
      "last_change": "2024-01-20T14:45:30Z",
      "pending": false
    },
    {
      "id": 1002,
      "parent_id": "SN123456789",
      "parent__name": "Router_Building_A",
      "parameter": {
        "id": 46,
        "name": "Firmware Version",
        "short_name": "fw-ver",
        "variable_name": "firmware_version",
        "type": "readonly",
        "position": 1,
        "required": false,
        "read_only": true,
        "metric": true,
        "group": {
          "id": 1,
          "name": "System Information",
          "service": "System Management",
          "discovery_group": "system",
          "title": "Device Info"
        }
      },
      "value": "v2.4.1",
      "extra": false,
      "extra_value": null,
      "created": "2024-01-15T10:30:00Z",
      "last_change": "2024-01-18T09:15:22Z",
      "pending": true
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns the paginated list of device settings
400 Bad Request - Missing required parent__serial_number parameter
401 Unauthorized - Invalid or missing API token
404 Not Found - Device with specified serial number does not exist

PUT /inventory_device_serial_setting/{parent__serial_number}/

Description: Performs a complete update of device settings for the specified device serial number. This endpoint replaces all existing settings with the provided data, making it suitable for bulk configuration updates or complete device reconfiguration scenarios.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_setting/SN123456789/

Parameters:

Parameter Type In Required Description
parent__serial_number string path Yes The serial number of the device whose settings will be updated
data string body Yes JSON payload containing the complete device settings configuration

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_serial_setting/SN123456789/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameter": {
      "id": 45,
      "name": "WiFi Password",
      "variable_name": "wifi_password",
      "type": "password",
      "required": true,
      "read_only": false,
      "group": {
        "name": "Wireless Configuration"
      }
    },
    "value": "NewSecurePassword456!"
  }'

Example Response:

{
  "id": 1001,
  "parent_id": "SN123456789",
  "parent__name": "Router_Building_A",
  "parameter": {
    "id": 45,
    "name": "WiFi Password",
    "short_name": "wifi-pass",
    "variable_name": "wifi_password",
    "type": "password",
    "position": 10,
    "required": true,
    "read_only": false,
    "metric": false,
    "group": {
      "id": 5,
      "name": "Wireless Configuration",
      "service": "WiFi Management",
      "discovery_group": "network",
      "title": "WiFi Settings"
    }
  },
  "value": "NewSecurePassword456!",
  "extra": false,
  "extra_value": null,
  "created": "2024-01-15T10:30:00Z",
  "last_change": "2024-01-22T16:20:15Z",
  "pending": true
}

Response Codes:

Status Description
200 Success - Device settings updated successfully
400 Bad Request - Invalid request data or missing required fields
401 Unauthorized - Invalid or missing API token
404 Not Found - Device with specified serial number does not exist
422 Unprocessable Entity - Validation errors in the request data

PATCH /inventory_device_serial_setting/{parent__serial_number}/

Description: Performs a partial update of device settings for the specified device serial number. Unlike PUT, this endpoint only modifies the specific fields provided in the request, leaving other settings unchanged. This is ideal for targeted configuration changes and incremental updates.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_setting/SN123456789/

Parameters:

Parameter Type In Required Description
parent__serial_number string path Yes The serial number of the device whose settings will be partially updated
data string body Yes JSON payload containing only the fields to be updated

cURL Example:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device_serial_setting/SN123456789/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "UpdatedValue123"
  }'

Example Response:

{
  "id": 1001,
  "parent_id": "SN123456789",
  "parent__name": "Router_Building_A",
  "parameter": {
    "id": 45,
    "name": "WiFi Password",
    "short_name": "wifi-pass",
    "variable_name": "wifi_password",
    "type": "password",
    "position": 10,
    "required": true,
    "read_only": false,
    "metric": false,
    "group": {
      "id": 5,
      "name": "Wireless Configuration",
      "service": "WiFi Management",
      "discovery_group": "network",
      "title": "WiFi Settings"
    }
  },
  "value": "UpdatedValue123",
  "extra": false,
  "extra_value": null,
  "created": "2024-01-15T10:30:00Z",
  "last_change": "2024-01-22T17:45:08Z",
  "pending": true
}

Response Codes:

Status Description
200 Success - Device settings partially updated successfully
400 Bad Request - Invalid request data
401 Unauthorized - Invalid or missing API token
404 Not Found - Device with specified serial number does not exist
422 Unprocessable Entity - Validation errors in the request data

Common Use Cases

Use Case 1: Device Configuration Audit

Retrieve all settings for multiple devices to verify compliance with security policies and configuration standards. Use the GET endpoint with different serial numbers and filter by parameter groups to audit specific configuration categories.

Use Case 2: Bulk WiFi Password Update

When updating WiFi credentials across a fleet of devices, use the PATCH endpoint to modify only the WiFi password parameter without affecting other network settings, minimizing the risk of configuration conflicts.

Use Case 3: Firmware Update Monitoring

Track firmware versions across devices using the GET endpoint with metric-enabled parameters. Filter by read-only parameters to monitor system information and identify devices that need updates.

Use Case 4: Factory Reset Recovery

After a factory reset, use the PUT endpoint to restore a complete device configuration from a previously saved backup, ensuring consistent device setup across your network.

Use Case 5: Pending Changes Management

Monitor configuration changes waiting to be applied by using the GET endpoint with the pending=true parameter. This helps track which devices have configuration updates queued for deployment.

Best Practices

Inventory Device Serial Variables

Endpoints Summary

Method Path Swagger
GET /inventory_device_serial_variables/ Swagger ↗
PUT /inventory_device_serial_variables/{parent__serial_number}/ Swagger ↗

The Inventory Device Serial Variables API provides endpoints for managing and retrieving device-specific configuration parameters and variables. These endpoints allow you to query device settings by serial number and update device configurations, making them essential for device management and configuration automation.

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 Variables API enables you to manage configuration parameters and variables for specific devices in your inventory. This API category is designed for device configuration management, allowing you to:

These endpoints work together to provide a complete device configuration management solution. The GET endpoint allows you to query current device settings and their status, while the PUT endpoint enables you to update configurations. The API supports advanced filtering capabilities including wildcard matching and parameter-specific queries.

Key concepts to understand:

Endpoints

GET /inventory_device_serial_variables/

Description: Retrieves configuration variables and parameters for devices based on their serial numbers. This endpoint is essential for querying current device configurations, monitoring parameter values, and checking for pending updates. It supports comprehensive filtering to help you retrieve exactly the data you need.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_variables/?parent__serial_number=ABC123456&parameter__variable_name=network_config,security_settings&extra=true

Parameters:

Parameter Type In Required Description
parent__serial_number string query Yes Filter settings by the parent device's serial number
parameter__variable_name string query No Comma-separated list of parameter variable names to retrieve
parameter__name string query No Comma-separated list of parameter names to retrieve
parameter__short_name string query No Comma-separated list of parameter short-names to retrieve
limit integer query No Number of results to return per page (for pagination)
offset integer query No The initial index from which to return results (for pagination)
pending boolean query No Filter to show only devices with pending settings when true
wildcard boolean query No Enable wildcard ('*') character matching in variable name or parameter name fields
extra boolean query No Include additional/extra information about parameters in the response

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_serial_variables/?parent__serial_number=DEV001&parameter__variable_name=network_config&extra=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1001,
      "name": "Network Configuration",
      "variable_name": "network_config",
      "value": "192.168.1.100",
      "type": "ip_address",
      "short_name": "net_cfg",
      "extra": true,
      "extra_value": "Primary network interface configuration",
      "pending": false
    },
    {
      "id": 1002,
      "name": "Device Timeout",
      "variable_name": "timeout_seconds",
      "value": "300",
      "type": "integer",
      "short_name": "timeout",
      "extra": false,
      "extra_value": null,
      "pending": true
    },
    {
      "id": 1003,
      "name": "Security Mode",
      "variable_name": "security_mode",
      "value": "enabled",
      "type": "boolean",
      "short_name": "sec_mode",
      "extra": true,
      "extra_value": "Enhanced security protocol active",
      "pending": false
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns the requested device variables
400 Bad Request - Missing required parent__serial_number parameter
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Device with specified serial number does not exist

PUT /inventory_device_serial_variables/{parent__serial_number}/

Description: Updates configuration variables for a specific device identified by its serial number. This endpoint allows you to modify device settings and parameters, enabling remote device configuration management. The changes may be applied immediately or queued as pending depending on the device status.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_serial_variables/DEV001/

Parameters:

Parameter Type In Required Description
parent__serial_number string path Yes Serial number of the device to update (included in URL path)
data string body Yes JSON string containing the variable updates to apply

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_serial_variables/DEV001/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "variable_name": "network_config",
    "value": "192.168.1.150",
    "name": "Network Configuration"
  }'

Example Request Body:

{
  "variable_name": "timeout_seconds",
  "value": "600",
  "name": "Device Timeout"
}

Example Response:

{
  "id": 1002,
  "name": "Device Timeout",
  "variable_name": "timeout_seconds",
  "value": "600",
  "type": "integer",
  "short_name": "timeout",
  "extra": false,
  "extra_value": null,
  "pending": true
}

Response Codes:

Status Description
200 Success - Variable updated successfully
400 Bad Request - Invalid data format or missing required fields
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Device with specified serial number does not exist
422 Unprocessable Entity - Data validation failed

Common Use Cases

Use Case 1: Device Configuration Audit

Query all configuration parameters for a specific device to perform a compliance audit or troubleshooting session. Use the GET endpoint with the device serial number and enable extra information to get comprehensive details about each parameter.

Use Case 2: Bulk Parameter Filtering

Retrieve specific configuration variables across devices using parameter filtering. This is useful when you need to check particular settings like network configurations or security parameters across your device inventory.

Use Case 3: Pending Changes Monitoring

Monitor devices that have pending configuration changes by using the pending=true filter. This helps administrators track which devices are waiting for configuration updates to be applied.

Use Case 4: Remote Device Reconfiguration

Update critical device settings remotely using the PUT endpoint. This is essential for maintaining devices in the field, updating network settings, or applying security patches without physical access.

Use Case 5: Wildcard Configuration Search

Use wildcard filtering to find all parameters matching a pattern, such as all network-related variables (network_*) or security settings (sec_*). This helps when working with devices that have standardized naming conventions.

Best Practices

Inventory Device Setting

Endpoints Summary

Method Path Swagger
GET /inventory_device_setting/ Swagger ↗
PUT /inventory_device_setting/{parent_id}/ Swagger ↗
PATCH /inventory_device_setting/{parent_id}/ Swagger ↗

The Inventory Device Setting API endpoints provide comprehensive management of device configuration parameters and settings within the Zequenze Control platform. These endpoints enable you to retrieve, update, and modify device-specific settings including network configurations, operational parameters, and device behavior controls for managed devices in your inventory.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Setting API category manages configuration parameters and settings for devices in your inventory system. These endpoints allow you to:

Device settings in the Zequenze platform are organized around parameters that define how devices behave and operate. Each setting includes metadata about its parameter type, whether it's required, read-only status, and whether it should be tracked as a metric for historical analysis.

Common scenarios include configuring network settings for CPE devices, updating firmware parameters, managing security settings, and monitoring operational metrics across your device fleet.

Endpoints

GET /inventory_device_setting/

Description: Retrieves a paginated list of device settings based on various filter criteria. This endpoint is essential for discovering current device configurations, monitoring setting states, and building device management dashboards.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_setting/?parent_id=123&pending=false&limit=50

Parameters:

Parameter Type In Required Description
parent_id integer query Yes Filter settings by device ID (parent ID field)
parameter_id string query No Filter by specific parameter ID
parameter__variable_name string query No Filter by parameter variable name (e.g., "wifi_ssid", "dhcp_enabled")
parameter__name string query No Filter by human-readable parameter name
parameter__short_name string query No Filter by parameter short name identifier
limit integer query No Number of results per page (default varies)
offset integer query No Starting index for pagination
pending boolean query No Show only settings with pending changes (true/false)

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_setting/?parent_id=123&parameter__variable_name=wifi_ssid&limit=25" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 45,
  "next": "https://control.zequenze.com/api/v1/inventory_device_setting/?limit=25&offset=25&parent_id=123",
  "previous": null,
  "results": [
    {
      "id": 1001,
      "parent_id": "123",
      "parent__name": "Router-Branch-Office-01",
      "parameter": {
        "id": 15,
        "name": "WiFi Network Name",
        "short_name": "wifi-ssid",
        "variable_name": "wifi_ssid",
        "type": "string",
        "position": 1,
        "required": true,
        "read_only": false,
        "metric": false,
        "group": {
          "id": 3,
          "name": "Wireless Settings",
          "service": "wifi",
          "title": "WiFi Configuration"
        }
      },
      "value": "CompanyWiFi_Guest",
      "extra": false,
      "extra_value": null,
      "created": "2024-01-15T10:30:00Z",
      "last_change": "2024-01-20T14:22:00Z",
      "pending": false
    },
    {
      "id": 1002,
      "parent_id": "123",
      "parent__name": "Router-Branch-Office-01",
      "parameter": {
        "id": 16,
        "name": "DHCP Enabled",
        "short_name": "dhcp-enabled",
        "variable_name": "dhcp_enabled",
        "type": "boolean",
        "position": 2,
        "required": true,
        "read_only": false,
        "metric": true,
        "group": {
          "id": 4,
          "name": "Network Settings",
          "service": "network",
          "title": "Network Configuration"
        }
      },
      "value": "true",
      "extra": false,
      "extra_value": null,
      "created": "2024-01-15T10:30:00Z",
      "last_change": "2024-01-18T09:15:00Z",
      "pending": true
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns paginated list of device settings
400 Bad Request - Invalid query parameters
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient permissions to access device settings

PUT /inventory_device_setting/{parent_id}/

Description: Performs a complete update of all device settings for a specific device (parent_id). This endpoint replaces the entire configuration set, making it ideal for bulk configuration updates and device provisioning scenarios.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_setting/123/

Parameters:

Parameter Type In Required Description
parent_id integer path Yes Device ID for which to update all settings
data object body Yes Complete configuration data containing all device settings

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_setting/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": [
      {
        "parameter_id": 15,
        "value": "NewCompanyWiFi"
      },
      {
        "parameter_id": 16,
        "value": "true"
      },
      {
        "parameter_id": 17,
        "value": "192.168.1.1"
      }
    ]
  }'

Example Response:

{
  "id": 1001,
  "parent_id": "123",
  "parent__name": "Router-Branch-Office-01",
  "parameter": {
    "id": 15,
    "name": "WiFi Network Name",
    "short_name": "wifi-ssid",
    "variable_name": "wifi_ssid",
    "type": "string",
    "position": 1,
    "required": true,
    "read_only": false,
    "metric": false,
    "group": {
      "id": 3,
      "name": "Wireless Settings",
      "service": "wifi",
      "discovery_group": "wireless",
      "title": "WiFi Configuration"
    }
  },
  "value": "NewCompanyWiFi",
  "extra": false,
  "extra_value": null,
  "created": "2024-01-15T10:30:00Z",
  "last_change": "2024-01-22T16:45:00Z",
  "pending": true
}

Response Codes:

Status Description
200 Success - Device settings updated successfully
400 Bad Request - Invalid configuration data or parameter values
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient permissions to modify device settings
404 Not Found - Device with specified parent_id does not exist

PATCH /inventory_device_setting/{parent_id}/

Description: Performs partial updates to device settings for a specific device. Unlike PUT, this endpoint allows you to modify only specific settings without affecting the rest of the device configuration, making it perfect for targeted configuration changes.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_setting/123/

Parameters:

Parameter Type In Required Description
parent_id integer path Yes Device ID for which to update specific settings
data object body Yes Partial configuration data containing only the settings to modify

cURL Example:

curl -X PATCH "https://control.zequenze.com/api/v1/inventory_device_setting/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameter_id": 16,
    "value": "false"
  }'

Example Response:

{
  "id": 1002,
  "parent_id": "123",
  "parent__name": "Router-Branch-Office-01",
  "parameter": {
    "id": 16,
    "name": "DHCP Enabled",
    "short_name": "dhcp-enabled",
    "variable_name": "dhcp_enabled",
    "type": "boolean",
    "position": 2,
    "required": true,
    "read_only": false,
    "metric": true,
    "group": {
      "id": 4,
      "name": "Network Settings",
      "service": "network",
      "discovery_group": "network",
      "title": "Network Configuration"
    }
  },
  "value": "false",
  "extra": false,
  "extra_value": null,
  "created": "2024-01-15T10:30:00Z",
  "last_change": "2024-01-22T17:20:00Z",
  "pending": true
}

Response Codes:

Status Description
200 Success - Specific device settings updated successfully
400 Bad Request - Invalid parameter data or values
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient permissions to modify device settings
404 Not Found - Device or parameter does not exist

Common Use Cases

Use Case 1: Device Configuration Dashboard

Build a comprehensive device management dashboard by first retrieving all settings for multiple devices, then use the parameter filtering to organize settings by groups (WiFi, Network, Security). Use the GET endpoint with different parent_id values and parameter filters.

Use Case 2: Bulk WiFi Configuration Update

When updating WiFi credentials across multiple branch office routers, use the PATCH endpoint to update only the WiFi-related parameters (SSID, password, security type) without affecting other network settings.

Use Case 3: New Device Provisioning

For new device deployments, use the PUT endpoint to apply a complete configuration template that includes all required parameters for the device type, ensuring consistent setup across your infrastructure.

Use Case 4: Configuration Change Monitoring

Monitor pending changes across your device fleet by using the GET endpoint with pending=true to identify devices with configuration changes waiting to be applied, enabling proactive change management.

Use Case 5: Compliance Reporting

Generate compliance reports by filtering settings using parameter names related to security configurations (firewall settings, encryption parameters, access controls) across all managed devices.

Best Practices

Inventory Device Variables

Endpoints Summary

Method Path Swagger
GET /inventory_device_variables/ Swagger ↗
PUT /inventory_device_variables/{parent_id}/ Swagger ↗

The Inventory Device Variables API provides access to device configuration parameters and settings for network devices. These endpoints allow you to retrieve current variable values, monitor pending changes, and update device configurations programmatically. Essential for device management, configuration automation, and monitoring system state across your network infrastructure.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Variables API enables comprehensive management of device configuration parameters within the Zequenze control platform. This API category focuses on the variables and settings that define device behavior, performance characteristics, and operational parameters.

Key Concepts:

Common Integration Scenarios:

These endpoints work together to provide complete lifecycle management of device configurations, from initial discovery through ongoing maintenance and updates.

Endpoints

GET /inventory_device_variables/

Description: Retrieves device configuration variables and their current values for a specified device. This endpoint supports extensive filtering options to target specific parameters and can optionally force real-time updates from devices rather than returning cached values.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_variables/?parent_id=123&parameter__variable_name=snmp_community,mgmt_ip&extra=true&pending=true

Parameters:

Parameter Type In Required Description
parent_id integer query Yes The unique identifier of the parent device whose variables you want to retrieve
parameter__variable_name string query No Comma-separated list of specific variable names to filter (e.g., "snmp_community,mgmt_ip,hostname")
parameter__name string query No Comma-separated list of parameter display names to retrieve
parameter__short_name string query No Comma-separated list of parameter short names for filtering
limit integer query No Number of results per page for pagination (default varies by server configuration)
offset integer query No Starting position for paginated results (0-based indexing)
pending boolean query No Include information about whether parameters have uncommitted changes waiting to be applied
wildcard boolean query No Allow wildcard (*) matching in variable_name and parameter name fields
force_update boolean query No Force real-time retrieval from device instead of using cached values
extra boolean query No Include additional metadata and extended information for each parameter
dates boolean query No Include timestamp information for when parameters were last modified

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_variables/?parent_id=123&parameter__variable_name=snmp_community,mgmt_ip&extra=true&pending=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 15,
  "next": "https://control.zequenze.com/api/v1/inventory_device_variables/?limit=10&offset=10&parent_id=123",
  "previous": null,
  "results": [
    {
      "id": 1247,
      "name": "SNMP Community String",
      "variable_name": "snmp_community",
      "value": "public",
      "type": "string",
      "short_name": "SNMP Comm",
      "extra": true,
      "extra_value": "v2c protocol",
      "pending": false
    },
    {
      "id": 1248,
      "name": "Management IP Address",
      "variable_name": "mgmt_ip",
      "value": "192.168.1.100",
      "type": "ipv4",
      "short_name": "Mgmt IP",
      "extra": false,
      "extra_value": null,
      "pending": true
    },
    {
      "id": 1249,
      "name": "Device Hostname",
      "variable_name": "hostname",
      "value": "core-switch-01",
      "type": "string",
      "short_name": "Hostname",
      "extra": false,
      "extra_value": null,
      "pending": false
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns device variables matching the specified criteria
400 Bad Request - Invalid parent_id or malformed query parameters
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Device with specified parent_id does not exist
500 Internal Server Error - Server-side error occurred

PUT /inventory_device_variables/{parent_id}/

Description: Updates device configuration variables for a specified device. This endpoint accepts bulk variable updates and stages them as pending changes that can be applied to the device. The update operation supports both individual parameter changes and batch modifications.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_variables/123/

Parameters:

Parameter Type In Required Description
parent_id integer path Yes The unique identifier of the device whose variables are being updated
data string body Yes JSON payload containing the variable updates to apply

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_variables/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "variable_name": "mgmt_ip",
    "value": "192.168.1.150"
  }'

Example Request Body:

{
  "variable_name": "snmp_community",
  "value": "monitoring123"
}

Example Response:

{
  "id": 1247,
  "name": "SNMP Community String",
  "variable_name": "snmp_community",
  "value": "monitoring123",
  "type": "string",
  "short_name": "SNMP Comm",
  "extra": true,
  "extra_value": "v2c protocol",
  "pending": true
}

Response Codes:

Status Description
200 Success - Variable updated successfully and staged as pending
400 Bad Request - Invalid data format or variable constraints violated
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Device or variable does not exist
422 Unprocessable Entity - Data validation failed
500 Internal Server Error - Server-side error occurred

Common Use Cases

Use Case 1: Configuration Audit and Compliance

Retrieve all device variables to verify configurations meet organizational standards, then generate compliance reports highlighting any deviations.

# Get all variables for compliance check
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_variables/?parent_id=123&extra=true&dates=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 2: Bulk IP Address Updates

Update management IP addresses across multiple devices during network restructuring, staging changes to be applied during maintenance windows.

# Update management IP address
curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_variables/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"variable_name": "mgmt_ip", "value": "10.0.1.100"}'

Use Case 3: Monitoring Pending Changes

Check for uncommitted configuration changes before deploying updates to production devices, ensuring change control processes are followed.

# Check for pending changes
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_variables/?parent_id=123&pending=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 4: Real-time Configuration Verification

Force real-time retrieval of device variables to verify that applied changes are active on the device, bypassing cached values.

# Force update from device
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_variables/?parent_id=123&force_update=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 5: Selective Parameter Management

Retrieve and update only specific configuration parameters using wildcard filtering, useful for managing specific aspects like SNMP settings across device fleets.

# Get only SNMP-related variables
curl -X GET "https://control.zequenze.com/api/v1/inventory_device_variables/?parent_id=123&parameter__variable_name=snmp_*&wildcard=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Best Practices

Inventory Device Whip

Endpoints Summary

Method Path Swagger
GET /inventory_device_whip/{id}/ Swagger ↗

The inventory device whip API provides remote device management capabilities, allowing administrators to execute critical operations on network devices through a centralized control interface. This endpoint enables remote rebooting, factory resets, configuration synchronization, and device reconfiguration operations for efficient device lifecycle management.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The inventory device whip API is designed for remote device management and control operations in network infrastructure environments. This API category provides a secure interface for executing administrative commands on managed devices without requiring physical access or direct device connections.

Key Capabilities:

Common Use Cases:

The API follows a command-based approach where operations are specified using predefined operation codes, ensuring consistent and reliable device management across different hardware types and vendors.

Endpoints

GET /inventory_device_whip/{id}/

Description: Retrieves device operation configuration and available commands for a specific managed device. This endpoint provides information about supported operations and current device state, allowing administrators to understand what management actions can be performed on the target device.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_whip/12345/

Parameters:

Parameter Type In Required Description
id integer path Yes Unique identifier of the managed device to retrieve operation information for

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_whip/12345/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "id": 12345,
  "operation": "reboot",
  "device_name": "Switch-Floor-3-A",
  "device_type": "network_switch",
  "model": "Cisco Catalyst 2960",
  "serial_number": "FCW2147L0GH",
  "management_ip": "192.168.1.100",
  "location": "Building A - Floor 3",
  "available_operations": [
    "reboot",
    "factory", 
    "device_factory",
    "sync",
    "reconf"
  ],
  "last_operation": {
    "operation": "sync",
    "timestamp": "2024-01-15T14:30:00Z",
    "status": "completed",
    "initiated_by": "admin@company.com"
  },
  "device_status": "online",
  "firmware_version": "15.2(7)E3",
  "uptime": "45 days, 12:34:56"
}

Operation Types Reference:

Operation Code Description Use Case
reboot Standard device restart Apply configuration changes, resolve performance issues
factory Complete factory reset Return device to original factory state
device_factory Device-specific factory reset Vendor-specific factory reset procedure
sync Configuration synchronization Update device with latest configuration from management system
reconf Device reconfiguration Apply new configuration parameters without full reset

Response Codes:

Status Description
200 Success - Returns device operation information
401 Unauthorized - Invalid or missing authentication token
403 Forbidden - Insufficient permissions for device access
404 Not Found - Device ID does not exist or is not accessible
500 Internal Server Error - Device communication failure

Common Use Cases

Use Case 1: Network Troubleshooting Workflow

When network devices experience connectivity or performance issues, administrators can use this endpoint to verify device accessibility and execute remote reboots to resolve common problems without requiring on-site visits.

Use Case 2: Configuration Drift Remediation

Regular configuration audits may reveal devices that have drifted from standard configurations. Use the sync operation to restore proper configurations and the reconf operation to apply updated policies across the network infrastructure.

Use Case 3: Device Replacement and Provisioning

During hardware refresh cycles, use factory or device_factory operations to prepare devices for redeployment, followed by sync operations to apply appropriate configurations for new network locations.

Use Case 4: Scheduled Maintenance Operations

Implement automated maintenance workflows that check device status and execute planned operations during maintenance windows, such as configuration updates followed by controlled reboots.

Use Case 5: Emergency Recovery Procedures

When devices become unresponsive or misconfigured, use this API to execute recovery operations remotely, potentially avoiding costly site visits and reducing network downtime.

Best Practices

Inventory Metric

Endpoints Summary

Method Path Swagger
GET /inventory_metric/ Swagger ↗
GET /inventory_metric/{id}/ Swagger ↗

The Inventory Metric API provides endpoints for retrieving and managing inventory metrics within the Zequenze Control system. These endpoints allow you to access detailed information about various measurement parameters used to track inventory performance, resource utilization, and operational statistics across your infrastructure.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Metric API is designed to help you access and manage the various metrics that track your inventory system's performance and status. Metrics are essential measurement points that provide insights into resource utilization, operational efficiency, and system health across your infrastructure.

These endpoints are commonly used for:

The API supports three types of metrics: Absolute (point-in-time values), Counter (cumulative values that increase over time), and Delta (change values between measurements). Each metric can be organized into groups and linked to specific parameters for structured data organization.

Endpoints

GET /inventory_metric/

Description: Retrieves a paginated list of all inventory metrics available in your system. This endpoint is essential for discovering available metrics, building metric catalogs, and implementing metric selection interfaces in applications.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_metric/?name=cpu_usage&limit=20&offset=0

Parameters:

Parameter Type In Required Description
name string query No Filter results by metric name. Supports partial matching for finding metrics containing specific keywords
limit integer query No Number of results to return per page. Default is typically 20, maximum varies by system configuration
offset integer query No The initial index from which to return results. Used for pagination through large metric lists

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_metric/?name=storage&limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 45,
  "next": "https://control.zequenze.com/api/v1/inventory_metric/?limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "id": 101,
      "name": "storage_utilization_percent",
      "group": 5,
      "description": "Percentage of storage space currently utilized across all storage devices",
      "type": "a",
      "parameter": 1001
    },
    {
      "id": 102,
      "name": "storage_capacity_gb",
      "group": 5,
      "description": "Total storage capacity in gigabytes available in the inventory",
      "type": "a",
      "parameter": 1002
    },
    {
      "id": 103,
      "name": "storage_requests_total",
      "group": 5,
      "description": "Cumulative count of storage allocation requests processed",
      "type": "c",
      "parameter": 1003
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns paginated list of inventory metrics
401 Unauthorized - Invalid or missing Bearer token
403 Forbidden - Insufficient permissions to access metrics
500 Internal Server Error - System error occurred

GET /inventory_metric/{id}/

Description: Retrieves detailed information about a specific inventory metric by its unique identifier. This endpoint provides complete metric configuration details including its type, description, associated group, and parameter relationships.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_metric/101/

Parameters:

Parameter Type In Required Description
id integer path Yes Unique identifier of the inventory metric to retrieve
name string query No Additional filter by metric name (typically not needed when using specific ID)

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_metric/101/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "id": 101,
  "name": "cpu_utilization_percent",
  "group": 3,
  "description": "Average CPU utilization percentage across all compute resources in inventory",
  "type": "a",
  "parameter": 2001
}

Response Codes:

Status Description
200 Success - Returns the requested inventory metric details
401 Unauthorized - Invalid or missing Bearer token
403 Forbidden - Insufficient permissions to access this metric
404 Not Found - Metric with specified ID does not exist
500 Internal Server Error - System error occurred

Common Use Cases

Use Case 1: Building a Metrics Dashboard

Retrieve all available metrics using the list endpoint, then fetch specific metric details to populate dashboard configuration options. Filter by name to find metrics related to specific categories like "cpu", "memory", or "network".

Use Case 2: Monitoring System Integration

Use both endpoints to discover available metrics and their types (Absolute, Counter, Delta) to properly configure external monitoring tools that need to understand how to aggregate and display the data correctly.

Use Case 3: Metric Validation and Documentation

Fetch individual metrics by ID to validate their current configuration, understand their parameter relationships, and generate documentation about what metrics are available in your inventory system.

Use Case 4: Performance Analysis Setup

Query metrics by name patterns to find all performance-related metrics, then use the detailed endpoint to understand their types and descriptions for setting up automated performance analysis workflows.

Use Case 5: Audit and Compliance Reporting

Retrieve comprehensive lists of all tracked metrics to ensure compliance with monitoring requirements and to document what operational data is being collected from your inventory systems.

Best Practices

Inventory Metric Log

Endpoints Summary

Method Path Swagger
GET /inventory_metric_log/ Swagger ↗
GET /inventory_metric_log/{id}/ Swagger ↗

The inventory metric log endpoints provide access to historical metric data from monitored inventory devices. These endpoints allow you to retrieve time-series data for device parameters, filter by time ranges and device characteristics, and analyze performance trends across your infrastructure.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The inventory metric log API category enables you to access and analyze historical performance and status data from your monitored devices. These endpoints are essential for:

The metric logs capture data from various sources (automatic monitoring, manual entry, scripts, APIs) and provide a comprehensive audit trail of device performance. Each log entry includes the original value, processed result, timestamp, and origin information to ensure data integrity and traceability.

Key concepts:

Endpoints

GET /inventory_metric_log/

Description: Retrieves a paginated list of inventory metric log entries with comprehensive filtering capabilities. This endpoint is your primary tool for querying historical device performance data, allowing you to filter by time ranges, device names, parameter types, and metric names to extract exactly the data you need for analysis.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_metric_log/?datetime__gte=2024-01-01&device__name=server-01&parameter__variable_name=cpu_usage&limit=50

Parameters:

Parameter Type In Required Description
datetime__gte string query No Filter for metrics recorded on or after this date/time (ISO format: 2000-01-01, 2000-01-01 00:01:00, 2000-01-01 00:01:00+00:00)
datetime__lte string query No Filter for metrics recorded on or before this date/time (ISO format: 2000-01-01, 2000-01-01 00:01:00, 2000-01-01 00:01:00+00:00)
device__name string query No Filter by the exact device name to get metrics from specific devices
metric__name string query No Filter by metric name to focus on specific measurement types
parameter__name string query No Filter by parameter name to get specific types of measurements
parameter__short_name string query No Filter using the abbreviated parameter name
parameter__variable_name string query No Filter by the technical variable name used in the system
cursor string query No Pagination cursor for navigating through large result sets
limit integer query No Number of results per page (default varies, recommend 50-100 for performance)
metric_name string query No Alternative filter for metric's parameter name field
parameter_name string query No Alternative filter for metric's parameter name field

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_metric_log/?datetime__gte=2024-01-01&device__name=web-server-01&parameter__variable_name=memory_usage&limit=100" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "next": "https://control.zequenze.com/api/v1/inventory_metric_log/?cursor=eyJpZCI6MTAwfQ%3D%3D",
  "previous": null,
  "results": [
    {
      "id": 1547,
      "datetime": "2024-01-15T14:30:00.123456Z",
      "device_name": "web-server-01",
      "parameter_name": "Memory Usage",
      "metric_name": "System Memory",
      "origin": "au",
      "value": 78.5,
      "result": 78.5,
      "original_value": "78.5%"
    },
    {
      "id": 1546,
      "datetime": "2024-01-15T14:25:00.987654Z",
      "device_name": "web-server-01",
      "parameter_name": "Memory Usage",
      "metric_name": "System Memory",
      "origin": "au",
      "value": 76.2,
      "result": 76.2,
      "original_value": "76.2%"
    },
    {
      "id": 1545,
      "datetime": "2024-01-15T14:20:00.555123Z",
      "device_name": "web-server-01",
      "parameter_name": "CPU Usage",
      "metric_name": "System CPU",
      "origin": "sc",
      "value": 45.8,
      "result": 45.8,
      "original_value": "45.8"
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns paginated metric log data
401 Unauthorized - Invalid or missing authentication token
400 Bad Request - Invalid filter parameters or date format

GET /inventory_metric_log/{id}/

Description: Retrieves detailed information for a specific inventory metric log entry by its unique ID. This endpoint provides the same filtering capabilities as the list endpoint but returns only the single record that matches both the ID and any additional filter criteria you specify.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_metric_log/1547/?device__name=web-server-01

Parameters:

Parameter Type In Required Description
id integer path Yes The unique identifier of the metric log entry to retrieve
datetime__gte string query No Additional filter: entry datetime must be on or after this date
datetime__lte string query No Additional filter: entry datetime must be on or before this date
device__name string query No Additional filter: verify the entry belongs to this device
metric_name string query No Additional filter: verify the entry has this metric name
parameter_name string query No Additional filter: verify the entry has this parameter name
parameter__variable_name string query No Additional filter: verify the entry has this variable name

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_metric_log/1547/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "id": 1547,
  "datetime": "2024-01-15T14:30:00.123456Z",
  "device_name": "web-server-01",
  "parameter_name": "Memory Usage",
  "metric_name": "System Memory",
  "origin": "au",
  "value": 78.5,
  "result": 78.5,
  "original_value": "78.5%"
}

Response Codes:

Status Description
200 Success - Returns the requested metric log entry
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Metric log entry with specified ID doesn't exist or doesn't match filters
400 Bad Request - Invalid filter parameters

Common Use Cases

Use Case 1: Performance Trend Analysis

Monitor CPU and memory usage trends for critical servers over the past week to identify performance patterns and potential capacity issues.

# Get CPU metrics for the last 7 days
curl -X GET "https://control.zequenze.com/api/v1/inventory_metric_log/?datetime__gte=2024-01-08&datetime__lte=2024-01-15&device__name=prod-server-01&parameter__variable_name=cpu_usage&limit=200" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 2: Incident Investigation

Examine all metric data from a specific device during a known incident timeframe to correlate performance issues with system problems.

# Get all metrics during incident window
curl -X GET "https://control.zequenze.com/api/v1/inventory_metric_log/?datetime__gte=2024-01-15T02:00:00&datetime__lte=2024-01-15T04:00:00&device__name=database-server-03" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 3: Automated Data Collection Verification

Verify that automatic monitoring systems are properly collecting data by filtering for specific origins and checking data continuity.

# Check recent automatic measurements
curl -X GET "https://control.zequenze.com/api/v1/inventory_metric_log/?datetime__gte=2024-01-15&origin=au&limit=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 4: Custom Dashboard Data Export

Export specific metric data for integration with external monitoring dashboards or business intelligence tools.

# Export temperature data for environmental monitoring
curl -X GET "https://control.zequenze.com/api/v1/inventory_metric_log/?parameter__variable_name=temperature&datetime__gte=2024-01-01&limit=1000" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 5: Compliance Reporting

Generate historical reports for compliance audits by retrieving metric data with proper origin tracking and timestamps.

# Get manual entries for audit trail
curl -X GET "https://control.zequenze.com/api/v1/inventory_metric_log/?origin=ma&datetime__gte=2024-01-01&datetime__lte=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Best Practices

Inventory Parameter

Endpoints Summary

Method Path Swagger
GET /inventory_parameter/ Swagger ↗
GET /inventory_parameter/{id}/ Swagger ↗

The Inventory Parameter API endpoints provide access to parameter definitions that control how device attributes are collected, displayed, and managed within the Zequenze Control platform. These endpoints allow you to retrieve parameter configurations including their data types, validation rules, and grouping information.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Parameter API category manages the parameter definitions used throughout the Zequenze Control platform for device management and monitoring. Parameters define the structure and behavior of data fields that can be collected from managed devices, displayed in the user interface, and used for device configuration.

Each inventory parameter contains metadata such as data type (string, integer, boolean, etc.), validation requirements, display properties, and grouping information. Parameters can be configured as metrics to enable historical data collection, marked as read-only for displaying device-reported information, or set as required fields for configuration validation.

These endpoints are essential for:

Parameter groups organize related parameters together and can be associated with specific services or discovery processes. The API supports filtering parameters by group and provides detailed information about parameter properties and their relationships.

Endpoints

GET /inventory_parameter/

Description: Retrieves a paginated list of all inventory parameters in the system. This endpoint returns parameter definitions including their data types, validation rules, grouping, and configuration properties. Use this endpoint to discover available parameters, understand their structure, or build custom interfaces that work with the platform's parameter system.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_parameter/?group=15&limit=50&offset=0

Parameters:

Parameter Type In Required Description
group integer query No Filter parameters by group ID to retrieve only parameters belonging to a specific parameter group
limit integer query No Number of results to return per page (default pagination applies if not specified)
offset integer query No The initial index from which to return results for pagination

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_parameter/?group=15&limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 87,
  "next": "https://control.zequenze.com/api/v1/inventory_parameter/?group=15&limit=20&offset=20",
  "previous": null,
  "results": [
    {
      "id": 42,
      "name": "Device Serial Number",
      "short_name": "device-serial",
      "variable_name": "device_serial_number",
      "type": "string",
      "position": 1,
      "required": true,
      "read_only": true,
      "metric": false,
      "group": {
        "id": 15,
        "name": "Device Information",
        "service": "device-mgmt",
        "discovery_group": false,
        "title": "Basic Device Information"
      }
    },
    {
      "id": 43,
      "name": "Firmware Version",
      "short_name": "firmware-version",
      "variable_name": "firmware_version",
      "type": "readonly",
      "position": 2,
      "required": false,
      "read_only": true,
      "metric": true,
      "group": {
        "id": 15,
        "name": "Device Information",
        "service": "device-mgmt",
        "discovery_group": false,
        "title": "Basic Device Information"
      }
    },
    {
      "id": 44,
      "name": "Device Status",
      "short_name": "device-status",
      "variable_name": "device_status",
      "type": "select",
      "position": 3,
      "required": true,
      "read_only": false,
      "metric": true,
      "group": {
        "id": 15,
        "name": "Device Information",
        "service": "device-mgmt",
        "discovery_group": false,
        "title": "Basic Device Information"
      }
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns paginated list of inventory parameters
401 Unauthorized - Invalid or missing authentication token
400 Bad Request - Invalid query parameters

GET /inventory_parameter/{id}/

Description: Retrieves detailed information about a specific inventory parameter by its unique ID. This endpoint provides complete parameter definition including all properties, validation rules, and group information. Use this endpoint when you need full details about a specific parameter for configuration or display purposes.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_parameter/42/

Parameters:

Parameter Type In Required Description
id integer path Yes The unique identifier of the inventory parameter to retrieve
group integer query No Additional filter by group ID (optional constraint for validation)

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_parameter/42/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "id": 42,
  "name": "Device Serial Number",
  "short_name": "device-serial",
  "variable_name": "device_serial_number",
  "type": "string",
  "position": 1,
  "required": true,
  "read_only": true,
  "metric": false,
  "group": {
    "id": 15,
    "name": "Device Information",
    "service": "device-mgmt",
    "discovery_group": false,
    "title": "Basic Device Information"
  }
}

Response Codes:

Status Description
200 Success - Returns the specified inventory parameter
401 Unauthorized - Invalid or missing authentication token
404 Not Found - Parameter with specified ID does not exist
400 Bad Request - Invalid parameter ID format

Common Use Cases

Use Case 1: Building Dynamic Device Configuration Forms

When creating custom interfaces for device management, use the list endpoint to retrieve all parameters for a specific group, then use their type and validation properties to build appropriate form controls.

Use Case 2: Parameter Discovery for New Services

When integrating a new service, filter parameters by discovery groups to identify automatically discovered parameters, then retrieve their full details to understand what data is being collected.

Use Case 3: Metric Parameter Identification

Query parameters where metric: true to identify which device attributes are being tracked historically, useful for building monitoring dashboards or analytics features.

Use Case 4: Validation Rule Implementation

Retrieve parameter details to understand validation requirements (required, read_only, type) when implementing custom device configuration workflows.

Use Case 5: Parameter Group Analysis

Use the group filter to analyze parameter organization and understand how different device attributes are categorized within the platform.

Best Practices

Inventory Type

Endpoints Summary

Method Path Swagger
GET /inventory_type/ Swagger ↗
GET /inventory_type/{id}/ Swagger ↗

The Inventory Type API endpoints allow you to retrieve information about different device types in your inventory system. These endpoints are essential for understanding the categorization and classification of devices, providing metadata about device profiles including their names, descriptions, and connection requirements.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Type API provides access to device type definitions that categorize and describe different kinds of inventory devices in your system. These device types serve as templates or profiles that define the characteristics, connection requirements, and properties of physical devices in your inventory.

Key Concepts:

Common Scenarios:

The API supports pagination for large datasets and provides filtering capabilities to help you find specific device types efficiently.

Endpoints

GET /inventory_type/

Description: Retrieves a paginated list of all inventory device types in the system. This endpoint is primarily used to display available device categories, populate selection interfaces, and provide an overview of supported device types in your inventory management system.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_type/?name=router&limit=20&offset=0

Parameters:

Parameter Type In Required Description
name string query No Filter device types by the 'name' field. Supports partial matching to find device types containing the specified text
limit integer query No Number of results to return per page. Default pagination limit applies if not specified
offset integer query No The initial index from which to return results. Used for pagination to skip a specified number of records

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_type/?name=switch&limit=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 15,
  "next": "https://control.zequenze.com/api/v1/inventory_type/?limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Cisco Catalyst Switch",
      "short_name": "cisco-catalyst-switch",
      "connection_profile": 3,
      "description": "Enterprise-grade Layer 3 switch with PoE+ support and advanced routing capabilities"
    },
    {
      "id": 2,
      "name": "Dell PowerEdge Server",
      "short_name": "dell-poweredge-server",
      "connection_profile": 1,
      "description": "Rack-mounted server for virtualization and enterprise applications"
    },
    {
      "id": 3,
      "name": "Ubiquiti UniFi Access Point",
      "short_name": "ubiquiti-unifi-ap",
      "connection_profile": 2,
      "description": "Wireless access point for enterprise WiFi networks with centralized management"
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns paginated list of inventory device types
401 Unauthorized - Invalid or missing API token
400 Bad Request - Invalid query parameters

GET /inventory_type/{id}/

Description: Retrieves detailed information about a specific inventory device type by its unique identifier. This endpoint provides complete metadata for a single device type, including its connection profile and full description.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/inventory_type/1/

Parameters:

Parameter Type In Required Description
id integer path Yes The unique identifier of the inventory device type to retrieve
name string query No Optional filter by device profile name field (typically used for additional validation)

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_type/1/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "id": 1,
  "name": "Cisco Catalyst 2960-X Switch",
  "short_name": "cisco-catalyst-2960x",
  "connection_profile": 3,
  "description": "24-port Gigabit Ethernet switch with 4 SFP+ uplink ports. Supports PoE+, advanced QoS, and Layer 3 static routing. Ideal for enterprise access layer deployment with centralized management capabilities."
}

Response Codes:

Status Description
200 Success - Returns the requested device type details
401 Unauthorized - Invalid or missing API token
404 Not Found - Device type with specified ID does not exist
400 Bad Request - Invalid ID format or query parameters

Common Use Cases

Use Case 1: Building Device Registration Interface

Retrieve all available device types to populate a dropdown menu when administrators add new devices to inventory. Use the list endpoint with pagination to handle large numbers of device types efficiently.

Use Case 2: Device Type Validation

Before registering a new device, fetch specific device type details to validate connection requirements and ensure proper categorization in the inventory system.

Use Case 3: Inventory Reporting and Analytics

Query device types to generate reports that group and categorize inventory devices, using the short_name field for consistent chart labels and the full name for detailed reports.

Use Case 4: Connection Profile Management

Retrieve device types with their associated connection profiles to understand network configuration requirements and automate device setup procedures.

Use Case 5: Administrative Device Type Search

Use the name filter parameter to quickly locate specific device types in administrative interfaces, especially useful in environments with many different device categories.

Best Practices

Securedns Categoryget

Endpoints Summary

Method Path Swagger
GET /securedns_categoryget/ Swagger ↗

The SecureDNS Category API provides functionality to retrieve category information for SecureDNS transactions using their unique identifiers. This endpoint is essential for understanding the classification of DNS security events and can be integrated into security monitoring workflows, reporting systems, and compliance auditing processes.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The SecureDNS Category API enables developers to query the categorization of SecureDNS transactions by providing a UUID-based lookup mechanism. This API is particularly valuable for security operations teams who need to understand the nature and classification of DNS security events that have been processed through the SecureDNS system.

Key Features:

Common Integration Scenarios:

The category information returned by this API helps organizations understand the types of DNS security events they're experiencing, enabling better threat intelligence and more informed security decisions.

Endpoints

GET /securedns_categoryget/

Description: Retrieves the category classification for a specific SecureDNS transaction using its UUID. This endpoint is essential for understanding what type of DNS security event occurred, enabling security teams to properly categorize, respond to, and report on DNS-related security incidents.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/securedns_categoryget/?uuid=550e8400-e29b-41d4-a716-446655440000

Parameters:

Parameter Type In Required Description
uuid string query Yes The unique identifier of the SecureDNS transaction to retrieve category information for

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/securedns_categoryget/?uuid=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

[
  {
    "category": "malware"
  }
]

Response Codes:

Status Description
200 Category request Ok - Returns the category information for the specified transaction
401 Category request not authorized - Invalid or missing authentication token
403 Category request forbidden / not allowed - Valid authentication but insufficient permissions
404 Provided UUID don't match any transaction - The specified UUID does not exist in the system

Common Use Cases

Use Case 1: SIEM Integration for DNS Security Monitoring

Security operations centers integrate this API into their SIEM platforms to automatically categorize DNS security events. When a SecureDNS transaction is flagged, the SIEM system uses the transaction UUID to retrieve the category, enabling automated rule-based responses and proper incident classification.

Use Case 2: Incident Response Investigation

During security incident investigations, analysts use this endpoint to quickly understand the nature of DNS-related security events. By querying transaction UUIDs from security logs, investigators can rapidly categorize threats and determine appropriate response procedures.

Use Case 3: Compliance Reporting and Auditing

Organizations use this API to generate compliance reports that categorize DNS security events. The category information helps demonstrate security monitoring effectiveness and provides detailed classifications required for various regulatory frameworks.

Use Case 4: Automated Threat Response Workflows

Security automation platforms integrate this endpoint to create dynamic response workflows. Different DNS security categories trigger different automated responses, from simple logging for low-risk categories to immediate blocking and alerting for high-risk classifications.

Use Case 5: Security Dashboard Visualization

Security dashboards use this API to display real-time categorized DNS threat intelligence, helping security teams visualize the types and distribution of DNS security events across their organization.

Best Practices

Securedns Hostcheck

Endpoints Summary

Method Path Swagger
GET /securedns_hostcheck/ Swagger ↗

The SecureDNS Host Check API provides real-time hostname filtering and parental control capabilities. This endpoint allows you to verify whether access to specific hostnames should be allowed, refused, or ignored based on your configured security policies and content filtering rules.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The SecureDNS Host Check API is designed for implementing DNS-based content filtering and parental control systems. This service evaluates hostnames against your configured security policies and returns appropriate actions based on category classifications, access control lists (ACLs), and subnet-specific rules.

Key Features:

Common Integration Scenarios:

The API returns structured responses indicating whether requests should be allowed through, redirected to warning pages, or blocked entirely, along with performance metrics and caching information.

Endpoints

GET /securedns_hostcheck/

Description: Performs real-time evaluation of a hostname against your configured SecureDNS policies. The endpoint checks the requested hostname against category filters, access control lists, and subnet-specific rules to determine the appropriate action. All requests are logged for auditing and reporting purposes.

Use Cases:

Full URL Example:

https://control.zequenze.com/api/v1/securedns_hostcheck/?hostname=example.com&client_ip=192.168.1.100&subnet=192.168.1.0/24

Parameters:

Parameter Type In Required Description
hostname string query Yes The hostname or domain to check against SecureDNS policies
client_ip string query Yes The IP address of the client making the request
subnet string query No The subnet identifier to apply specific ACL rules
category_override string query No Override automatic category detection with specific category

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/securedns_hostcheck/?hostname=social-media.com&client_ip=10.0.1.50&subnet=10.0.1.0/24" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response (Allowed):

[
  {
    "action": "A",
    "redirect_ip": "0.0.0.0",
    "match_subnet": "10.0.1.0/24",
    "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "category": "business",
    "acl": "corporate_allow",
    "cached": true,
    "response_time": 12.5
  }
]

Example Response (Blocked):

[
  {
    "action": "R",
    "redirect_ip": "203.0.113.10",
    "match_subnet": "192.168.1.0/24",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "category": "adult_content",
    "acl": "family_safe",
    "cached": false,
    "response_time": 8.3
  }
]

Response Fields:

Field Type Description
action string Action to take: "A" (Allow), "R" (Refuse/Block), "I" (Ignore)
redirect_ip string IP address to redirect blocked requests to (0.0.0.0 for allow)
match_subnet string The subnet rule that matched this request
uuid string Unique identifier for this policy rule match
category string Content category classification (malware, adult_content, social_media, etc.)
acl string Access Control List name that was applied
cached boolean Whether this response was served from cache
response_time number Response time in milliseconds

Response Codes:

Status Description
200 Rule matched and request allowed - hostname passes all filters
401 Request not authorized - invalid or missing API token
403 Request forbidden - hostname blocked by security policy
404 No rule matched - hostname not found in any policy rules
404 Rules matched and request not allowed - hostname explicitly blocked

Common Use Cases

Use Case 1: DNS Resolver Integration

Integrate the SecureDNS API into your DNS resolver to automatically filter malicious domains and inappropriate content. Query each hostname before resolving DNS requests and either allow resolution or redirect to a block page based on the API response.

Use Case 2: Parental Control Router

Implement family-safe internet filtering by checking all outbound web requests through the API. Configure different policies for children's devices versus adult devices using subnet-based rules and redirect blocked content to age-appropriate explanations.

Use Case 3: Corporate Network Security

Protect enterprise networks by filtering access to social media, streaming services, or malware domains during business hours. Use the API to enforce acceptable use policies and maintain productivity while ensuring security compliance.

Use Case 4: Educational Institution Filtering

Deploy content filtering for school networks to block inappropriate content while allowing educational resources. Implement time-based restrictions and category-specific filtering based on different areas of the campus network.

Use Case 5: Security Appliance Integration

Embed the SecureDNS check into network security devices to provide an additional layer of threat protection. Combine with other security feeds to create comprehensive protection against emerging threats and malicious domains.

Best Practices