Configuration¶

All options are set through ApiConfig:

from cocapi import CocApi, ApiConfig

config = ApiConfig(
    timeout=30,
    max_retries=3,
    retry_delay=1.0,
    enable_caching=True,
    cache_ttl=600,
    enable_rate_limiting=True,
    requests_per_second=10.0,
    burst_limit=20,
    enable_metrics=True,
    use_pydantic_models=True,
)

api = CocApi("your_token", config=config)

All Options¶

Option	Type	Default	Description
`base_url`	`str`	`https://api.clashofclans.com/v1`	API base URL
`timeout`	`int`	`20`	Request timeout in seconds
`max_retries`	`int`	`3`	Max retry attempts on failure
`retry_delay`	`float`	`1.0`	Base delay for exponential backoff (seconds)
`cache_ttl`	`int`	`300`	Cache time-to-live in seconds
`enable_caching`	`bool`	`True`	Enable response caching
`enable_rate_limiting`	`bool`	`True`	Enable rate limiting (async only)
`use_pydantic_models`	`bool`	`False`	Return Pydantic models instead of dicts
`requests_per_second`	`float`	`10.0`	Rate limit (async only)
`burst_limit`	`int`	`20`	Burst allowance above rate limit (async only)
`enable_metrics`	`bool`	`False`	Track request metrics
`metrics_window_size`	`int`	`1000`	Number of requests to track
`enable_keepalive`	`bool`	`True`	Enable HTTP keep-alive
`max_connections`	`int`	`10`	Max connections in pool
`max_keepalive_connections`	`int`	`5`	Max keep-alive connections
`key_name`	`str`	`"cocapi_auto"`	Name prefix for managed keys
`key_count`	`int`	`1`	Number of keys to maintain
`key_description`	`str`	`"Auto-generated by cocapi KeyManager"`	Key description on portal
`auto_refresh_keys`	`bool`	`True`	Auto-refresh on `accessDenied.invalidIp`
`persist_keys`	`bool`	`False`	Save API keys locally for reuse
`key_storage_path`	`str \\| None`	`None`	Custom key storage path (default: `~/.cocapi/keys.json`)

Runtime Management¶

# Cache
api.get_cache_stats()
api.clear_cache()

# Metrics
api.get_metrics()
api.clear_metrics()

Custom Endpoints¶

Call new SuperCell endpoints without waiting for a library update:

result = api.custom_endpoint("/new-endpoint")
result = api.custom_endpoint("/clans/search", {"name": "clash", "limit": 10})

# With dynamic Pydantic model
result = api.custom_endpoint("/new-endpoint", use_dynamic_model=True)

Base URL Override¶

For proxies or testing environments:

config = ApiConfig(base_url="https://my-proxy.com/clash/v1")
api = CocApi("token", config=config)

# Or at runtime
api.set_base_url("https://staging.example.com/v1", force=True)
api.reset_base_url()

Warning

Changing the base URL from the official endpoint may cause API failures. Use force=True to suppress the safety warning.