Skip to content

api overview

Jump to bottom
Valtronics Team edited this page May 4, 2026 · 1 revision

Valtronics API Overview

Complete API documentation for the Valtronics system

Overview

The Valtronics API provides a comprehensive RESTful interface for managing devices, telemetry data, alerts, and analytics. The API is built using FastAPI and follows OpenAPI 3.0 specifications.

API Architecture

Base URL

  • Development: http://localhost:8000
  • Production: https://api.valtronics.com
  • API Version: /api/v1

Authentication

  • Method: JWT Bearer Token
  • Header: Authorization: Bearer <token>
  • Expiration: 30 minutes (configurable)
  • Refresh: Token refresh available

Rate Limiting

  • Standard: 100 requests per minute
  • Premium: 1,000 requests per minute
  • Enterprise: Unlimited requests

API Endpoints Summary

Health and System

  • GET /api/v1/health/ - System health check
  • GET /api/v1/health/detailed - Detailed health status

Authentication

  • POST /api/v1/auth/login - User login
  • POST /api/v1/auth/logout - User logout
  • POST /api/v1/auth/refresh - Token refresh
  • GET /api/v1/auth/me - Current user info

Device Management

  • GET /api/v1/devices/ - List all devices
  • POST /api/v1/devices/ - Create new device
  • GET /api/v1/devices/{id} - Get device details
  • PUT /api/v1/devices/{id} - Update device
  • DELETE /api/v1/devices/{id} - Delete device
  • GET /api/v1/devices/stats - Device statistics
  • GET /api/v1/devices/status/{status} - Devices by status

Telemetry Data

  • GET /api/v1/telemetry/ - Get telemetry data
  • POST /api/v1/telemetry/ - Submit telemetry data
  • GET /api/v1/telemetry/latest - Latest telemetry values
  • GET /api/v1/telemetry/history - Historical telemetry data
  • GET /api/v1/telemetry/device/{device_id} - Device telemetry

Alert Management

  • GET /api/v1/alerts/ - List all alerts
  • POST /api/v1/alerts/ - Create new alert
  • GET /api/v1/alerts/{id} - Get alert details
  • PUT /api/v1/alerts/{id} - Update alert
  • DELETE /api/v1/alerts/{id} - Delete alert
  • GET /api/v1/alerts/rules - Alert rules
  • POST /api/v1/alerts/rules - Create alert rule

Analytics and Reporting

  • GET /api/v1/analytics/system - System analytics
  • GET /api/v1/analytics/devices - Device analytics
  • GET /api/v1/analytics/performance - Performance metrics
  • GET /api/v1/analytics/reports - Generate reports
  • GET /api/v1/analytics/trends - Trend analysis

AI and Machine Learning

  • POST /api/v1/ai/insights - AI insights
  • POST /api/v1/ai/anomaly-detection - Anomaly detection
  • POST /api/v1/ai/predictive-maintenance - Predictive maintenance
  • GET /api/v1/ai/health-score/{device_id} - Device health score

WebSocket Connections

  • WS /ws - Real-time data stream
  • WS /ws/notifications - Alert notifications
  • WS /ws/telemetry - Live telemetry data
  • WS /ws/system - System status updates

Request/Response Format

Standard Response Format

{
  "success": true,
  "data": {
    // Response data
  },
  "message": "Operation completed successfully",
  "timestamp": "2024-01-01T12:00:00Z",
  "request_id": "req_123456789"
}

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "field": "device_id",
      "issue": "Required field missing"
    }
  },
  "timestamp": "2024-01-01T12:00:00Z",
  "request_id": "req_123456789"
}

Pagination Format

{
  "success": true,
  "data": {
    "items": [
      // Array of items
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 100,
      "pages": 5,
      "has_next": true,
      "has_prev": false
    }
  }
}

Authentication

Login Request

curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "password123"
  }'

Login Response

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "expires_in": 1800,
    "user": {
      "id": 1,
      "username": "admin",
      "email": "admin@valtronics.com",
      "role": "admin"
    }
  }
}

Using the Token

curl -X GET http://localhost:8000/api/v1/devices/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Device API Examples

List All Devices

curl -X GET http://localhost:8000/api/v1/devices/ \
  -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "name": "Temperature Sensor Alpha",
        "device_id": "TEMP-001",
        "device_type": "sensor",
        "manufacturer": "SensorTech",
        "model": "ST-T1000",
        "firmware_version": "2.1.4",
        "location": "Zone A - Server Room",
        "status": "online",
        "is_active": true,
        "created_at": "2024-01-01T12:00:00Z",
        "updated_at": "2024-01-01T12:00:00Z",
        "last_seen": "2024-01-01T12:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 5,
      "pages": 1,
      "has_next": false,
      "has_prev": false
    }
  }
}

Create New Device

curl -X POST http://localhost:8000/api/v1/devices/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Temperature Sensor",
    "device_id": "TEMP-002",
    "device_type": "sensor",
    "manufacturer": "SensorTech",
    "model": "ST-T2000",
    "firmware_version": "3.0.0",
    "location": "Zone B - Office",
    "status": "online"
  }'

Update Device

curl -X PUT http://localhost:8000/api/v1/devices/1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Temperature Sensor",
    "location": "Zone C - Warehouse",
    "status": "warning"
  }'

Telemetry API Examples

Submit Telemetry Data

curl -X POST http://localhost:8000/api/v1/telemetry/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": 1,
    "metric_name": "temperature",
    "metric_value": 23.5,
    "unit": "°C",
    "timestamp": "2024-01-01T12:00:00Z"
  }'

Get Latest Telemetry

curl -X GET "http://localhost:8000/api/v1/telemetry/latest?device_id=1&metrics=temperature,humidity" \
  -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": {
    "device_id": 1,
    "telemetry": {
      "temperature": {
        "value": 23.5,
        "unit": "°C",
        "timestamp": "2024-01-01T12:00:00Z"
      },
      "humidity": {
        "value": 45.2,
        "unit": "%",
        "timestamp": "2024-01-01T12:00:00Z"
      }
    }
  }
}

Get Historical Data

curl -X GET "http://localhost:8000/api/v1/telemetry/history?device_id=1&metric=temperature&start_time=2024-01-01T00:00:00Z&end_time=2024-01-01T23:59:59Z" \
  -H "Authorization: Bearer <token>"

Alert API Examples

Create Alert

curl -X POST http://localhost:8000/api/v1/alerts/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": 1,
    "title": "High Temperature Alert",
    "description": "Temperature exceeds safe threshold",
    "severity": "warning",
    "alert_type": "threshold",
    "threshold_value": 25.0,
    "actual_value": 26.5,
    "metric_name": "temperature"
  }'

List Active Alerts

curl -X GET "http://localhost:8000/api/v1/alerts/?status=active&severity=warning" \
  -H "Authorization: Bearer <token>"

Acknowledge Alert

curl -X PUT http://localhost:8000/api/v1/alerts/1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "acknowledged",
    "acknowledged_at": "2024-01-01T12:00:00Z",
    "acknowledged_by": "admin"
  }'

Analytics API Examples

System Analytics

curl -X GET http://localhost:8000/api/v1/analytics/system \
  -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": {
    "system_stats": {
      "total_devices": 5,
      "online_devices": 4,
      "offline_devices": 1,
      "error_devices": 0
    },
    "device_performance": [
      {
        "device_id": 1,
        "device_name": "Temperature Sensor Alpha",
        "uptime_percentage": 99.5,
        "data_points_24h": 1440,
        "last_seen": "2024-01-01T12:00:00Z"
      }
    ],
    "telemetry_overview": {
      "total_points": 7200,
      "active_devices": 5,
      "metrics": {
        "temperature": {
          "count": 1440,
          "min": 18.0,
          "max": 28.0,
          "avg": 23.5
        }
      }
    }
  }
}

Generate Report

curl -X POST http://localhost:8000/api/v1/analytics/reports \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "device_performance",
    "date_range": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-01T23:59:59Z"
    },
    "device_ids": [1, 2, 3],
    "format": "json"
  }'

AI API Examples

Get AI Insights

curl -X POST http://localhost:8000/api/v1/ai/insights \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": 1,
    "analysis_type": "performance",
    "time_range": "24h"
  }'

Anomaly Detection

curl -X POST http://localhost:8000/api/v1/ai/anomaly-detection \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": 1,
    "metrics": ["temperature", "humidity"],
    "time_range": "24h",
    "sensitivity": "medium"
  }'

Predictive Maintenance

curl -X POST http://localhost:8000/api/v1/ai/predictive-maintenance \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": 1,
    "prediction_horizon": "7d",
    "include_recommendations": true
  }'

WebSocket API

Connect to WebSocket

const ws = new WebSocket('ws://localhost:8000/ws');

// Authentication
ws.onopen = function() {
  ws.send(JSON.stringify({
    type: 'auth',
    token: 'your-jwt-token'
  }));
};

// Subscribe to device updates
ws.send(JSON.stringify({
  type: 'subscribe',
  channel: 'device_telemetry',
  device_id: 1
}));

// Receive messages
ws.onmessage = function(event) {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

WebSocket Message Formats

Authentication

{
  "type": "auth",
  "token": "jwt-token"
}

Subscription

{
  "type": "subscribe",
  "channel": "device_telemetry",
  "device_id": 1
}

Telemetry Update

{
  "type": "telemetry_update",
  "device_id": 1,
  "metric": "temperature",
  "value": 23.5,
  "unit": "°C",
  "timestamp": "2024-01-01T12:00:00Z"
}

Alert Notification

{
  "type": "alert",
  "alert_id": 123,
  "device_id": 1,
  "severity": "warning",
  "title": "High Temperature",
  "message": "Temperature exceeds threshold",
  "timestamp": "2024-01-01T12:00:00Z"
}

Error Handling

HTTP Status Codes

  • 200 OK - Request successful
  • 201 Created - Resource created
  • 400 Bad Request - Invalid request data
  • 401 Unauthorized - Authentication required
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 422 Unprocessable Entity - Validation error
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error

Error Codes

  • VALIDATION_ERROR - Input validation failed
  • AUTHENTICATION_ERROR - Authentication failed
  • AUTHORIZATION_ERROR - Insufficient permissions
  • RESOURCE_NOT_FOUND - Resource not found
  • RATE_LIMIT_EXCEEDED - Rate limit exceeded
  • INTERNAL_ERROR - Internal server error
  • EXTERNAL_SERVICE_ERROR - External service error

Rate Limiting

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Rate Limit Response

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 100,
      "reset_time": "2024-01-01T12:00:00Z"
    }
  }
}

API Versioning

Version Strategy

  • URL Versioning: /api/v1/, /api/v2/
  • Semantic Versioning: MAJOR.MINOR.PATCH
  • Backward Compatibility: Maintain compatibility for previous versions
  • Deprecation Notice: 6-month deprecation notice

Version Information

curl -X GET http://localhost:8000/api/v1/version

Response

{
  "success": true,
  "data": {
    "version": "1.0.0",
    "api_version": "v1",
    "build_date": "2024-01-01T12:00:00Z",
    "git_commit": "abc123def456",
    "supported_versions": ["v1"],
    "deprecated_versions": []
  }
}

OpenAPI Documentation

Interactive Documentation

  • Swagger UI: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc
  • OpenAPI JSON: http://localhost:8000/openapi.json

Download API Spec

curl -X GET http://localhost:8000/openapi.json > valtronics-api.json

Testing the API

Health Check

curl -X GET http://localhost:8000/api/v1/health/

Test Authentication

# Login
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "password"}'

# Use token
curl -X GET http://localhost:8000/api/v1/devices/ \
  -H "Authorization: Bearer <token>"

Test Device Operations

# Create device
curl -X POST http://localhost:8000/api/v1/devices/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Device", "device_id": "TEST-001", "device_type": "sensor"}'

# List devices
curl -X GET http://localhost:8000/api/v1/devices/ \
  -H "Authorization: Bearer <token>"

# Get device details
curl -X GET http://localhost:8000/api/v1/devices/1 \
  -H "Authorization: Bearer <token>"

SDKs and Libraries

Python SDK

from valtronics_client import ValtronicsClient

client = ValtronicsClient(
    base_url="http://localhost:8000",
    api_key="your-api-key"
)

# List devices
devices = client.devices.list()

# Create device
device = client.devices.create({
    "name": "New Device",
    "device_id": "DEV-001",
    "device_type": "sensor"
})

JavaScript SDK

import { ValtronicsClient } from 'valtronics-js';

const client = new ValtronicsClient({
  baseURL: 'http://localhost:8000',
  apiKey: 'your-api-key'
});

// List devices
const devices = await client.devices.list();

// Create device
const device = await client.devices.create({
  name: 'New Device',
  device_id: 'DEV-001',
  device_type: 'sensor'
});

Best Practices

Authentication

  • Use HTTPS for all API calls
  • Store tokens securely
  • Implement token refresh
  • Use short-lived tokens

Error Handling

  • Check HTTP status codes
  • Parse error responses
  • Implement retry logic
  • Handle rate limits gracefully

Performance

  • Use pagination for large datasets
  • Cache frequently accessed data
  • Use WebSocket for real-time updates
  • Optimize query parameters

Security

  • Validate input data
  • Sanitize user input
  • Implement proper authorization
  • Monitor API usage

Support

Documentation

Support Channels

© 2024 Software Customs Auto Bot Solution. All Rights Reserved.
Valtronics API Overview v1.0

Clone this wiki locally