Public REST API

Modern Speedtest API

Secure, versioned endpoints for external consumers. The public API supports authenticated ISP lookup and profile-aware network analysis with rate limiting and strict input validation.

Base path: /api/v1Auth: x-api-key or Bearer tokenRate limit: configurable per deployment

Back to main

Authentication

API key protection

All public business endpoints require an API key. Configure one or more keys in the server environment through SPEEDTEST_API_KEYS.

SPEEDTEST_API_KEYS=prod_key_1,prod_key_2
SPEEDTEST_API_RATE_LIMIT=60
SPEEDTEST_API_RATE_LIMIT_WINDOW_MS=60000

Security model

What is enforced

Constant-time API key comparison
Per-IP and per-key rate limiting
Strict JSON validation on POST routes
No-store API responses with hardened response headers
Versioned endpoints under /api/v1

Endpoints

Available routes

GET/api/v1/health

Public health check for infrastructure verification.

curl https://your-domain.com/api/v1/health

GET/api/v1/network/identity

Returns the detected public IP and ISP for the caller context.

curl https://your-domain.com/api/v1/network/identity   -H "x-api-key: YOUR_API_KEY"

POST/api/v1/network/analyze

Analyzes measured metrics and returns inferred capability tier, latency quality, and a profile-aware health score.

curl https://your-domain.com/api/v1/network/analyze   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "downloadSpeed": 934.42,
    "uploadSpeed": 612.11,
    "latencyMs": 12.5,
    "jitterMs": 2.1,
    "packetLossPct": 0.0,
    "qualityProfile": "gaming",
    "bestDownloadSpeed": 958.33,
    "bestUploadSpeed": 640.10,
    "isp": "Example Fiber"
  }'

Request body

POST /api/v1/network/analyze

Field	Type	Required	Description
downloadSpeed	number	Yes	Measured download speed in Mbps.
uploadSpeed	number	Yes	Measured upload speed in Mbps.
bestDownloadSpeed	number	No	Best historical download speed in Mbps.
bestUploadSpeed	number	No	Best historical upload speed in Mbps.
latencyMs	number	No	Measured latency in milliseconds.
jitterMs	number	No	Measured jitter in milliseconds.
packetLossPct	number	No	Estimated packet loss percentage (0-100).
qualityProfile	string	No	One of: general, gaming, video-calls, streaming, remote-work. Default: general.
isp	string	No	Optional ISP name supplied by the caller.
timestamp	string	No	Optional ISO timestamp associated with the measurement.

Example response

Successful analysis payload

{
  "data": {
    "input": {
      "downloadSpeed": 934.42,
      "uploadSpeed": 612.11,
      "latencyMs": 12.5,
      "jitterMs": 2.1,
      "packetLossPct": 0,
      "qualityProfile": "gaming",
      "bestDownloadSpeed": 958.33,
      "bestUploadSpeed": 640.1,
      "isp": "Example Fiber",
      "timestamp": null
    },
    "analysis": {
      "observedPeakMbps": 958.33,
      "thresholdMbps": 900,
      "scaleMaxMbps": 10000,
      "tier": "gigabit",
      "supportsGigabit": true,
      "isNearGigabit": false,
      "latencyQuality": "good",
      "health": {
        "score": 96.4,
        "grade": "A",
        "profile": "gaming",
        "latencyQuality": "good",
        "breakdown": {
          "speed": 100,
          "latency": 95.8,
          "jitter": 100,
          "packetLoss": 100
        }
      }
    }
  },
  "meta": {
    "scope": "network-analyze",
    "evaluatedAt": "2026-04-14T00:00:00.000Z"
  }
}