Control WhaleProxy with code.

Overview

The API is a machine-to-machine interface to the routing engine. The default base URL is http://127.0.0.1:8091/v1, JSON in/out. Enable it in the Settings tab.

By default it listens on loopback (127.0.0.1) only. You can bind it to a network IP for remote control — put it behind TLS + a firewall, since the engine runs elevated and controls all of the machine's network traffic.

Authentication

Every request (except /v1/healthz) needs an API key, sent in a header. The key is CSPRNG-generated; create/rotate it in Settings → Generate. Keys are compared in constant time.

X-API-Key: <YOUR_API_KEY>
# hoặc
Authorization: Bearer <YOUR_API_KEY>

Reroute — change a running process's proxy

Select processes by pids, exe name, path, identity hash, or nickname — then point them at a new proxy. Use /preview to dry-run without applying.

{ "match": { "nickname": "Acc 3" }, "proxy": "jp-2" }

→ 200 { "rerouted": 1, "flows_moved": 12 }

Proxies

Manage the upstream pool (socks5 / http / localnet). Test returns latency and the real exit IP.

Rules

Persistent, first-match-wins rules applied to current and future processes.

Processes

Inspect tracked processes, assign nicknames, or kill them.

Stats & events

Read bytes/flows/connections per process and per proxy; long-poll spawn/exit events.

Command line

The CLI wraps the same commands; add --json for machine-readable output. Runs while the engine is up.

$ whaleproxy proxies list --json
$ whaleproxy reroute --name chrome.exe --to jp-2
$ whaleproxy pin --nickname "Acc 3" --proxy us-1
$ whaleproxy stats --json

Example — call it from Python

The API is plain HTTP, callable from any language. The example below moves one account to a different proxy.

import requests

API = "http://127.0.0.1:8091/v1"
H   = { "X-API-Key": "YOUR_KEY" }

# Đổi proxy của "Acc 3" sang jp-2, ngay khi đang chạy
r = requests.post(f"{API}/reroute", headers=H, json={
    "match": { "nickname": "Acc 3" },
    "proxy": "jp-2"
})
print(r.json())  # {'rerouted': 1, 'flows_moved': 12}