{
  "components": {
    "schemas": {
      "Error": {
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ],
        "type": "object"
      },
      "PoolSummary": {
        "properties": {
          "asOf": {
            "format": "date-time",
            "type": "string"
          },
          "endpoints": {
            "minimum": 0,
            "type": "integer"
          },
          "latestValidation": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "protocols": {
            "items": {
              "properties": {
                "endpoints": {
                  "type": "integer"
                },
                "protocol": {
                  "type": "string"
                },
                "uniqueIPs": {
                  "type": "integer"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "uniqueIPs": {
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "asOf",
          "endpoints",
          "uniqueIPs",
          "protocols"
        ],
        "type": "object"
      },
      "Proxy": {
        "properties": {
          "capabilities": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "format": "int64",
            "type": "integer"
          },
          "ip": {
            "type": "string"
          },
          "port": {
            "type": "string"
          },
          "protocol": {
            "enum": [
              "http",
              "socks4",
              "socks5"
            ],
            "type": "string"
          },
          "proxy": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "sources": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "validated_at": {
            "format": "date-time",
            "type": "string"
          },
          "validation_latency_ms": {
            "minimum": 0,
            "type": "integer"
          },
          "validation_status": {
            "type": "integer"
          },
          "verified": {
            "type": "boolean"
          }
        },
        "required": [
          "protocol",
          "ip",
          "port",
          "proxy",
          "verified",
          "validated_at",
          "expires_at"
        ],
        "type": "object"
      },
      "ProxyList": {
        "properties": {
          "count": {
            "minimum": 0,
            "type": "integer"
          },
          "generatedAt": {
            "format": "date-time",
            "type": "string"
          },
          "health": {
            "type": "string"
          },
          "proxies": {
            "items": {
              "$ref": "#/components/schemas/Proxy"
            },
            "type": "array"
          },
          "snapshotVersion": {
            "type": "string"
          },
          "validUntil": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "snapshotVersion",
          "generatedAt",
          "count",
          "proxies"
        ],
        "type": "object"
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "in": "header",
        "name": "X-API-Key",
        "type": "apiKey"
      },
      "BearerAuth": {
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "externalDocs": {
    "description": "API documentation",
    "url": "https://proxylistapi.xyz/docs"
  },
  "info": {
    "description": "Paid access to application-verified public proxy-list metadata. The service returns endpoints and validation timestamps; it does not relay traffic.",
    "title": "FreeProxy API",
    "version": "1.0.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/api/v1/pool-summary": {
      "get": {
        "operationId": "getPoolSummary",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PoolSummary"
                }
              }
            },
            "description": "Current counts grouped by protocol"
          }
        },
        "summary": "Read current public pool aggregates"
      }
    },
    "/api/v1/proxies": {
      "get": {
        "operationId": "listProxies",
        "parameters": [
          {
            "description": "Use https as an alias for HTTP CONNECT-capable records.",
            "in": "query",
            "name": "protocol",
            "schema": {
              "enum": [
                "http",
                "https",
                "socks4",
                "socks5"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 20,
              "maximum": 10000,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProxyList"
                }
              }
            },
            "description": "Verified, unexpired proxy metadata"
          },
          "304": {
            "description": "List snapshot is unchanged for the supplied If-None-Match validator"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing, expired, or inactive API key"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "No matching proxy is currently available"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "summary": "List verified proxy records"
      }
    },
    "/api/v1/proxy": {
      "get": {
        "operationId": "getProxy",
        "parameters": [
          {
            "description": "Use https as an alias for HTTP CONNECT-capable records.",
            "in": "query",
            "name": "protocol",
            "schema": {
              "enum": [
                "http",
                "https",
                "socks4",
                "socks5"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Proxy"
                }
              }
            },
            "description": "Verified, unexpired proxy metadata"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing, expired, or inactive API key"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "No matching proxy is currently available"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "summary": "Get one verified proxy record"
      }
    }
  },
  "servers": [
    {
      "url": "https://proxylistapi.xyz"
    }
  ]
}