{ "openapi": "3.1.0", "info": { "title": "ProxyCheck.app free proxy list API", "version": "0.1.0", "summary": "Keyless read-only API for the verified free proxy list.", "description": "The free proxy list of ProxyCheck.app: verified public HTTP, HTTPS, SOCKS4 and SOCKS5 proxies, their counts by protocol and country, and exports as TXT, CSV or JSON. No API key or account is needed; requests are rate-limited per client IP (429 when exceeded). Generated from docs/openapi.yaml." }, "servers": [ { "url": "https://proxycheck.app/api", "description": "Production; requests go to https://proxycheck.app/api/v1/..." } ], "security": [], "tags": [ { "name": "PublicProxies" } ], "externalDocs": { "description": "API documentation", "url": "https://proxycheck.app/docs/api" }, "paths": { "/v1/public-proxies": { "get": { "tags": [ "PublicProxies" ], "summary": "List verified public proxies (snapshot)", "security": [], "parameters": [ { "in": "query", "name": "protocol", "description": "Case-insensitive (HTTP = http); any other value returns 400.", "schema": { "type": "string", "enum": [ "http", "https", "socks4", "socks5" ] } }, { "in": "query", "name": "country", "description": "ISO 3166-1 alpha-2 code in any case (us matches the stored US). Any value that is not two ASCII letters returns 400.", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" } }, { "in": "query", "name": "anonymity", "description": "Reported anonymity. HTTP/HTTPS is elite for HTTPS traffic (checked only through an HTTPS CONNECT tunnel, where a proxy cannot add headers; plain-HTTP behaviour is not measured); SOCKS4/SOCKS5 is elite. transparent and anonymous match nothing.", "schema": { "type": "string", "enum": [ "transparent", "anonymous", "elite", "unknown" ] } }, { "in": "query", "name": "fresh_minutes", "description": "Out-of-range values fall back to 1440.", "schema": { "type": "integer", "minimum": 1, "maximum": 1440, "default": 1440 } }, { "in": "query", "name": "max_latency_ms", "description": "Maximum latency (ttfb_ms) in ms", "schema": { "type": "integer", "minimum": 0 } }, { "in": "query", "name": "min_uptime", "description": "Minimum uptime as a percentage 0-100 (100 matches >= 99.5%)", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "in": "query", "name": "proxy", "description": "Substring match on proxy_norm or exit IP; bypasses the cache", "schema": { "type": "string" } }, { "in": "query", "name": "quality", "description": "Quality gate. Omitted uses the server default (full when PUBLIC_REQUIRE_QUALITY=true, as in production, otherwise quick); none disables it.", "schema": { "type": "string", "enum": [ "full", "quick", "none" ] } }, { "in": "query", "name": "sort", "description": "uptime is an alias of uptime_desc; unknown values sort by checked_desc", "schema": { "type": "string", "enum": [ "checked_desc", "checked_asc", "latency_asc", "latency_desc", "uptime_desc", "uptime_asc", "uptime" ], "default": "checked_desc" } }, { "in": "query", "name": "page", "description": "Pages past 1000 are served as page 1000.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 } }, { "in": "query", "name": "limit", "description": "Values outside 1-200 fall back to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicProxiesResponse" } } } }, "400": { "description": "Invalid protocol or country" }, "429": { "description": "Rate limited" } } } }, "/v1/public-proxies/stats": { "get": { "tags": [ "PublicProxies" ], "summary": "Count live public proxies by protocol and anonymity (rate-limited, cached 30s)", "security": [], "parameters": [ { "in": "query", "name": "protocol", "description": "Case-insensitive (HTTP = http); any other value returns 400.", "schema": { "type": "string", "enum": [ "http", "https", "socks4", "socks5" ] } }, { "in": "query", "name": "country", "description": "ISO 3166-1 alpha-2 code in any case (us matches the stored US). Any value that is not two ASCII letters returns 400.", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" } }, { "in": "query", "name": "anonymity", "description": "Reported anonymity. HTTP/HTTPS is elite for HTTPS traffic (checked only through an HTTPS CONNECT tunnel, where a proxy cannot add headers; plain-HTTP behaviour is not measured); SOCKS4/SOCKS5 is elite. transparent and anonymous match nothing.", "schema": { "type": "string", "enum": [ "transparent", "anonymous", "elite", "unknown" ] } }, { "in": "query", "name": "fresh_minutes", "description": "Out-of-range values fall back to 1440.", "schema": { "type": "integer", "minimum": 1, "maximum": 1440, "default": 1440 } }, { "in": "query", "name": "max_latency_ms", "description": "Maximum latency (ttfb_ms) in ms", "schema": { "type": "integer", "minimum": 0 } }, { "in": "query", "name": "min_uptime", "description": "Minimum uptime as a percentage 0-100 (100 matches >= 99.5%)", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "in": "query", "name": "proxy", "description": "Substring match on proxy_norm or exit IP; bypasses the cache", "schema": { "type": "string" } }, { "in": "query", "name": "quality", "description": "Quality gate. Omitted uses the server default (full when PUBLIC_REQUIRE_QUALITY=true, as in production, otherwise quick); none disables it.", "schema": { "type": "string", "enum": [ "full", "quick", "none" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicProxiesStatsResponse" } } } }, "400": { "description": "Invalid protocol or country" }, "429": { "description": "Rate limited" } } } }, "/v1/public-proxies/countries": { "get": { "tags": [ "PublicProxies" ], "summary": "Countries with live public proxies, by count (rate-limited, cached 30s)", "security": [], "parameters": [ { "in": "query", "name": "fresh_minutes", "description": "Out-of-range values fall back to 1440.", "schema": { "type": "integer", "minimum": 1, "maximum": 1440, "default": 1440 } } ], "responses": { "200": { "description": "Every country with at least one live proxy checked within fresh_minutes, sorted by total descending. No quality gate is applied (every live proxy currently passes it); countries and stats are computed and cached (30 s) separately, so their totals can differ by a few rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCountriesResponse" } } } }, "429": { "description": "Rate limited" } } } }, "/v1/public-proxies/export": { "get": { "tags": [ "PublicProxies" ], "summary": "Export verified public proxies (rate-limited)", "security": [], "parameters": [ { "in": "query", "name": "format", "schema": { "type": "string", "enum": [ "txt", "csv", "json" ], "default": "txt" } }, { "in": "query", "name": "protocol", "description": "Case-insensitive (HTTP = http); any other value returns 400.", "schema": { "type": "string", "enum": [ "http", "https", "socks4", "socks5" ] } }, { "in": "query", "name": "country", "description": "ISO 3166-1 alpha-2 code in any case (us matches the stored US). Any value that is not two ASCII letters returns 400.", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" } }, { "in": "query", "name": "anonymity", "description": "Reported anonymity. HTTP/HTTPS is elite for HTTPS traffic (checked only through an HTTPS CONNECT tunnel, where a proxy cannot add headers; plain-HTTP behaviour is not measured); SOCKS4/SOCKS5 is elite. transparent and anonymous match nothing.", "schema": { "type": "string", "enum": [ "transparent", "anonymous", "elite", "unknown" ] } }, { "in": "query", "name": "fresh_minutes", "description": "Only proxies checked within N minutes. Clamped like the list and stats: out-of-range values (0 and negatives included) fall back to 1440.", "schema": { "type": "integer", "minimum": 1, "maximum": 1440, "default": 1440 } }, { "in": "query", "name": "max_latency_ms", "description": "Maximum latency (ttfb_ms) in ms", "schema": { "type": "integer", "minimum": 0 } }, { "in": "query", "name": "min_uptime", "description": "Minimum uptime as a percentage 0-100 (100 matches >= 99.5%)", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "in": "query", "name": "proxy", "description": "Substring match on proxy_norm or exit IP; bypasses the cache", "schema": { "type": "string" } }, { "in": "query", "name": "quality", "description": "Quality gate. Omitted uses the server default (full when PUBLIC_REQUIRE_QUALITY=true, as in production, otherwise quick); none disables it.", "schema": { "type": "string", "enum": [ "full", "quick", "none" ] } }, { "in": "query", "name": "max_rows", "description": "Rows to export, newest check first. Larger values, values below 1 and non-numbers use the cap (RL_PUBLIC_EXPORT_MAX_ROWS, 500 in production).", "schema": { "type": "integer", "minimum": 1, "default": 500, "maximum": 500 } } ], "responses": { "200": { "description": "Export. txt lists one proxy URL per line, each once; in csv the proxy column is the URL to connect to. Both write https-labelled proxies as http://host:port (HTTP proxies that tunnel HTTPS via CONNECT). json items keep proxy_norm.", "content": { "text/plain": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicProxy" } } } } }, "400": { "description": "Invalid format, protocol or country" }, "429": { "description": "Rate limited" } } } } }, "components": { "schemas": { "PublicCountriesResponse": { "type": "object", "required": [ "countries" ], "properties": { "countries": { "type": "array", "items": { "type": "object", "required": [ "code", "total" ], "properties": { "code": { "type": "string", "description": "ISO 3166-1 alpha-2 country code" }, "total": { "type": "integer" }, "protocols": { "type": "object", "description": "Live proxies per protocol (http, https, socks4, socks5; every key present)", "additionalProperties": { "type": "integer" } } } } } } }, "PublicProxiesResponse": { "type": "object", "required": [ "page", "limit", "total", "items", "refreshed_at" ], "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "refreshed_at": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicProxy" } } } }, "PublicProxiesStatsResponse": { "type": "object", "required": [ "total", "protocols", "anonymity" ], "properties": { "total": { "type": "integer" }, "protocols": { "type": "object", "required": [ "http", "https", "socks4", "socks5" ], "properties": { "http": { "type": "integer" }, "https": { "type": "integer" }, "socks4": { "type": "integer" }, "socks5": { "type": "integer" } } }, "anonymity": { "type": "object", "description": "Counts by reported anonymity. HTTP/HTTPS rows count as elite (elite for HTTPS traffic); unknown = total - transparent - anonymous - elite.", "required": [ "transparent", "anonymous", "elite" ], "properties": { "transparent": { "type": "integer" }, "anonymous": { "type": "integer" }, "elite": { "type": "integer" } } } } }, "PublicProxy": { "type": "object", "description": "One proxy of the public pool (handlers.PublicProxyResponse).", "required": [ "proxy_norm", "status", "protocol", "anonymity", "checked_at", "uptime_score" ], "properties": { "proxy_norm": { "type": "string", "description": "Canonical identity, protocol://host:port. A proxy with protocol https is an HTTP CONNECT proxy: connect to it as http://host:port." }, "status": { "type": "string", "description": "live for every row the list returns" }, "protocol": { "type": "string", "enum": [ "http", "https", "socks4", "socks5" ] }, "connect_ms": { "type": [ "integer", "null" ], "description": "Tunnel time: ms until the proxy opened the tunnel (CONNECT answered or SOCKS handshake done). Never larger than ttfb_ms." }, "ttfb_ms": { "type": [ "integer", "null" ], "description": "The latency: ms from sending the request through the proxy to the first byte of the response. max_latency_ms and the latency sorts use it." }, "exit_ip": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "description": "Two-letter ISO code" }, "city": { "type": [ "string", "null" ], "description": "List only; the json export leaves it out" }, "asn": { "type": [ "string", "null" ], "description": "AS" }, "anonymity": { "type": "string", "enum": [ "transparent", "anonymous", "elite", "unknown" ], "description": "http and https proxies are reported elite (an HTTPS tunnel cannot carry proxy-added headers); SOCKS proxies keep their measured label" }, "checked_at": { "type": "string", "format": "date-time" }, "uptime_score": { "type": "number", "minimum": 0, "maximum": 1 } } } } } }