API Documentation

Bearer Token Authentication

All API endpoints require a valid bearer token in the Authorization header.

Sensor Management

• GET /api/sensors
  List all registered sensors
• GET /api/sensors/{sensor_id}
  Get detailed information about a specific sensor
• POST /api/command/{sensor_id}
  Send command to a specific sensor
• GET /api/sensors/{id}/df
  DF station status and configuration for a specific sensor
• POST /api/sensors/{id}/df/calibrate
  Trigger remote DF calibration on a DF-equipped sensor
• GET /api/bearings/recent
  Recent DF bearing measurements from all DF stations
• GET /api/bearings/intersections
  Recent DF bearing intersection positions (computed from 2+ stations)

Detection Data

• GET /api/detections
  Recent raw detections from all sensors
• GET /api/detections?sensor_id={id}&start={timestamp}&end={timestamp}
  Filtered detections with optional parameters
• GET /api/fused
  Fused multi-sensor detections with position estimates
• GET /api/targets
  Active tracked targets with latest position

Fused Detections & History

• GET /api/fused/history
  Historical fused detections with time range filtering and CSV export

Swarm Detection

• GET /api/swarms
  Active swarm events with formation geometry and threat escalation status

MGRS & Protected Zones

• GET /api/zones
  List all MGRS protected zones
• POST /api/zones
  Add a protected zone (MGRS designator, name, priority level)
• DELETE /api/zones/{mgrs}
  Remove a protected zone by MGRS designator
• POST /api/zones/check
  Check a lat/lon position against all defined zones
• POST /api/mgrs/convert
  Convert between lat/lon and MGRS coordinates
• POST /api/mgrs/grid
  Get MGRS cell boundaries for a map viewport

Threat Intelligence Export

• GET /api/export/stix
  Export detections as STIX 2.1 bundle
• GET /api/export/stix/indicators
  Export STIX 2.1 indicators for known drone signatures

Map Configuration

• GET /api/map/config
  Get map configuration (center, zoom, layers)
• GET /api/map/markers
  Get map markers for threat positions

System Health

• GET /health
  System health status (JSON)
• GET /health/live
  Liveness probe for container orchestration
• GET /health/ready
  Readiness probe for traffic routing

Metrics

• GET /metrics
  Prometheus metrics endpoint

Real-time Detection Stream

Real-time stream of detection events as JSON objects.

Connection Example

const ws = new WebSocket('wss://varta-max.example.com/ws/detections');

ws.onmessage = (event) => {
    const detection = JSON.parse(event.data);
    console.log('Detection:', detection);
    // detection contains: threat_type, threat_level, frequencies, 
    // confidence, approach_vector, provenance, etc.
};

Detection Event Schema

{
    "timestamp": "2026-01-30T16:00:00Z",
    "sensor_id": "PRO-ALPHA-01",
    "threat_type": "LANCET",
    "threat_level": 4,
    "frequencies": [868500000, 902500000],
    "confidence": 0.85,
    "modulation": "LoRa CSS",
    "hop_rate_hz": 50,
    "bandwidth_hz": 500000,
    "approach_vector": "approaching",
    "provenance": {
        "signature_db_version": "v2.0",
        "band_config_version": "v2.0",
        "analyzer_version": "v2.0",
        "sensor_firmware_hash": "abc123..."
    }
}

Sensor Status Topics

• varta/sensors/{sensor_id}/status QoS 0
  Online/offline/degraded status
• varta/sensors/{sensor_id}/heartbeat QoS 0
  Health metrics (CPU, memory, temperature)

Detection Topics

• varta/sensors/{sensor_id}/detections QoS 1
  Detection events (at-least-once delivery)
• varta/threats/raw QoS 0
  Raw detections from all sensors
• varta/threats/fused QoS 1
  Correlated multi-sensor detections
• varta/threats/alerts QoS 2
  High-priority alerts (exactly-once delivery)

Command Topics

• varta/commands/{sensor_id}/ QoS 1
  Sensor-specific commands
• varta/commands/broadcast QoS 1
  Commands to all sensors

System Topics

• varta/system/config QoS 1
  Config updates (signed, verified)
• varta/system/status QoS 1
  System health status

Transport Layer Security

• TLS 1.3: All MQTT, WebSocket, REST connections
• mTLS: Sensor-to-Max mutual certificate authentication
• CURVE: ZeroMQ command channel encryption

Data at Rest

• SQLCipher: AES-256-CBC encryption for edge databases (Mini/Pro)
• TimescaleDB: PostgreSQL encryption extensions (Max)

Configuration Security

• Signed configs: HMAC-SHA256 or Ed25519 signatures on drone_bands.yaml, threat_patterns.json
• Last-known-good rollback: LKG store on integrity failure
• Key rotation: Revocation lists, graceful key expiry

Access Control

• MQTT ACLs: Topic-level permissions per sensor ID
• API authentication: Bearer tokens, rate limiting
• Sensor registration: Certificate-based enrollment

API Rate Limits

• REST API: 100 requests/minute per token
• WebSocket: 10 messages/second per connection
• MQTT: 100 messages/second per topic

HTTP Status Codes

• 200 OK: Request successful
• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Missing or invalid authentication
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource does not exist
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error

Error Response Format

{
    "error": {
        "code": "SENSOR_NOT_FOUND",
        "message": "Sensor with ID 'PRO-ALPHA-01' not found",
        "details": {
            "sensor_id": "PRO-ALPHA-01"
        }
    }
}

Python Example

import requests
import json

# Get all sensors
response = requests.get(
    'https://varta-max.example.com/api/sensors',
    headers={'Authorization': 'Bearer YOUR_TOKEN'}
)
sensors = response.json()

# Get recent detections
response = requests.get(
    'https://varta-max.example.com/api/detections',
    headers={'Authorization': 'Bearer YOUR_TOKEN'}
)
detections = response.json()

# Send command to sensor
command = {
    'command': 'start_scan',
    'parameters': {'bands': ['2G4', '5G8']}
}
response = requests.post(
    f'https://varta-max.example.com/api/command/{sensor_id}',
    headers={'Authorization': 'Bearer YOUR_TOKEN'},
    json=command
)

JavaScript/Node.js Example

const axios = require('axios');

// Get all sensors
const response = await axios.get('https://varta-max.example.com/api/sensors', {
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
    }
});
const sensors = response.data;

// WebSocket connection
const ws = new WebSocket('wss://varta-max.example.com/ws/detections');

ws.onmessage = (event) => {
    const detection = JSON.parse(event.data);
    console.log('New detection:', detection);
    
    // Handle detection
    if (detection.threat_level >= 4) {
        // High threat - trigger alert
        alert(`High threat detected: ${detection.threat_type}`);
    }
};

MQTT Integration Example

import paho.mqtt.client as mqtt

# Create MQTT client
client = mqtt.Client(
    client_id="integration_client",
    transport="websockets",
    port=443
)

# Connect with TLS and mTLS
client.tls_set_context(
    ca_certs="/path/to/ca.crt",
    certfile="/path/to/client.crt",
    keyfile="/path/to/client.key"
)

# Subscribe to detections
def on_connect(client, userdata, flags, rc):
    client.subscribe("varta/threats/fused", qos=1)
    client.subscribe("varta/threats/alerts", qos=2)

def on_message(client, userdata, msg):
    detection = json.loads(msg.payload)
    print(f"Detection: {detection['threat_type']} - Confidence: {detection['confidence']}")
    
    # Handle high-priority alerts
    if msg.topic == "varta/threats/alerts":
        # Trigger immediate response
        handle_alert(detection)

client.connect("varta-max.example.com", 60)
client.loop_forever()

Documentation

• Documentation Hub
• Features & Capabilities
• Technical Deep Dive
• System Architecture
• Drone Database
• Product Roadmap

Contact

For API access and integration support:

• Email: team@varta-systems.com
• GitHub: https://github.com/mattpainter701/Varta_Platform