{
  "openapi": "3.0.3",
  "info": {
    "title": "EProxies Public API",
    "description": "Public API for EProxies residential proxies (eproxies.io). Covers whitelist-mode proxy extraction and whitelist management.\n\nProxy gateway (not part of this HTTP API): `proxy.eproxies.net:23333` — HTTP/HTTPS/SOCKS5 on the same port, credential-mode username syntax `{account}-pool-flow[-region-{CC}][-state-{State}][-city-{city}][-asn-{ASN}][-sid-{8chars}-ttl-{1-120}]`.\n\nNote: `/gateway_api/extract_ip` must be called from an IP that is already on your whitelist. Management endpoints authenticate with `userName` + `userKeyValue` (user key, available in the dashboard).",
    "version": "1.0.0",
    "contact": {
      "email": "support@eproxies.io",
      "url": "https://www.eproxies.io/company/contact"
    }
  },
  "servers": [
    { "url": "https://api.eproxies.net", "description": "Production" }
  ],
  "tags": [
    { "name": "extraction", "description": "Whitelist-mode proxy extraction" },
    { "name": "whitelist", "description": "Whitelist management (userName + userKeyValue auth)" }
  ],
  "paths": {
    "/gateway_api/extract_ip": {
      "get": {
        "tags": ["extraction"],
        "summary": "Extract proxy endpoints",
        "description": "Returns a batch of `IP:port` proxy endpoints for direct, credential-free use. The request must originate from a whitelisted IP.",
        "operationId": "extractIp",
        "parameters": [
          { "name": "count", "in": "query", "required": true, "description": "Number of proxies to extract", "schema": { "type": "integer", "minimum": 1 }, "example": 10 },
          { "name": "country", "in": "query", "required": false, "description": "ISO 3166-1 alpha-2 country code, or `Global` for any country", "schema": { "type": "string" }, "example": "US" },
          { "name": "protocol", "in": "query", "required": false, "description": "Proxy protocol", "schema": { "type": "string", "enum": ["http", "socks5"] }, "example": "http" },
          { "name": "format", "in": "query", "required": false, "description": "Response format", "schema": { "type": "string", "enum": ["txt", "json"] }, "example": "json" },
          { "name": "separator", "in": "query", "required": false, "description": "Line separator for `txt` format: `crlf` = \\r\\n, `br` = </br>, `cr` = \\r, `lf` = \\n, `tab` = \\t", "schema": { "type": "string", "enum": ["crlf", "br", "cr", "lf", "tab"] }, "example": "crlf" },
          { "name": "st", "in": "query", "required": false, "description": "Custom separator string (alternative to `separator`)", "schema": { "type": "string" } },
          { "name": "session", "in": "query", "required": false, "description": "IP session type: `sticky` reuses the same batch of IPs, `random` returns random IPs", "schema": { "type": "string", "enum": ["sticky", "random"] }, "example": "sticky" }
        ],
        "responses": {
          "200": {
            "description": "Extracted proxy endpoints (array of objects for `format=json`, plain text lines for `format=txt`)",
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProxyEndpoint" } },
                "example": [
                  { "ipAddress": "203.0.113.10", "portValue": 23333 },
                  { "ipAddress": "203.0.113.11", "portValue": 23333 }
                ]
              }
            }
          }
        }
      }
    },
    "/gateway_api/country-list": {
      "get": {
        "tags": ["extraction"],
        "summary": "List supported countries",
        "description": "Countries available for whitelist-mode extraction (code, name, flag icon).",
        "operationId": "countryList",
        "responses": {
          "200": {
            "description": "Supported countries",
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } },
                "example": [{ "country": "US", "name": "United States", "flag_url": "https://file.eproxies.net/flags/us.png" }]
              }
            }
          }
        }
      }
    },
    "/gateway_api/add-ip": {
      "get": {
        "tags": ["whitelist"],
        "summary": "Add a whitelist IP",
        "operationId": "addWhitelistIp",
        "parameters": [
          { "name": "userName", "in": "query", "required": true, "description": "Account username", "schema": { "type": "string" } },
          { "name": "userKeyValue", "in": "query", "required": true, "description": "User key (from the dashboard)", "schema": { "type": "string" } },
          { "name": "ipAddress", "in": "query", "required": true, "description": "IP address to whitelist", "schema": { "type": "string" }, "example": "203.0.113.10" }
        ],
        "responses": {
          "200": { "description": "Add result", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }
        }
      }
    },
    "/gateway_api/del-ip": {
      "get": {
        "tags": ["whitelist"],
        "summary": "Delete a whitelist IP",
        "operationId": "deleteWhitelistIp",
        "parameters": [
          { "name": "userName", "in": "query", "required": true, "description": "Account username", "schema": { "type": "string" } },
          { "name": "userKeyValue", "in": "query", "required": true, "description": "User key (from the dashboard)", "schema": { "type": "string" } },
          { "name": "ipAddress", "in": "query", "required": true, "description": "IP address to remove", "schema": { "type": "string" }, "example": "203.0.113.10" }
        ],
        "responses": {
          "200": { "description": "Delete result", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }
        }
      }
    },
    "/gateway_api/lists-ip": {
      "get": {
        "tags": ["whitelist"],
        "summary": "List whitelist IPs",
        "operationId": "listWhitelistIps",
        "parameters": [
          { "name": "userName", "in": "query", "required": true, "description": "Account username", "schema": { "type": "string" } },
          { "name": "userKeyValue", "in": "query", "required": true, "description": "User key (from the dashboard)", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Current whitelist entries",
            "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ProxyEndpoint": {
        "type": "object",
        "properties": {
          "ipAddress": { "type": "string", "description": "Proxy IP address" },
          "portValue": { "type": "integer", "description": "Proxy port" }
        }
      },
      "Country": {
        "type": "object",
        "properties": {
          "country": { "type": "string", "description": "ISO 3166-1 alpha-2 code" },
          "name": { "type": "string", "description": "Country name" },
          "flag_url": { "type": "string", "description": "Flag icon URL" }
        }
      }
    }
  }
}