### Run from Source with pip install and python3 app.py Source: https://github.com/honmashironeko/proxycat/blob/main/README-EN.md Requires Python 3.10+ due to X | Y union type annotations; 3.9 or earlier raises TypeError at import. Starts the web panel and outbound proxy together. The shipped config sets proxy_source_mode=pool, so the built-in proxy pool starts automatically. ```bash pip install -r requirements.txt # On Windows the command is `python` python3 app.py ``` -------------------------------- ### Build and start ProxyCat container with Docker Compose Source: https://github.com/honmashironeko/proxycat/blob/main/ProxyCat-Manual/Operation Manual-EN.md Builds the Docker image and starts the container from inside the ProxyCat folder. Requires Docker and Docker Compose to be installed. The container exposes ports 1080 (proxy) and 5001 (web panel). ```bash # From inside the ProxyCat folder, build the image and start the container docker compose up -d --build ``` -------------------------------- ### POST /api/pool/start Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Starts the pool. ```APIDOC ## POST /api/pool/start ### Description Start the pool. ### Method POST ### Endpoint /api/pool/start ``` -------------------------------- ### Install Python dependencies with pip Source: https://github.com/honmashironeko/proxycat/blob/main/ProxyCat-Manual/Operation Manual-EN.md Installs the required Python packages from requirements.txt. Python 3.10 or later is required; a mirror option is provided for faster downloads in some regions. ```bash pip install -r requirements.txt # Or use a mirror: pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/ ``` -------------------------------- ### Start Outbound Proxy Service (POST /api/service) Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Sends a JSON request body with action 'start' to start the service. The endpoint is serialized and has timeouts: start waits up to 10 seconds for the old thread to exit and up to 5 seconds for readiness; on timeout it returns status 'error' and does not fall back to another port. ```json { "action": "start" } ``` -------------------------------- ### GET /api/pool/plugins Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Lists plugins and their status. ```APIDOC ## GET /api/pool/plugins ### Description Plugin list and status. ### Method GET ### Endpoint /api/pool/plugins ``` -------------------------------- ### Service Start Port-in-Use Error Response (POST /api/service) Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Error response when the configured port is already in use. The service does not start and returns status 'error' with the specified message. ```json { "status": "error", "message": "Port 1080 is already in use by another program, please choose a different port and retry", "service_status": "stopped" } ``` -------------------------------- ### Open the Panel with Token (GET /web) Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Visiting the panel root with a token set returns a 401 after redirect unless the token is supplied. Use the address with the ?token= query parameter. GET / itself performs no check and carries ?token= through unchanged when redirecting to /web. ```http http://127.0.0.1:5001/?token= ``` -------------------------------- ### GET /api/pool/sources Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Lists the names of source plugins. ```APIDOC ## GET /api/pool/sources ### Description List of source plugin names. ### Method GET ### Endpoint /api/pool/sources ``` -------------------------------- ### GET /api/pool/tasks Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Lists tasks. ```APIDOC ## GET /api/pool/tasks ### Description List tasks. ### Method GET ### Endpoint /api/pool/tasks ``` -------------------------------- ### POST /api/pool/start Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Starts the proxy pool. This endpoint takes no parameters and returns the new running state. ```APIDOC ## POST /api/pool/start ### Description Starts the proxy pool. This endpoint takes no parameters and returns the new running state. ### Method POST ### Endpoint /api/pool/start ### Parameters None. ### Response #### Success Response (200) - **status** (string) - Always "success" - **message** (string) - Success message - **is_running** (boolean) - Whether the pool is now running #### Response Example ```json { "status": "success", "message": "Pool started successfully", "is_running": true } ``` ``` -------------------------------- ### GET /api/pool/backups Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Lists backups. ```APIDOC ## GET /api/pool/backups ### Description List backups. ### Method GET ### Endpoint /api/pool/backups ``` -------------------------------- ### POST /api/pool/start Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Starts the proxy pool. Returns a status and message, with no `error_code` on failure. ```APIDOC ## POST /api/pool/start ### Description Starts the proxy pool. Returns a status and message, with no `error_code` on failure. ### Method POST ### Endpoint /api/pool/start ### Response #### Success Response (200) - **status** (string) - Success indicator. - **message** (string) - Human-readable message. - **is_running** (boolean) - Whether the pool is running. #### Error Response (500) - **status** (string) - `error` - **message** (string) - Error description. - **is_running** (boolean) - Whether the pool is running. ``` -------------------------------- ### GET /static/ Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Serves frontend static assets. No authentication required. ```APIDOC ## [GET] /static/ ### Description Serves frontend static assets. ### Method GET ### Endpoint /static/ ### Path Parameters - **path** (string) - Required - Path to the static asset. ### Response #### Success Response (200) Static asset content. ``` -------------------------------- ### POST /api/pool/restart Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Restarts the proxy pool. This endpoint takes no parameters. It stops and then starts; the stop and the start each wait up to 30 seconds. ```APIDOC ## POST /api/pool/restart ### Description Restarts the proxy pool. This endpoint takes no parameters. It stops and then starts; the stop and the start each wait up to 30 seconds. ### Method POST ### Endpoint /api/pool/restart ### Parameters None. ### Response #### Success Response (200) - **status** (string) - Always "success" - **message** (string) - Success message - **is_running** (boolean) - Whether the pool is now running #### Response Example ```json { "status": "success", "message": "Pool restarted successfully", "is_running": true } ``` #### Error Response (500) - **status** (string) - Always "error" - **message** (string) - Error message - **is_running** (boolean) - Whether the pool is running #### Error Example ```json { "status": "error", "message": "...", "is_running": false } ``` ``` -------------------------------- ### GET /api/logs/export Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Exports logs. ```APIDOC ## GET /api/logs/export ### Description Exports logs. ### Method GET ### Endpoint /api/logs/export ``` -------------------------------- ### GET /api/logs/files Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Lists log files. ```APIDOC ## GET /api/logs/files ### Description Lists log files. ### Method GET ### Endpoint /api/logs/files ``` -------------------------------- ### GET / Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Redirects to /web with the token. No authentication required. ```APIDOC ## [GET] / ### Description Redirects to `/web` with the token. ### Method GET ### Endpoint / ### Response #### Success Response (200) Redirect to `/web` with the token. ``` -------------------------------- ### Clone ProxyCat repository with Git Source: https://github.com/honmashironeko/proxycat/blob/main/ProxyCat-Manual/Operation Manual-EN.md Clones the ProxyCat project from GitHub on Linux. Requires Git to be installed. ```bash git clone https://github.com/honmashironeko/ProxyCat.git ``` -------------------------------- ### GET /api/logs Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Queries in-memory logs. ```APIDOC ## GET /api/logs ### Description Queries in-memory logs. ### Method GET ### Endpoint /api/logs ``` -------------------------------- ### POST /api/pool/start|stop|restart Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Starts, stops, or restarts the pool. On failure, returns 500 with no error_code. ```APIDOC ## [POST] /api/pool/start|stop|restart ### Description Starts, stops, or restarts the pool. On failure, returns 500 with no error_code. ### Method POST ### Endpoint /api/pool/start|stop|restart ### Response #### Success Response (200) `{"status": "success", ...}` #### Error Response (500) `{"status": "error", "message": "..."}` ``` -------------------------------- ### GET /api/config Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Reads the [Server] and [Pool] configuration. ```APIDOC ## GET /api/config ### Description Reads the [Server] and [Pool] configuration. ### Method GET ### Endpoint /api/config ``` -------------------------------- ### GET /web Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Serves the panel single page. Requires authentication. ```APIDOC ## [GET] /web ### Description Serves the panel single page. ### Method GET ### Endpoint /web ### Authentication Required ### Response #### Success Response (200) Panel single page. ``` -------------------------------- ### GET /api/config Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Returns every key and value of the [Server] and [Pool] sections. The token key is stripped out, and [Users] and [api_credentials] are not returned here. ```APIDOC ## [GET] /api/config ### Description Returns every key and value of the `[Server]` and `[Pool]` sections. The `token` key is stripped out, and `[Users]` and `[api_credentials]` are not returned here. ### Method GET ### Endpoint /api/config ### Response #### Success Response (200) - **status** (string) - Always "success" - **server** (object) - Server configuration keys and values - **pool** (object) - Pool configuration keys and values #### Response Example ```json { "status": "success", "server": { "port": "1080", "web_port": "5001", "mode": "cycle" }, "pool": { "validator.timeout_seconds": "10" } } ``` ``` -------------------------------- ### GET /api/pool/plugins Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Lists all successfully loaded plugins with their configuration and scheduling details. The response is a JSON array without a status field. ```APIDOC ## [GET] /api/pool/plugins ### Description Lists all plugins that loaded successfully, including their configuration and scheduling details. ### Method GET ### Endpoint /api/pool/plugins ### Response #### Success Response (200) - **name** (string) - The plugin name, equal to the plugin file's file name without its extension - **enabled** (boolean) - Whether the plugin takes part in automatic fetch scheduling - **interval_minutes** (integer) - Fetch interval in minutes - **last_run** (string|null) - An ISO 8601 string or null - **next_run** (string|null) - An ISO 8601 string or null - **last_error** (string|null) - The most recent error; a built-in message key is rendered in the current language, while an exception text raised by the plugin itself is passed through as-is - **is_loaded** (boolean) - Whether the module loaded successfully. The response only includes plugins that loaded successfully, so this is always true; a plugin that failed to load does not appear in the list (the error is only recorded in the pool's log) - **test_url** (string) - The liveness test URL used only by this plugin; an empty string means it inherits the global [Server] test_url - **reval_enabled** (boolean) - Whether the plugin takes part in automatic revalidation - **reval_interval_minutes** (integer) - Revalidation interval; 0 means inherit the global value - **skip_validation** (boolean) - Whether to skip validation before storing (high risk) #### Response Example ```json [ { "name": "geonode_plugin", "enabled": true, "interval_minutes": 60, "last_run": "2026-09-30T11:00:00", "next_run": "2026-09-30T12:00:00", "last_error": null, "is_loaded": true, "test_url": "", "reval_enabled": true, "reval_interval_minutes": 0, "skip_validation": false } ] ``` ``` -------------------------------- ### GET /web Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Returns the panel's single page. Requires a token when authentication is enabled; the token is passed via the query parameter. ```APIDOC ## [GET] /web ### Description Returns the panel's single page. Requires a token when authentication is enabled; the token is passed via the query parameter. ### Method GET ### Endpoint /web ### Parameters #### Query Parameters - **token** (string) - Required - Authentication token. ### Response #### Success Response (200) Returns the panel's HTML page. #### Redirect Behavior - `GET /?token=abc` → `302` → `/web?token=abc` - `GET /` (no token) → `302` → `/web` ``` -------------------------------- ### GET /api/logs/records/options Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Retrieves filter options for access records. ```APIDOC ## GET /api/logs/records/options ### Description Retrieves filter options for access records. ### Method GET ### Endpoint /api/logs/records/options ``` -------------------------------- ### POST /api/service Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Starts, stops, or restarts the outbound proxy service. ```APIDOC ## POST /api/service ### Description Starts, stops, or restarts the outbound proxy service. ### Method POST ### Endpoint /api/service ``` -------------------------------- ### Implement IProxyPlugin interface (ExamplePlugin) Source: https://github.com/honmashironeko/proxycat/blob/main/modules/proxypool/README-EN.md Recommended way to write a scrape plugin. Define a class implementing IProxyPlugin with fetch_proxies, name, and version. Use context.http_client for requests; raise PluginExecutionException on failure to trigger retries and error reporting. Returning an empty list is treated as 'no proxies right now' and does not retry or report an error. ```python """Example: scrape proxies from an API.""" import json from typing import List from core.domain.exceptions import PluginExecutionException from core.interfaces.services import IProxyPlugin, PluginContext class ExamplePlugin(IProxyPlugin): """Plugin description. It is written to the log and also shown in the plugin list.""" API_URL = "https://example.com/api/proxies" async def fetch_proxies(self, context: PluginContext) -> List[str]: """Return a list of proxy URLs, each in the form protocol://ip:port or protocol://user:pass@ip:port.""" response = await context.http_client.get(self.API_URL) if response.status != 200: # Raise when the fetch fails: returning an empty list is taken by the # scheduler as "this source has no proxies right now" — it neither # retries nor reports an error in the plugin list. raise PluginExecutionException( f"Request to {self.API_URL} failed, HTTP status code: {response.status}" ) items = json.loads(response.text).get("data", []) return [f"http://{item['ip']}:{item['port']}" for item in items] @property def name(self) -> str: return "example" @property def version(self) -> str: return "1.0.0" ``` -------------------------------- ### GET /api/version Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Returns the version check result (read-only cache, no authentication). ```APIDOC ## GET /api/version ### Description Returns the version check result (read-only cache, no authentication). ### Method GET ### Endpoint /api/version ``` -------------------------------- ### GET /api/version Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Retrieves the current version. This endpoint reads a cache and makes no request; the check is done at process start and by a background task every 24 hours. ```APIDOC ## [GET] /api/version ### Description Retrieves the current version. This endpoint reads a cache and makes no request; the check is done at process start and by a background task every 24 hours. ### Method GET ### Endpoint /api/version ### Response #### Success Response (200) - **version** (string) - The current version. ``` -------------------------------- ### GET /api/ads Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Gets ads (no authentication). ```APIDOC ## GET /api/ads ### Description Gets ads (no authentication). ### Method GET ### Endpoint /api/ads ``` -------------------------------- ### Verify Deployment with curl Source: https://github.com/honmashironeko/proxycat/blob/main/README-EN.md First command checks the panel (expect 302 redirect to /web). Second checks proxy forwarding (expect 200) with authentication; without credentials you get 407. ```bash # 1. The panel is listening: expect 302 (redirect to /web) curl -i http://127.0.0.1:5001/ # 2. The proxy is forwarding: expect 200, with the request actually going through an upstream. # The [Users] section of the shipped config has accounts, so requests must be authenticated; # without credentials you get a 407. curl -x http://neko:123456@127.0.0.1:1080 https://www.baidu.com -I ``` -------------------------------- ### GET /api/logs/files Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Lists log files available for download, including rotated copies. Only whitelisted files under the logs/ directory are listed. ```APIDOC ## [GET] /api/logs/files ### Description Lists log files available for download, including rotated copies. Only whitelisted files under the logs/ directory are listed. ### Method GET ### Endpoint /api/logs/files ### Response #### Success Response (200) - **status** (string) - `success` - **files** (array) - List of file objects with `name`, `category`, `size`, `modified`, `current`, `rotated` - **name** (string) - File name (used to call `/api/logs/file`) - **category** (string) - `main` / `proxy` / `access` / `error` (error must not be passed as category parameter of GET /api/logs) - **size** (integer) - Size in bytes - **modified** (string) - Last modified time - **current** (boolean) - Whether this is the currently written file - **rotated** (boolean) - Opposite of `current`; true for rotated historical copies ### Request Example ```json { "status": "success", "files": [ { "name": "main.log", "category": "main", "size": 20480, "modified": "2026-10-02 15:30:00", "current": true, "rotated": false } ] } ``` ``` -------------------------------- ### GET /api/pool/backups Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Retrieves a list of backup objects. Each backup object contains the filename, size, and creation time of a backup file. ```APIDOC ## GET /api/pool/backups ### Description Retrieves a list of backup objects. Each backup object contains the filename, size, and creation time of a backup file. ### Method GET ### Endpoint /api/pool/backups ### Response #### Success Response (200) - **filename** (string) - Backup file name, used as the parameter of `POST /api/pool/backups/restore` - **size** (int) - File size (bytes) - **created_at** (string) - Creation time, always formatted as `YYYY-MM-DD HH:MM:SS` ``` -------------------------------- ### Docker Compose Deployment Source: https://github.com/honmashironeko/proxycat/blob/main/README-EN.md Builds the image and starts the container. Exposes ports 1080 (proxy) and 5001 (web panel). Binds config/, logs/, and modules/proxypool/data/ to the host. ```bash docker compose up -d --build ``` -------------------------------- ### GET /api/proxies Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Returns the contents of the proxy list file under config/. A read failure returns an error, not an empty list. ```APIDOC ## [GET] /api/proxies ### Description Returns the contents of the proxy list file under config/. A read failure returns an error, not an empty list. ### Method GET ### Endpoint /api/proxies ### Response #### Success Response (200) - **proxies** (array of strings) - List of proxy addresses #### Error Response - **status** (string) - `error` - **message** (string) - Error description ### Response Example ```json { "proxies": ["http://1.2.3.4:8080", "socks5://5.6.7.8:1080"] } ``` #### Error Response Example ```json { "status": "error", "message": "Failed to load proxy file: ..." } ``` ``` -------------------------------- ### GET /api/status Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Returns a live snapshot of the outbound proxy service. Takes no request parameters. ```APIDOC ## [GET] /api/status ### Description Returns a live snapshot of the outbound proxy service. Takes no request parameters. ### Method GET ### Endpoint /api/status ### Parameters None ### Response #### Success Response (200) Returns a JSON object with the following fields: - **current_proxy** (string) - Current proxy URL. - **mode** (string) - Proxy selection mode (e.g., "cycle"). - **port** (integer) - Local proxy port. - **interval** (integer) - Switch interval in seconds. - **time_left** (number) - Time left in current cycle. - **switch_countdown_mode** (string) - Countdown mode (e.g., "time"). - **total_proxies** (integer) - Total number of proxies. - **active_proxies** (array) - List of active proxy objects with fields: url, inflight, active, capacity, failures, suspect, failure_ratio, last_used. - **proxy_source_mode** (string) - Source mode (e.g., "local"). - **exit_count** (integer) - Number of exits. - **elastic_active** (boolean) - Whether elastic mode is active. - **auth_required** (boolean) - Whether authentication is required. - **display_level** (integer) - Display level. - **service_status** (string) - Service status (e.g., "running"). - **language** (string) - Language code (e.g., "cn"). - **request_interval** (integer) - Request interval. - **pool_running** (boolean) - Whether the pool is running. - **source_error** (string/null) - Source error message if any. #### Response Example ```json { "current_proxy": "http://1.2.3.4:8080", "mode": "cycle", "port": 1080, "interval": 300, "time_left": 123.4, "switch_countdown_mode": "time", "total_proxies": 10, "active_proxies": [ { "url": "http://1.2.3.4:8080", "inflight": 3, "active": 2, "capacity": 0, "failures": 0, "suspect": false, "failure_ratio": 0.0, "last_used": 12.5 } ], "proxy_source_mode": "local", "exit_count": 5, "elastic_active": true, "auth_required": false, "display_level": 1, "service_status": "running", "language": "cn", "request_interval": 0, "pool_running": true, "source_error": null } ``` ``` -------------------------------- ### Example ip.txt proxy list format Source: https://github.com/honmashironeko/proxycat/blob/main/ProxyCat-Manual/Operation Manual-EN.md Shows the expected format for the local ip.txt file when serving fixed proxy addresses. Each line contains protocol://[user:password@]host:port; supported protocols are http, https, and socks5, with optional username/password authentication. ```text socks5://neko:123456@127.0.0.1:7890 https://neko:123456@127.0.0.1:7890 http://neko:123456@127.0.0.1:7890 socks5://127.0.0.1:7890 https://127.0.0.1:7890 http://127.0.0.1:7890 ... ``` -------------------------------- ### POST /api/pool/plugins/{name}/run Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Runs a plugin immediately. ```APIDOC ## POST /api/pool/plugins/{name}/run ### Description Run a plugin immediately. ### Method POST ### Endpoint /api/pool/plugins/{name}/run ### Parameters #### Path Parameters - **name** - Required - Plugin name ``` -------------------------------- ### GET /api/pool/random Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Retrieves a random proxy object from the pool. The response contains the same detailed proxy information as the get endpoint, including address, protocol, region, validation status, and quality metrics. ```APIDOC ## [GET] /api/pool/random ### Description Retrieves a random proxy object from the pool. The response contains the same detailed proxy information as the get endpoint, including address, protocol, region, validation status, and quality metrics. ### Method GET ### Endpoint /api/pool/random ### Response #### Success Response (200) - **id** (int) - Primary key - **proxy_url** (string) - Full proxy address; when the username and password **are both present**, it takes the form `protocol://user:password@ip:port` - **protocol** (string) - `http` / `https` / `socks5` - **ip** (string) - Entry IP - **port** (int) - Port - **username** / **password** (string | null) - Proxy authentication credentials - **real_ip** (string | null) - Egress IP (the IP the peer sees when requests go through the proxy) - **exit_ip_differs** (bool) - Whether the entry IP differs from the egress IP. **Supplied in both the query and random responses** (the two share one serialization); the export paths deliberately leave it out - **region** (string) - Full Chinese region name, e.g. 「中国 广东 深圳」; 「未知」 ("unknown") when the lookup finds nothing - **country** / **province** / **city** (string) - Chinese region levels - **region_en** / **country_en** / **province_en** / **city_en** (string | null) - English region levels - **delay_ms** (float | null) - Most recently measured delay (milliseconds) - **validated_at** (string | null) - Most recent validation time (ISO 8601) - **source_plugin** (string) - Source plugin name; `manual_import` for manual imports - **is_favorite** (bool) - Whether the proxy is favorited (a user choice that fetching and validation do not overwrite) - **is_valid** (bool) - Whether the proxy is currently usable; the list uses it to badge invalid rows as 「失效」 ("invalid"). Exports use their own status column - **health_score** (float) - Health score, **0-100**, 1 decimal place - **anonymity_level** (string) - `transparent` / `anonymous` / `elite` / `unverified` - **anonymity_fallback** (bool) - Whether the anonymity level was judged to be the anonymity fallback - **supports_https** / **supports_http** (bool) - Whether the corresponding protocol is supported - **quality_assessed_at** (string | null) - Most recent quality assessment time (ISO 8601) - **success_rate** (float) - Validation success rate, 0-1, 3 decimal places - **avg_delay_ms** (float | null) - Historical average delay (milliseconds) - **total_checks** (int) - Cumulative validation count; missing values fall back to 0 - **probe_success_rate** (float) - Probe success rate, 0-1, 3 decimal places - **probe_total_count** (int) - Cumulative probe count; missing values fall back to 0 ``` -------------------------------- ### GET /api/logs/records/options Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Returns the upstream proxy and target host values that appear in the current records, for the frontend to render dropdowns. ```APIDOC ## GET /api/logs/records/options ### Description Returns the upstream proxy and target host values that appear in the current records, for the frontend to render dropdowns. ### Method GET ### Endpoint /api/logs/records/options ### Response #### Success Response (200) - **status** (string) - Status of the response. - **upstreams** (array) - List of upstream proxy values and labels. #### Response Example ```json { "status": "success", "upstreams": [{ "value": "http://1.2.3.4:8080", "label": "..." }] } ``` ``` -------------------------------- ### Run a Plugin Immediately (POST /api/pool/plugins/{name}/run) - Response Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md No request body. Returns as soon as a background task is created; the fetch is bounded by [Pool] plugins.execution_timeout_seconds. status is a snapshot; poll task_id for progress. Plugin not loaded → 404 api_error. ```json { "task_id": "8f14e45f-ea6b-4c1e-9c1a-0f3b2d5e7a91", "status": "running", "message": "Fetch task created for plugin geonode_plugin" } ``` -------------------------------- ### Run ProxyCat CLI with custom config file Source: https://github.com/honmashironeko/proxycat/blob/main/ProxyCat-Manual/Operation Manual-EN.md Starts the CLI-only outbound proxy service (no web panel) using the specified configuration file. The `-c` flag points to a config file, defaulting to `config/config.ini`. On Windows, use `python` instead of `python3`. ```bash python ProxyCat.py -c config/config.ini # On Windows the command is python, so write it as python ProxyCat.py ``` -------------------------------- ### GET /api/pool/database/stats Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Retrieves database statistics. ```APIDOC ## GET /api/pool/database/stats ### Description Database statistics. ### Method GET ### Endpoint /api/pool/database/stats ``` -------------------------------- ### GET /api/pool/stats Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Retrieves pool statistics. ```APIDOC ## GET /api/pool/stats ### Description Pool statistics. ### Method GET ### Endpoint /api/pool/stats ``` -------------------------------- ### Provide only a fetch_proxies function (old style) Source: https://github.com/honmashironeko/proxycat/blob/main/modules/proxypool/README-EN.md Legacy plugin style: define a module-level fetch_proxies function. It can be synchronous or asynchronous; synchronous versions run in a thread pool. Return a list of proxy URLs. ```python def fetch_proxies(): return ["http://1.2.3.4:8080", "socks5://5.6.7.8:1080"] ``` -------------------------------- ### GET /api/logs/domains Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Queries domain statistics. ```APIDOC ## GET /api/logs/domains ### Description Queries domain statistics. ### Method GET ### Endpoint /api/logs/domains ``` -------------------------------- ### Access the panel with token query parameter Source: https://github.com/honmashironeko/proxycat/blob/main/ProxyCat-Manual/Operation Manual-EN.md Use this URL to open the web panel when a token is set. The panel is token-guarded and returns 401 without the token. The token in the repo is public and must be changed before exposing the panel. ```text http://127.0.0.1:5001/?token=honmashironeko ``` -------------------------------- ### GET /api/logs/records/export Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Exports access records. ```APIDOC ## GET /api/logs/records/export ### Description Exports access records. ### Method GET ### Endpoint /api/logs/records/export ``` -------------------------------- ### GET /api/logs/records Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Queries access records. ```APIDOC ## GET /api/logs/records ### Description Queries access records. ### Method GET ### Endpoint /api/logs/records ``` -------------------------------- ### POST /api/pool/plugins/{name}/run Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Triggers an immediate fetch for a plugin. The call returns as soon as a background task is created; the fetch itself is bounded by the pool's execution timeout. ```APIDOC ## [POST] /api/pool/plugins/{name}/run ### Description Triggers an immediate fetch for a plugin. The call returns as soon as a background task is created; the fetch itself is bounded by the pool's execution timeout. ### Method POST ### Endpoint /api/pool/plugins/{name}/run ### Parameters #### Path Parameters - **name** (string) - Required - The plugin name ### Response #### Success Response (200) - **task_id** (string) - The ID of the background task - **status** (string) - Snapshot of the task status at creation time - **message** (string) - Confirmation message #### Error Response (404) - **error** (string) - api_error (when plugin is not loaded) #### Response Example ```json { "task_id": "8f14e45f-ea6b-4c1e-9c1a-0f3b2d5e7a91", "status": "running", "message": "Fetch task created for plugin geonode_plugin" } ``` ``` -------------------------------- ### GET /api/logs/file Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Reads a log file. ```APIDOC ## GET /api/logs/file ### Description Reads a log file. ### Method GET ### Endpoint /api/logs/file ``` -------------------------------- ### POST /api/pool/plugins/{name}/run Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Triggers a fetch by hand by running a plugin immediately. This endpoint is part of the Pool API and follows the pool's error convention (real status code plus error_code). ```APIDOC ## POST /api/pool/plugins/{name}/run ### Description Triggers a fetch by hand by running a plugin immediately. ### Method POST ### Endpoint /api/pool/plugins/{name}/run ### Parameters #### Path Parameters - **name** (string) - Required - The name of the plugin to run. ### Response #### Success Response (200) - **status** (string) - Indicates success or error. ``` -------------------------------- ### GET /api/logs/stats Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Retrieves log statistics. ```APIDOC ## GET /api/logs/stats ### Description Retrieves log statistics. ### Method GET ### Endpoint /api/logs/stats ``` -------------------------------- ### Python: Panel and Pool API usage Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Python example covering panel status, manual proxy switch, failed request logs, pool random proxy retrieval, and batch validation task creation/polling. Requires a running server at localhost:5001 and a valid token. Note that cooldown and genuine failures both return error status; distinguish them via the 'cooldown' field. ```python import requests HOST = "http://localhost:5001" TOKEN = "YOUR_TOKEN" PARAMS = {"token": TOKEN} # Panel: view runtime status status = requests.get(f"{HOST}/api/status", params=PARAMS).json() print(status["current_proxy"], status["proxy_source_mode"]) # Panel: manually switch the upstream proxy once switched = requests.get(f"{HOST}/api/switch_proxy", params=PARAMS).json() if switched["status"] != "success": # A cooldown and a genuine failure both come back as error; tell them apart by the field print("In cooldown" if switched.get("cooldown") else switched.get("message")) # Panel: query failed requests from the past hour records = requests.get( f"{HOST}/api/logs/records", params={**PARAMS, "outcome": "failure", "limit": 50}, ).json() for row in records["records"]: print(row["ts"], row["host"], row["upstream_label"], row["reason"]) # Pool: get an available proxy (plain text) proxy = requests.get( f"{HOST}/api/pool/random", params={**PARAMS, "status": "valid", "format": "text"}, ).text.strip() print(proxy) # for example http://1.2.3.4:8080 # Pool: create a batch validation task and poll it task = requests.post( f"{HOST}/api/pool/proxies/batch/validate", params=PARAMS, json={"proxy_ids": [1, 2, 3], "mode": "liveness"}, ).json() progress = requests.get( f"{HOST}/api/pool/tasks/{task['task_id']}", params=PARAMS ).json() print(progress["status"], progress.get("progress"), progress.get("total")) ``` -------------------------------- ### GET /api/bypass_whitelist Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Reads the bypass list. ```APIDOC ## GET /api/bypass_whitelist ### Description Reads the bypass list. ### Method GET ### Endpoint /api/bypass_whitelist ``` -------------------------------- ### GET /static/ Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Serves front-end static assets from the web/static/ directory. Cache headers vary based on the presence of the version query parameter. ```APIDOC ## [GET] /static/ ### Description Serves front-end static assets from the web/static/ directory. Cache headers vary based on the presence of the version query parameter. ### Method GET ### Endpoint /static/ ### Parameters #### Path Parameters - **path** (string) - Required - Path to the static asset. #### Query Parameters - **v** (string) - Optional - Version parameter; when present, response includes `Cache-Control: public, max-age=31536000, immutable`; otherwise `Cache-Control: no-cache`. ``` -------------------------------- ### Service Start Success Response (POST /api/service) Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Successful response for start/stop actions. Carries 'service_status' with values 'running' or 'stopped'. A successful 'restart' does not include this field. ```json { "status": "success", "message": "Service started successfully", "service_status": "running" } ``` -------------------------------- ### GET /api/pool/count Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Counts proxies matching the filters. ```APIDOC ## GET /api/pool/count ### Description Count proxies matching the filters. ### Method GET ### Endpoint /api/pool/count ``` -------------------------------- ### POST /api/pool/import Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Batch imports proxies, validating them before ingestion. ```APIDOC ## POST /api/pool/import ### Description Batch import (validate before ingesting). ### Method POST ### Endpoint /api/pool/import ``` -------------------------------- ### POST /api/pool/plugins/{name}/enable Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Enables a specific plugin. ```APIDOC ## POST /api/pool/plugins/{name}/enable ### Description Enable a plugin. ### Method POST ### Endpoint /api/pool/plugins/{name}/enable ### Parameters #### Path Parameters - **name** - Required - Plugin name ``` -------------------------------- ### GET /api/api_credentials Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Reads upstream API credentials. ```APIDOC ## GET /api/api_credentials ### Description Reads upstream API credentials. ### Method GET ### Endpoint /api/api_credentials ``` -------------------------------- ### POST /api/language Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Switches the UI language. ```APIDOC ## POST /api/language ### Description Switches the UI language. ### Method POST ### Endpoint /api/language ``` -------------------------------- ### GET /api/users Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Reads outbound proxy accounts. ```APIDOC ## GET /api/users ### Description Reads outbound proxy accounts. ### Method GET ### Endpoint /api/users ``` -------------------------------- ### GET /api/ip_lists Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Reads the IP whitelist / blacklist. ```APIDOC ## GET /api/ip_lists ### Description Reads the IP whitelist / blacklist. ### Method GET ### Endpoint /api/ip_lists ``` -------------------------------- ### POST /api/pool/plugins/{name}/enable Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Enables a plugin so it takes part in automatic fetch scheduling. No request body is required. ```APIDOC ## [POST] /api/pool/plugins/{name}/enable ### Description Enables a plugin so it takes part in automatic fetch scheduling. ### Method POST ### Endpoint /api/pool/plugins/{name}/enable ### Parameters #### Path Parameters - **name** (string) - Required - The plugin name ### Response #### Success Response (200) - **success** (boolean) - Always true - **message** (string) - Confirmation message #### Error Response (500) - **error** (string) - api_error #### Response Example ```json { "success": true, "message": "Plugin geonode_plugin enabled" } ``` ``` -------------------------------- ### GET /api/proxies Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Reads the local proxy list. ```APIDOC ## GET /api/proxies ### Description Reads the local proxy list. ### Method GET ### Endpoint /api/proxies ``` -------------------------------- ### POST /api/language Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Switches the UI language of the panel. ```APIDOC ## POST /api/language ### Description Switches the UI language of the panel. ### Method POST ### Endpoint /api/language ### Parameters #### Query Parameters - **token** (string) - Required - Authentication token #### Request Body - **language** (string) - Required - Language code (e.g., "en") ### Request Example ```bash curl -X POST "http://localhost:5001/api/language?token=YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"language": "en"}' ``` ``` -------------------------------- ### GET /api/pool/geo/status Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Retrieves the status of the offline geolocation database. ```APIDOC ## GET /api/pool/geo/status ### Description Offline geolocation database status. ### Method GET ### Endpoint /api/pool/geo/status ``` -------------------------------- ### POST /api/config Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Saves the configuration. ```APIDOC ## POST /api/config ### Description Saves the configuration. ### Method POST ### Endpoint /api/config ``` -------------------------------- ### GET /api/pool/tasks/{task_id} Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Queries the status of a specific task. ```APIDOC ## GET /api/pool/tasks/{task_id} ### Description Query task status. ### Method GET ### Endpoint /api/pool/tasks/{task_id} ### Parameters #### Path Parameters - **task_id** - Required - Task ID ``` -------------------------------- ### GET /api/pool/host-ip Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Returns the public egress IP of this host. ```APIDOC ## GET /api/pool/host-ip ### Description This host's public egress IP. ### Method GET ### Endpoint /api/pool/host-ip ``` -------------------------------- ### GET /api/status Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Retrieves the runtime status of the proxy service. ```APIDOC ## GET /api/status ### Description Retrieves the runtime status of the proxy service. ### Method GET ### Endpoint /api/status ``` -------------------------------- ### POST /api/pool/import Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Imports a batch of proxies into the pool. ```APIDOC ## POST /api/pool/import ### Description Imports a batch of proxies into the pool. ### Method POST ### Endpoint /api/pool/import ### Parameters #### Query Parameters - **token** (string) - Required - Authentication token #### Request Body - **proxies** (array of strings) - Required - List of proxy addresses to import ### Request Example ```bash curl -X POST "http://localhost:5001/api/pool/import?token=YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"proxies": ["http://1.2.3.4:8080"]}' ``` ``` -------------------------------- ### GET /api/ip_lists Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Returns the current IP whitelist and blacklist. ```APIDOC ## [GET] /api/ip_lists ### Description Returns the current IP whitelist and blacklist. ### Method GET ### Endpoint /api/ip_lists ### Response #### Success Response (200) - **whitelist** (array of strings) - List of whitelisted IPs - **blacklist** (array of strings) - List of blacklisted IPs ### Response Example ```json { "whitelist": ["127.0.0.1"], "blacklist": ["1.2.3.4"] } ``` ``` -------------------------------- ### POST /api/proxies Source: https://github.com/honmashironeko/proxycat/blob/main/API-EN.md Writes the local proxy list. ```APIDOC ## POST /api/proxies ### Description Writes the local proxy list. ### Method POST ### Endpoint /api/proxies ```