REST API Deployment

ProxyWhirl exposes a FastAPI application at proxywhirl.api:app. Use it for service integrations that need HTTP access to pool management, rotation, and monitoring.

Quick Start

tmpdir="$(mktemp -d)"
PROXYWHIRL_STORAGE_PATH="$tmpdir/api.db" \
  uv run uvicorn proxywhirl.api:app --host 127.0.0.1 --port 8765

Verify health and readiness:

uv run python - <<'PY'
import httpx

for path in ("/api/health", "/api/ready"):
    response = httpx.get(f"http://127.0.0.1:8765{path}", timeout=5)
    if path == "/api/ready":
        response.raise_for_status()
    payload = response.json()
    assert payload.get("status") == "success", payload
    print(path, response.status_code, payload["data"])
PY

With an empty database, /api/health may return 503 with an unhealthy body while /api/ready returns 200.

Environment Variables

Authentication

When PROXYWHIRL_API_KEY is set, protected routes require the key via the X-API-Key header. Use a temporary key for local smoke tests; never commit production keys.

Route Surfaces

For the full operation inventory, see REST/OpenAPI Reference and OpenAPI pages.

See Also

• Configuration — TOML and env layering
• Operations — contributor gate matrix
• Operations Playbook — runtime validation loop