API Documentation

RESTful API for device management, telemetry data, analytics, and real-time communication. All endpoints support JSON format with comprehensive error handling and authentication.

🔑 Authentication

All API endpoints require authentication using Bearer tokens. Include the token in the Authorization header: Authorization: Bearer YOUR_API_KEY

curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.valtronics.com/v1/devices

Overview

The Valtronics API provides comprehensive access to device management, telemetry data, analytics, and real-time communication capabilities. The API follows RESTful principles and uses standard HTTP status codes.

Base URL

https://api.valtronics.com/v1

All API endpoints are relative to this base URL. The API version is v1.

Devices

Manage IoT devices, register new devices, and monitor device status and configuration.

Device Management

GET /devices

Retrieve a list of all registered devices with their current status and configuration.

Query Parameters:
Parameter Type Required Description
page integer No Page number (default: 1)
limit integer No Items per page (default: 50, max: 100)
status string No Filter by device status (online, offline, error)
Response Example:
{ "devices": [ { "id": "VT-ESP32-001", "name": "Temperature Sensor 1", "type": "temperature_sensor", "status": "online", "last_seen": "2024-01-15T10:30:00Z", "location": "Building A - Floor 1", "firmware_version": "2.0.0", "platform": "esp32" } ], "pagination": { "page": 1, "limit": 50, "total": 1, "pages": 1 } }
POST /devices

Register a new device with the platform and receive a unique device ID.

Request Body:
Parameter Type Required Description
name string Yes Device name
type string Yes Device type (temperature_sensor, humidity_sensor, etc.)
platform string Yes Hardware platform (esp32, arduino, stm32)
location string No Device location
Response Example:
{ "device": { "id": "VT-ESP32-002", "name": "New Temperature Sensor", "type": "temperature_sensor", "platform": "esp32", "location": "Building B - Floor 2", "status": "offline", "created_at": "2024-01-15T10:30:00Z", "api_key": "device_api_key_here" } }
GET /devices/{device_id}

Get detailed information about a specific device.

Response Example:
{ "device": { "id": "VT-ESP32-001", "name": "Temperature Sensor 1", "type": "temperature_sensor", "status": "online", "last_seen": "2024-01-15T10:30:00Z", "location": "Building A - Floor 1", "firmware_version": "2.0.0", "platform": "esp32", "configuration": { "sampling_interval": 30, "alert_threshold": 30.0, "calibration_offset": 0.5 }, "sensors": [ { "id": "temp_01", "type": "temperature", "model": "DHT22", "status": "active" } ] } }
PUT /devices/{device_id}

Update device configuration and settings.

Request Example:
{ "name": "Updated Temperature Sensor", "location": "Building A - Floor 1 - Room 101", "configuration": { "sampling_interval": 60, "alert_threshold": 35.0, "calibration_offset": 1.0 } }
DELETE /devices/{device_id}

Remove a device from the platform. This action cannot be undone.

Response Example:
{ "message": "Device VT-ESP32-001 deleted successfully" }

Telemetry

Access real-time and historical sensor data from devices with flexible query parameters.

Data Access

GET /telemetry/{device_id}

Get the latest telemetry data from a specific device.

Query Parameters:
Parameter Type Required Description
sensors string No Comma-separated list of sensor types
limit integer No Number of records to return (default: 100)
Response Example:
{ "device_id": "VT-ESP32-001", "telemetry": [ { "timestamp": "2024-01-15T10:30:00Z", "sensors": { "temperature": { "value": 25.5, "unit": "C", "quality": 0.95 }, "humidity": { "value": 60.2, "unit": "%", "quality": 0.92 } } } ] }
GET /telemetry/{device_id}/history

Get historical telemetry data for a specific device.

Query Parameters:
Parameter Type Required Description
from string No Start date (ISO 8601 format)
to string No End date (ISO 8601 format)
interval string No Aggregation interval (1m, 5m, 1h, 1d)
POST /telemetry/{device_id}

Submit telemetry data from a device (used by devices to send data).

Request Example:
{ "timestamp": "2024-01-15T10:30:00Z", "sensors": { "temperature": { "value": 25.5, "unit": "C" }, "humidity": { "value": 60.2, "unit": "%" } } }

Analytics

Retrieve AI-powered insights, predictive maintenance recommendations, and data analytics.

Analytics Endpoints

GET /analytics/{device_id}/insights

Get AI-powered insights and analysis for a specific device.

Response Example:
{ "device_id": "VT-ESP32-001", "insights": [ { "type": "trend_analysis", "description": "Temperature showing upward trend over last 24 hours", "confidence": 0.85, "timestamp": "2024-01-15T10:30:00Z" }, { "type": "anomaly_detection", "description": "Unusual humidity spike detected", "severity": "medium", "confidence": 0.92 } ] }
GET /analytics/{device_id}/predictions

Get predictive maintenance recommendations and failure predictions.

Response Example:
{ "device_id": "VT-ESP32-001", "predictions": { "health_score": 0.88, "maintenance_needed": false, "predicted_failure": null, "next_maintenance": "2024-02-15T00:00:00Z", "recommendations": [ "Sensor calibration recommended within 30 days", "Firmware update available for improved accuracy" ] } }

Alerts

Manage device alerts, configure alert rules, and receive notifications.

Alert Management

GET /alerts

Get all active alerts across all devices.

Query Parameters:
Parameter Type Required Description
severity string No Filter by severity (low, medium, high, critical)
device_id string No Filter by specific device
Response Example:
{ "alerts": [ { "id": "alert_001", "device_id": "VT-ESP32-001", "type": "threshold_exceeded", "severity": "high", "message": "Temperature exceeded threshold of 30°C", "timestamp": "2024-01-15T10:30:00Z", "acknowledged": false } ] }
POST /alerts/{alert_id}/acknowledge

Acknowledge an alert to mark it as seen.

⏱️ Rate Limits

API requests are rate-limited to ensure fair usage and system stability. Current limits are 1000 requests per hour per API key.

Rate Limit Headers:
Header Description
X-RateLimit-Limit Maximum requests per hour
X-RateLimit-Remaining Remaining requests in current window
X-RateLimit-Reset Unix timestamp when rate limit resets