PublicVPNList API v1

Free API & downloads: 24-hour access

Get access here before using the API or downloading a dataset. Your key and download links expire after 24 hours. Return to this page and press the button to get new access; it does not renew automatically.

Checking access…

Protected by Google reCAPTCHA. Google’s Privacy Policy and Terms of Service apply.

For permanent access, tell us your name, email and intended use. Requests are reviewed individually.

Already saved files are not revoked. A configuration may stop working earlier if its third-party server changes. Individual OpenVPN checks still use their existing single-use download token.

Quick start

Use the versioned /api/v1/ paths. Respect 429, apply backoff, cache the ETag, and check both expires_at and each record’s last_checked_at.

curl -H 'Authorization: Bearer YOUR_24_HOUR_KEY' -H 'Accept: application/json' \
  'https://publicvpnlist.com/api/v1/servers?protocol=vless&status=online&sort=last_checked&order=desc&per_page=50'

Result will appear here.

Filters and pagination

Examples

PHP

$url = 'https://publicvpnlist.com/api/v1/servers?country=US&per_page=10';
$context = stream_context_create(['http' => ['header' => "Authorization: Bearer YOUR_24_HOUR_KEY\r\n"]]);
$data = json_decode(file_get_contents($url, false, $context), true);

Python

import requests
r = requests.get('https://publicvpnlist.com/api/v1/servers', params={'country': 'US'}, headers={'Authorization': 'Bearer YOUR_24_HOUR_KEY'}, timeout=15)
r.raise_for_status()
print(r.json()['data'])

JavaScript

const response = await fetch('https://publicvpnlist.com/api/v1/stats', {headers: {Authorization: 'Bearer YOUR_24_HOUR_KEY'}});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const payload = await response.json();

Record fields

HTTP behavior

• Free API limit: 60 requests per minute per short-lived keyed IP hash. The small health endpoint is not tied to the filesystem counter so monitoring remains available during counter-storage failures.
• 401 missing, expired or revoked access key, 400 invalid parameter, 404 unknown endpoint/record, 405 method, 429 rate limit, 500 safe internal error.
• Use ETag or Last-Modified; unchanged GET/HEAD requests return 304.
• CORS allows GET/HEAD with an Authorization Bearer key; OPTIONS does not require a key. Authenticated responses use private, no-store caching. Duplicate query parameters are rejected.
• Technical quality score is not a privacy, identity or trust assessment.

See the exact machine-readable contract in OpenAPI JSON and stable files on the exports page.

Changelog and migration policy

Access policy — September 18, 2026: API requests and every export require a free 24-hour key issued after Google reCAPTCHA. Previous anonymous integrations must obtain a key on this website and send it as a Bearer header. Permanent personal keys are available only after individual review. Legacy routes follow the same access policy.

v1.3 — September 18, 2026: protocol-specific countries, statistics, lifecycle and health; JSON/CSV/TXT/XML exports for every published protocol; downloads share the API generation. URI-protocol latency and tunnel RTT now use the measured HTTPS round trip, with null for missing measurements. Handshake and first-byte fields retain their separate meanings.

v1.2 — August 31, 2026: additive protocol filters, compact checked snapshots, current config download URLs and dedicated documentation for VLESS, Trojan, VMess, Shadowsocks, Hysteria2, TUIC, WireGuard and IKEv2. The no-filter default remains OpenVPN.

v1.1 — July 28, 2026: source-reported and PublicVPNList-measured fields are separate; health exposes snapshot age and generator state and remains independent of counter storage.

v1.0 — July 28, 2026: stable public IDs, strict filters, pagination, conditional caching, rate-limit headers and snapshot exports.

The earlier multiprotocol preview remains temporarily available on its old specialist routes and with ?legacy=1 for list routes. New integrations should use the documented dataset response; legacy compatibility may be retired only after a published migration window.

Breaking changes require a new versioned path. Additive fields may appear in v1; integrations should ignore unknown fields. A deprecated major version will be documented before removal.

Acceptable use: cache results, avoid scraping HTML, do not use the service to conceal abuse, and report unwanted or incorrect endpoint listings through contact/takedown.