OpenVPN-Monitoring-Simple/DOCS/api_v3_endpoints.md

OpenVPN Monitor API v3 Documentation

This API provides access to OpenVPN monitoring data, including real-time client status and historical data stored in a Time Series Database (TSDB). It features optimized aggregation for fast visualization.

Base URL: http://<your-server-ip>:5001/api/v1

---

1. Global Analytics (Dashboard)

Provides aggregated trend data for the entire server. optimized for visualization with exactly 96 data points regardless of the time range.

GET /analytics

Query Parameters

Parameter	Type	Default	Description
range	string	24h	Time range. Supported: 24h, 7d, 30d.

Behavior

• 24h: Returns 15-minute intervals.
• 7d: Returns 105-minute intervals (1h 45m).
• 30d: Returns 450-minute intervals (7h 30m).
• Zero-Filling: Missing data periods are automatically filled with zeros to ensure graph continuity.

Example Response

{
  "success": true,
  "timestamp": "2026-01-09 12:00:00",
  "range": "24h",
  "data": {
    "global_history_24h": [
      {
        "timestamp": "2026-01-09 11:45:00",
        "total_rx": 102400,
        "total_tx": 51200,
        "active_count": 5
      },
      ...
    ],
    "max_concurrent_24h": 12,
    "top_clients_24h": [ ... ],
    "traffic_distribution": { "rx": 1000, "tx": 500 }
  }
}

---

2. Client Statistics (Detail + History)

Main endpoint for individual client reports. Supports Dynamic Aggregation to optimize payload size (~98% reduction for 24h view).

GET /stats/<common_name>

Query Parameters

Parameter	Type	Default	Description
range	string	24h	Time range. Formats: 1h, 3h, 6h, 12h, 24h, 7d, 30d.
resolution	string	auto	Force resolution (optional): raw, 5min, hourly, auto.

Dynamic Aggregation Logic (resolution=auto)

The API automatically selects the aggregation interval based on the requested range to balance detail and performance:

Range	Resolution	Points	Source Table
1h	30 sec	120	usage_history (Raw)
3h	1 min	180	usage_history (Raw)
6h	2 min	180	usage_history (Raw)
12h	5 min	144	usage_history (Raw)
24h	15 min	96	usage_history (Raw)
7d	1 Hour	168	stats_hourly
30d	6 Hours	120	stats_6h

All short-term ranges (≤24h) include automatic Zero-Filling.

Examples: Long-Term Aggregated Data

To explicitly request data from long-term storage tables (skipping raw data), use the resolution parameter or specific ranges.

1. Last 7 Days (Hourly Resolution) Uses stats_hourly table. Reduced precision for weekly trends.

GET /api/v1/stats/user-alice?range=7d

or explicit resolution:

GET /api/v1/stats/user-alice?range=7d&resolution=hourly

2. Last 30 Days (6-Hour Resolution) Uses stats_6h table. Ideal for monthly volume analysis.

GET /api/v1/stats/user-alice?range=30d

3. Last 1 Year (Daily Resolution) Uses stats_daily table. Extremely lightweight for annual reporting.

GET /api/v1/stats/user-alice?range=1y&resolution=daily

Example Response

{
  "success": true,
  "data": {
    "common_name": "user-alice",
    "status": "Active",
    "current_rates": { "recv_mbps": 1.5, "sent_mbps": 0.2 },
    "totals": { "received_mb": 500.25, "sent_mb": 120.10 },
    "history": [
      {
        "timestamp": "2026-01-09 11:30:00",
        "bytes_received": 5000,
        "bytes_sent": 2000,
        "bytes_received_rate_mbps": 0.5,
        "bytes_sent_rate_mbps": 0.1
      },
      ...
    ],
    "meta": {
      "resolution_used": "usage_history_hires",
      "record_count": 120
    }
  }
}

---

3. Current Statistics (All Clients)

Returns a snapshot of all known clients.

GET /stats

Example Response

{
  "success": true,
  "count": 2,
  "data": [
    {
      "common_name": "user-alice",
      "status": "Active",
      "current_recv_rate_mbps": 1.5,
      "total_received_mb": 500.2
    },
    ...
  ]
}

---

4. System Statistics

Aggregated metrics for the Server.

GET /stats/system

Example Response

{
  "success": true,
  "data": {
    "total_clients": 15,
    "active_clients": 3,
    "total_received_gb": 10.0,
    "total_sent_gb": 5.0
  }
}

---

5. Certificates

SSL Certificate expiration tracking.

GET /certificates

Example Response

{
  "success": true,
  "data": [
    {
      "file": "user-alice.crt",
      "days_remaining": "360 days",
      "is_expired": false
    }
  ]
}

---

6. Utility Methods

GET /clients

Simple list of clients (Common Name + Status) for UI dropdowns.

GET /health

Database connectivity check. Returns {"status": "healthy"}.