Authoritative resources for the runtime APIs, configuration knobs, and public data models.

Reference

Quick Lookup

By Interface

Interface	Entry Point	Docs
Python sync	ProxyWhirl	Python API
Python async	AsyncProxyWhirl	Python API
REST API	GET/POST /api/v1/*	REST API
CLI	proxywhirl <command>	CLI Reference
MCP	proxywhirl mcp	MCP Server

By Task

Task	Where to Look
Configure rotation strategy	Configuration – [rotation] section
Handle errors	Exceptions – error codes and hierarchy
Set up caching	Cache API – CacheConfig, tier options
Rate limit requests	Rate Limiting API – token bucket setup
Set up authentication	REST API – API key configuration
Tune retry behavior	Retry & Failover – RetryPolicy options

By Class

Class	Module	Docs
ProxyWhirl	proxywhirl.rotator	Sync rotator
AsyncProxyWhirl	proxywhirl.rotator	Async rotator
ProxyFetcher	proxywhirl.fetchers	Fetcher
ProxyValidator	proxywhirl.fetchers	Validator
CacheManager	proxywhirl.cache	Cache API
RateLimiter	proxywhirl.rate_limiting	Rate Limiting API
SyncRateLimiter	proxywhirl.rate_limiting	Rate Limiting API
AsyncRateLimiter	proxywhirl.rate_limiting	Rate Limiting API
CircuitBreaker	proxywhirl.circuit_breaker	Retry & Failover
RetryExecutor	proxywhirl.retry	Python API
StrategyRegistry	proxywhirl.strategies	Python API
StrategyState	proxywhirl.strategies	Python API
BrowserRenderer	proxywhirl.browser	Browser
CacheHealthStatus	proxywhirl	Python API
HealthMonitor	proxywhirl.models	Python API
SourceStats	proxywhirl.models	Python API
HourlyAggregate	proxywhirl.retry	Python API
CircuitBreakerEvent	proxywhirl.retry	Python API

API Surfaces

REST API

Complete REST endpoint documentation with examples, error codes, and deployment guides.

• Starting the server – dev mode, production, Docker

• Authentication – API key setup

• Rotation endpoints – GET/PUT config, strategy context

• Pool management – CRUD proxies, health checks

• Proxied requests – POST requests through rotating proxies

FastAPI OpenAPI

ProxyWhirl REST API Usage Guide

Python API

Core classes, strategies, models, and utility functions.

• ProxyWhirl – sync client with context manager

• AsyncProxyWhirl – async client, connection pooling

• Rotation strategies – all 9 strategy classes

• ProxyFetcher & Validator – fetch, validate, enrich

• BrowserRenderer – Playwright JS-rendered sources

Python httpx

Python API

Configuration & Error Handling

Configuration

TOML configuration reference with all options and environment variables.

• Configuration discovery – auto-detect paths

• TOML format – complete annotated example

• File locations – pyproject.toml, standalone, explicit path

• Environment variables – PROXYWHIRL_* overrides

TOML env vars

Configuration Reference

Exceptions

Error handling, exception hierarchy, and error codes.

• Exception hierarchy – tree of all exception types

• Error codes – ProxyErrorCode enum values

• URL redaction – redact_url() for safe logging

• Per-exception reference – when raised, attributes, resolution

errors security

Exceptions Reference

Subsystem APIs

Cache API

Multi-tier caching system with L1/L2/L3 storage, TTL management, and health-based invalidation.

• Data models – CacheEntry, CacheConfig, CacheStatistics

• CacheEntry fields – key, value, TTL, tier, health status

• CacheConfig options – per-tier settings, encryption

• CacheTierConfig – max size, TTL, promotion rules

L1/L2/L3 encryption

Cache API Reference

Rate Limiting API

Per-proxy and global rate limiting with token bucket algorithm.

• RateLimiter – constructor, global vs per-proxy limits

• SyncRateLimiter – sync per-proxy configuration

• AsyncRateLimiter – async token bucket check

• Overview – architecture and algorithm details

rate limit token bucket

Rate Limiting API Reference

Database & Migrations

Migrations

Alembic-based database migrations for SQLite schema management.

• Quick start – initialize and run migrations

• Programmatic API – library-first migration control

• Schema versioning – track and roll back schema changes

Alembic SQLite

Database Migrations Guide

---

Related: Guides for usage guides | Getting Started for quickstart | Project for contributing