{ "openapi": "3.1.0", "info": { "title": "Litport API", "version": "1.0.0", "description": "Public free-proxy retrieval and read-only authenticated account operations. No endpoint creates proxy tokens." }, "servers": [ { "url": "https://litport.net" } ], "paths": { "/api/free-proxy": { "get": { "operationId": "listFreeProxies", "summary": "List public free proxies", "description": "Returns a bare array. Invalid numeric and sort inputs currently fall back to defaults instead of returning 400.", "security": [], "parameters": [ { "name": "country", "in": "query", "required": false, "description": "Case-insensitive ISO-2 code. The value is uppercased; no aliases are applied.", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "limit", "in": "query", "required": false, "description": "Accepted range 10–1000. Invalid or out-of-range values are ignored.", "schema": { "type": "integer", "minimum": 10, "maximum": 1000, "default": 50 } }, { "name": "page", "in": "query", "required": false, "description": "Accepted range 1–1000. Invalid or out-of-range values are ignored.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 } }, { "name": "sortBy", "in": "query", "required": false, "description": "Field: pingAt, responseTimeMs, or createdAt. Direction: asc or desc. Invalid values are ignored.", "schema": { "type": "string", "enum": [ "pingAt_asc", "pingAt_desc", "responseTimeMs_asc", "responseTimeMs_desc", "createdAt_asc", "createdAt_desc" ] } }, { "name": "anonymityLevel", "in": "query", "required": false, "description": "Exact filter. Unknown values usually return an empty array.", "schema": { "type": "string" } }, { "name": "protocol", "in": "query", "required": false, "description": "Exact filter such as http, https, or socks5. Unknown values usually return an empty array.", "schema": { "type": "string" } }, { "name": "uptimeRating", "in": "query", "required": false, "description": "Minimum 24-hour uptime percentage, 1–100. Invalid values are ignored.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "responseTimeMs", "in": "query", "required": false, "description": "Maximum HTTP response time in milliseconds, 1–10000. Invalid values are ignored.", "schema": { "type": "integer", "minimum": 1, "maximum": 10000 } }, { "name": "format", "in": "query", "required": false, "description": "json, csv, txt, or txt-proto. Unknown values fall back to JSON.", "schema": { "type": "string", "enum": [ "json", "csv", "txt", "txt-proto" ], "default": "json" } }, { "name": "download", "in": "query", "required": false, "description": "When present for a supported format, returns an attachment.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Free proxies in the requested format.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FreeProxy" } } }, "text/csv": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } } } } }, "/api/v1/tokens": { "get": { "operationId": "listTokens", "summary": "List the caller's existing tokens", "description": "Returns customer-visible metadata for the caller's existing tokens.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "unlimited", "ppg" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "expired", "disabled" ] } } ], "responses": { "200": { "description": "Owned token metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenList" } } } }, "400": { "description": "Request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tokens/{tokenId}/usage": { "get": { "operationId": "getTokenUsage", "summary": "Read usage for one owned token", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "groupBy", "in": "query", "schema": { "type": "string", "enum": [ "hour", "day", "month" ], "default": "day" } }, { "name": "include", "in": "query", "description": "Comma-separated optional expansions. Use `domains` for destinations, or `charges` with a PPG token and `groupBy=hour` for persisted charge components.", "schema": { "type": "string", "example": "domains,charges" } } ], "responses": { "200": { "description": "Customer-visible traffic summary and sparse ascending buckets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "400": { "description": "Request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "lit_", "description": "Account API key created in /users/settings." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "docsUrl" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" }, "docsUrl": { "type": "string", "format": "uri" } } } } }, "FreeProxy": { "type": "object", "properties": { "protocol": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "externalIp": { "type": "string" }, "geoCountry": { "type": "string" }, "geoCountryFlagEmoji": { "type": "string" }, "geoRegion": { "type": "string" }, "geoCity": { "type": "string" }, "geoTimezone": { "type": "string" }, "asn": { "type": "integer" }, "asnOrgName": { "type": "string" }, "anonymityLevel": { "type": "string" }, "anonymityLevelRating": { "type": "integer" }, "responseTimeMs": { "type": "integer" }, "responseTimeRating": { "type": "integer" }, "uptimeRating": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "pingAt": { "type": "string", "format": "date-time" } } }, "Token": { "type": "object", "required": [ "id", "type", "status", "createdAt", "username", "password" ], "example": { "id": 12345, "type": "ppg", "status": "active", "label": "Production crawler", "createdAt": "2026-08-01T10:15:00.000Z", "expiresAt": null, "ingress": { "hub": "example-hub", "protocol": "http", "mode": "request-selected", "supportedProtocols": [ "http", "socks5" ] }, "poolSelection": { "mode": "fixed", "pool": { "authKey": "residential-main", "name": "Residential Main" } }, "username": "proxy-username", "password": "proxy-password" }, "properties": { "id": { "type": "integer" }, "type": { "type": "string", "enum": [ "unlimited", "ppg" ] }, "status": { "type": "string", "enum": [ "active", "expired", "disabled" ] }, "label": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "ingress": { "type": "object", "additionalProperties": true }, "poolSelection": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "auth-parameter", "fixed" ] }, "pool": { "anyOf": [ { "type": "object", "required": [ "authKey", "name" ], "properties": { "authKey": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, "username": { "type": "string" }, "password": { "type": "string" } } }, "TokenList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Token" } }, "page": { "type": "object", "properties": { "nextCursor": { "type": [ "string", "null" ] } } } } }, "UsageTotals": { "type": "object", "properties": { "requests": { "type": "integer" }, "uploadedBytes": { "type": "string", "pattern": "^[0-9]+$" }, "downloadedBytes": { "type": "string", "pattern": "^[0-9]+$" }, "totalBytes": { "type": "string", "pattern": "^[0-9]+$" } } }, "UsageDomainItem": { "type": "object", "properties": { "protocol": { "type": [ "string", "null" ], "enum": [ "tcp", "udp", null ] }, "destination": { "type": "string" }, "port": { "type": [ "integer", "null" ] }, "requests": { "type": "integer" }, "uploadedBytes": { "type": "string", "pattern": "^[0-9]+$" }, "downloadedBytes": { "type": "string", "pattern": "^[0-9]+$" }, "totalBytes": { "type": "string", "pattern": "^[0-9]+$" }, "lastSeenAt": { "type": [ "string", "null" ], "format": "date-time" }, "firstSeenAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "UsageDomainBreakdown": { "type": "object", "properties": { "limit": { "type": "integer", "const": 150 }, "totalDestinationCount": { "type": "integer" }, "displayedCount": { "type": "integer" }, "truncated": { "type": "boolean" }, "range": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "const": "UTC" }, "periodClamped": { "type": "boolean" }, "endClamped": { "type": "boolean" } } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/UsageDomainItem" } }, "other": { "$ref": "#/components/schemas/UsageDomainItem" } } }, "UsageResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tokenId": { "type": "integer" }, "range": { "type": "object" }, "trafficBasis": { "type": "string", "const": "customer_chargeable" }, "summary": { "$ref": "#/components/schemas/UsageTotals" }, "buckets": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/UsageTotals" }, { "type": "object" } ] } }, "domainBreakdown": { "$ref": "#/components/schemas/UsageDomainBreakdown" } } } } } } } }