better-ccflare HTTP API Documentation

July 10, 2026 · View on GitHub

Quick Start

# Check health status
curl http://localhost:8080/health

# Proxy a request to Claude
curl -X POST http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-opus-20240229",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 100
  }'

# List all accounts
curl http://localhost:8080/api/accounts

# View dashboard
open http://localhost:8080/dashboard

Overview

better-ccflare provides a RESTful HTTP API for managing accounts, monitoring usage, and proxying requests to Claude. The API runs on port 8080 by default and requires no authentication.

Base URL

http://localhost:8080

Content Type

All API responses are in JSON format with Content-Type: application/json.

Endpoints

Health Check

GET /health

Check the health status of the better-ccflare service.

HTTP status codes:

  • 200 — status: "ok" (routable accounts available)
  • 503 — status: "degraded" (pool empty, accounts will recover) or status: "unhealthy" (runtime broken or no recovery)

Response:

{
  "status": "ok",
  "accounts": 5,
  "timestamp": "2024-12-17T10:30:45.123Z",
  "strategy": "session",
  "pool": {
    "configured": 5,
    "routable": 3,
    "paused": 1,
    "rate_limited": 1,
    "next_available_at": "2024-12-17T11:00:00.000Z"
  }
}

Status values:

  • ok — runtime healthy and at least one account is routable
  • degraded — runtime healthy but pool is empty; next_available_at indicates when the first account recovers
  • unhealthy — runtime broken, no accounts configured, or pool empty with no recovery time

Optional: per-account detail

Set HEALTH_DETAIL_ENABLED=true to enable the ?detail=1 parameter. When disabled (default), ?detail=1 is silently ignored — the full health response is still returned, just without accounts_detail:

curl http://localhost:8080/health?detail=1

{
  "status": "ok",
  "pool": { ... },
  "accounts_detail": [
    { "name": "my-account", "status": "available", "rate_limited_until": null },
    { "name": "other", "status": "rate_limited", "rate_limited_until": 1734429600000 }
  ]
}

Example:

curl http://localhost:8080/health

Claude Proxy

/v1/* (All Methods)

Proxy requests to Claude API. All requests to paths starting with /v1/ are forwarded to Claude using the configured load balancing strategy. This includes POST, GET, and any other HTTP methods that Claude's API supports.

Supported Endpoints:

  • POST /v1/messages - Native Anthropic messages endpoint
  • POST /v1/responses - OpenAI Responses API compatibility endpoint (translated to /v1/messages)
  • POST /v1/responses/compact - Compact Responses API compatibility endpoint (translated to /v1/messages)
  • POST /v1/complete - Text completion (legacy)
  • Any other Claude API v1 endpoint

Codex CLI as a Client: Codex CLI (and other OpenAI Responses API clients) can target better-ccflare directly. Requests to /v1/responses and /v1/responses/compact are intercepted before the normal proxy and translated to Anthropic /v1/messages internally, then routed through the account pool like any other request. See the README for configuration details.

Note: this is distinct from the codex provider, which routes requests outbound to OpenAI's Codex endpoint.

Known Limitations (/v1/responses):

  • previous_response_id is accepted but ignored — better-ccflare is stateless and does not store prior responses. Codex uses this field only over WebSocket (which better-ccflare does not implement); for regular HTTP requests Codex always sends the full conversation history in input, so this field has no effect.
  • Built-in tool types (web_search_preview, code_interpreter, file_search) are silently skipped; only type: "function" tools are forwarded to Anthropic.

Note: GET /v1/models is proxied through to Claude like any other /v1/* request. A successful response (from a console/API-key account) is also passively captured into better-ccflare's own model catalog cache — see Model Catalog below for the read endpoint (GET /api/models) and how the catalog is kept up to date.

Headers:

  • All standard Claude API headers are supported
  • Authorization header is managed by better-ccflare (no need to provide)

Request Body: Same as Claude API requirements for the specific endpoint.

Response: Proxied response from Claude API, including streaming responses.

Automatic Failover: If a request fails or an account is rate limited, better-ccflare automatically retries with the next available account according to the configured load balancing strategy. This ensures high availability and reliability.

Example:

curl -X POST http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-opus-20240229",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 100
  }'

Account Management

GET /api/accounts

List all configured accounts with their current status.

Response:

[
  {
    "id": "uuid-here",
    "name": "account1",
    "provider": "anthropic",
    "requestCount": 150,
    "totalRequests": 1500,
    "lastUsed": "2024-12-17T10:25:30.123Z",
    "created": "2024-12-01T08:00:00.000Z",
    "priority": 50,
    "paused": false,
    "tokenStatus": "valid",
    "rateLimitStatus": "allowed_warning (5m)",
    "rateLimitReset": "2024-12-17T10:30:00.000Z",
    "rateLimitRemaining": 100,
    "sessionInfo": "Session: 25 requests",
    "autoFallbackEnabled": false
  }
]

Example:

curl http://localhost:8080/api/accounts

OAuth Flow

POST /api/oauth/init

Initialize OAuth flow for adding a new account.

Request:

{
  "name": "myaccount",
  "mode": "claude-oauth",  // "claude-oauth" or "console" (default: "claude-oauth")
  "priority": 50  // 0-100, lower value = higher priority (optional, defaults: 0)
}

Response:

{
  "success": true,
  "authUrl": "https://console.anthropic.com/oauth/authorize?...",
  "sessionId": "uuid-here",
  "step": "authorize"
}

Example:

curl -X POST http://localhost:8080/api/oauth/init \
  -H "Content-Type: application/json" \
  -d '{"name": "myaccount", "mode": "claude-oauth"}'

POST /api/oauth/callback

Complete OAuth flow after user authorization.

Request:

{
  "sessionId": "uuid-from-init-response",
  "code": "authorization-code-from-oauth"
}

Response:

{
  "success": true,
  "message": "Account 'myaccount' added successfully!",
  "mode": "Claude CLI",
  "priority": 50
}

Example:

curl -X POST http://localhost:8080/api/oauth/callback \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "uuid-here", "code": "auth-code"}'

Account Management

DELETE /api/accounts/:accountId

Remove an account. Requires confirmation.

Request:

{
  "confirm": "account-name"
}

Response:

{
  "success": true,
  "message": "Account 'account-name' removed successfully"
}

Example:

curl -X DELETE http://localhost:8080/api/accounts/uuid-here \
  -H "Content-Type: application/json" \
  -d '{"confirm": "myaccount"}'

POST /api/accounts/:accountId/priority

Update account priority. Lower priority values increase the likelihood of the account being selected by the load balancer.

Request:

{
  "priority": 75  // 0-100, lower value = higher priority
}

Response:

{
  "success": true,
  "priority": 75
}

Example:

curl -X POST http://localhost:8080/api/accounts/uuid-here/priority \
  -H "Content-Type: application/json" \
  -d '{"priority": 75}'

How Priorities Work:

  • Priority values range from 0 to 100
  • Lower values indicate higher priority in load balancing
  • Priority is optional and defaults to 0 (highest priority) if not specified
  • Priority affects both primary account selection and fallback order
  • Changes take effect immediately without restarting the server

POST /api/accounts/:accountId/auto-fallback

Enable or disable auto-fallback for an account. When enabled, the system will automatically switch back to this account when its usage window resets and it has higher priority than the currently active account.

Important: Auto-fallback is only available for Anthropic accounts since only they provide rate limit reset information via the API. Attempts to enable auto-fallback on non-Anthropic accounts will result in an error.

Request:

{
  "enabled": 1  // 1 to enable, 0 to disable
}

Response:

{
  "success": true,
  "message": "Auto-fallback enabled for account 'myaccount'",
  "autoFallbackEnabled": true
}

Example:

# Enable auto-fallback
curl -X POST http://localhost:8080/api/accounts/uuid-here/auto-fallback \
  -H "Content-Type: application/json" \
  -d '{"enabled": 1}'

# Disable auto-fallback
curl -X POST http://localhost:8080/api/accounts/uuid-here/auto-fallback \
  -H "Content-Type: application/json" \
  -d '{"enabled": 0}'

How Auto-Fallback Works:

  • Auto-fallback is a per-account setting that defaults to disabled
  • When enabled, the system monitors the account's API rate limit reset time
  • If the account becomes available (usage window resets) and has higher priority than the current active account, the system automatically switches to it
  • The system logs when auto-fallback is triggered for transparency
  • Only accounts that are not paused and not currently rate limited will be considered for auto-fallback

Use Cases:

  • Primary Account Recovery: Automatically switch back to your main account as soon as its rate limit window resets
  • Cost Optimization: Prioritize lower-cost accounts when they become available
  • Performance Management: Automatically use higher-performance accounts when they're ready
  • Tiered Access: Ensure priority accounts get used first when available

POST /api/accounts/:accountId/pause

Pause an account temporarily.

Response:

{
  "success": true,
  "message": "Account 'myaccount' paused"
}

Example:

curl -X POST http://localhost:8080/api/accounts/uuid-here/pause

POST /api/accounts/:accountId/force-reset-rate-limit

Force-clear persisted rate-limit lock state for an account and trigger immediate usage polling when possible.

What it does:

  • Clears rate_limited_until
  • Clears rate_limit_reset
  • Clears rate_limit_status
  • Clears rate_limit_remaining
  • Triggers immediate usage poll for the account (if polling is configured in-process)

Response:

{
  "success": true,
  "message": "Rate limit state cleared for account 'myaccount'",
  "usagePollTriggered": true
}

Example:

curl -X POST http://localhost:8080/api/accounts/uuid-here/force-reset-rate-limit

POST /api/accounts/:accountId/resume

Resume a paused account.

Response:

{
  "success": true,
  "message": "Account 'myaccount' resumed"
}

Example:

curl -X POST http://localhost:8080/api/accounts/uuid-here/resume

Statistics

GET /api/stats

Get overall usage statistics.

Response:

{
  "totalRequests": 5000,
  "successRate": 98.5,
  "activeAccounts": 4,
  "avgResponseTime": 1250.5,
  "totalTokens": 1500000,
  "totalCostUsd": 125.50,
  "avgTokensPerSecond": null,
  "topModels": [
    {"model": "claude-3-opus-20240229", "count": 3000},
    {"model": "claude-3-sonnet-20240229", "count": 2000}
  ]
}

Example:

curl http://localhost:8080/api/stats

POST /api/stats/reset

Reset all usage statistics.

Response:

{
  "success": true,
  "message": "Statistics reset successfully"
}

Example:

curl -X POST http://localhost:8080/api/stats/reset

Request History

GET /api/requests

Get recent request summary.

Query Parameters:

  • limit - Number of requests to return (default: 50)

Response:

[
  {
    "id": "request-uuid",
    "timestamp": "2024-12-17T10:30:45.123Z",
    "method": "POST",
    "path": "/v1/messages",
    "accountUsed": "account1",
    "statusCode": 200,
    "success": true,
    "errorMessage": null,
    "responseTimeMs": 1234,
    "failoverAttempts": 0,
    "model": "claude-3-opus-20240229",
    "promptTokens": 50,
    "completionTokens": 100,
    "totalTokens": 150,
    "inputTokens": 50,
    "outputTokens": 100,
    "cacheReadInputTokens": 0,
    "cacheCreationInputTokens": 0,
    "costUsd": 0.0125,
    "agentUsed": null,
    "tokensPerSecond": null
  }
]

Example:

curl "http://localhost:8080/api/requests?limit=100"

GET /api/requests/detail

Get detailed request information including payloads. Request and response bodies are base64-encoded to handle binary data and special characters.

Query Parameters:

  • limit - Number of requests to return (default: 100)

Response:

[
  {
    "id": "request-uuid",
    "timestamp": "2024-12-17T10:30:45.123Z",
    "method": "POST",
    "path": "/v1/messages",
    "accountUsed": "account1",
    "statusCode": 200,
    "success": true,
    "payload": {
      "request": {
        "headers": {...},
        "body": "base64-encoded-body"
      },
      "response": {
        "status": 200,
        "headers": {...},
        "body": "base64-encoded-body"
      },
      "meta": {
        "accountId": "uuid",
        "accountName": "account1",
        "retry": 0,
        "timestamp": 1234567890,
        "success": true,
        "rateLimited": false,
        "accountsAttempted": 1
      }
    }
  }
]

Example:

curl "http://localhost:8080/api/requests/detail?limit=10"

Configuration

GET /api/config

Get current configuration.

Response:

{
  "lb_strategy": "session",
  "port": 8080,
  "sessionDurationMs": 18000000
}

Example:

curl http://localhost:8080/api/config

GET /api/config/strategy

Get current load balancing strategy.

Response:

{
  "strategy": "session"
}

Example:

curl http://localhost:8080/api/config/strategy

POST /api/config/strategy

Update load balancing strategy.

Request:

{
  "strategy": "session"
}

Response:

{
  "success": true,
  "strategy": "session"
}

Available Strategies:

  • session - Session-based routing that maintains 5-hour sessions with individual accounts to avoid rate limits and account bans

⚠️ WARNING: Only the session strategy is supported. Other strategies have been removed as they can trigger Claude's anti-abuse systems.

Example:

curl -X POST http://localhost:8080/api/config/strategy \
  -H "Content-Type: application/json" \
  -d '{"strategy": "session"}'

GET /api/strategies

List all available load balancing strategies.

Response:

["session"]

Example:

curl http://localhost:8080/api/strategies

Analytics

GET /api/analytics

Get detailed analytics data.

Query Parameters:

  • range - Time range: 1h, 6h, 24h, 7d, 30d (default: 24h)
  • accounts - Filter by account names (comma-separated list)
  • models - Filter by model names (comma-separated list)
  • apiKeys - Filter by API key names (comma-separated list)
  • status - Filter by request status: all, success, error (default: all)
  • mode - Display mode: normal, cumulative (default: normal). Cumulative mode shows running totals over time
  • modelBreakdown - Include per-model time series data: true, false (default: false)

Response:

{
  "meta": {
    "range": "24h",
    "bucket": "1h",
    "cumulative": false
  },
  "totals": {
    "requests": 5000,
    "successRate": 98.5,
    "activeAccounts": 4,
    "avgResponseTime": 1250.5,
    "totalTokens": 1500000,
    "totalCostUsd": 125.50,
    "avgTokensPerSecond": null
  },
  "timeSeries": [
    {
      "ts": 1734430800000,
      "requests": 100,
      "tokens": 15000,
      "costUsd": 1.25,
      "successRate": 98,
      "errorRate": 2,
      "cacheHitRate": 15,
      "avgResponseTime": 1200,
      "avgTokensPerSecond": null
    }
  ],
  "tokenBreakdown": {
    "inputTokens": 500000,
    "cacheReadInputTokens": 100000,
    "cacheCreationInputTokens": 50000,
    "outputTokens": 850000
  },
  "modelDistribution": [
    {"model": "claude-3-opus-20240229", "count": 3000}
  ],
  "accountPerformance": [
    {"name": "account1", "requests": 2500, "successRate": 99}
  ],
  "apiKeyPerformance": [
    {"id": "key-123", "name": "Production App", "requests": 1500, "successRate": 99.5}
  ],
  "costByModel": [
    {"model": "claude-3-opus-20240229", "costUsd": 100.50, "requests": 3000, "totalTokens": 1200000}
  ],
  "modelPerformance": [
    {
      "model": "claude-3-opus-20240229",
      "avgResponseTime": 1300,
      "p95ResponseTime": 2500,
      "errorRate": 1.5,
      "avgTokensPerSecond": null,
      "minTokensPerSecond": null,
      "maxTokensPerSecond": null
    }
  ]
}

Examples:

# Basic analytics for last 7 days
curl "http://localhost:8080/api/analytics?range=7d"

# Analytics filtered by specific accounts
curl "http://localhost:8080/api/analytics?range=24h&accounts=account1,account2"

# Analytics for specific models with success status only
curl "http://localhost:8080/api/analytics?range=24h&models=claude-3-opus-20240229,claude-3-sonnet-20240229&status=success"

# Analytics filtered by API keys
curl "http://localhost:8080/api/analytics?range=24h&apiKeys=Production%20App,Development%20App"

# Combined filters (accounts, models, API keys, and status)
curl "http://localhost:8080/api/analytics?range=7d&accounts=premium1,premium2&models=claude-3-opus-20240229&apiKeys=Production%20App&status=error"

Agent Management

GET /api/agents

List all available agents with their preferences.

Response:

{
  "agents": [
    {
      "id": "agent-uuid",
      "name": "code-reviewer",
      "description": "Reviews code for quality and best practices",
      "model": "claude-3-5-sonnet-20241022",
      "source": "global",
      "workspace": null
    }
  ],
  "globalAgents": [...],
  "workspaceAgents": [...],
  "workspaces": [
    {
      "name": "my-workspace",
      "path": "/path/to/workspace"
    }
  ]
}

Example:

curl http://localhost:8080/api/agents

POST /api/agents/:agentId/preference

Update model preference for a specific agent.

Request:

{
  "model": "claude-3-5-sonnet-20241022"
}

Response:

{
  "success": true,
  "agentId": "agent-uuid",
  "model": "claude-3-5-sonnet-20241022"
}

Example:

curl -X POST http://localhost:8080/api/agents/agent-uuid/preference \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-3-5-sonnet-20241022"}'

DELETE /api/agents/:agentId/preference

Remove an agent's model preference, reverting it to its default (the agent's frontmatter model, or the session model if it has none).

Response:

{
  "success": true,
  "agentId": "agent-uuid",
  "deleted": true
}

Example:

curl -X DELETE http://localhost:8080/api/agents/agent-uuid/preference

PATCH /api/agents/:agentId

Update an agent's configuration. Changes are written to the agent's .md file.

Request: (all fields optional)

{
  "description": "Reviews code for quality and best practices",
  "model": "claude-3-5-sonnet-20241022",
  "tools": ["Read", "Edit"],
  "color": "blue",
  "systemPrompt": "You are a code reviewer...",
  "mode": "edit"
}

model accepts a valid model id, null, or the string "inherit" (case-insensitive); the latter two remove the model: key from the agent file so it inherits the session model. Side effect: including model in the request body at all — even to set it to null — clears the agent's runtime model preference (see POST/DELETE /api/agents/:agentId/preference above), so the two override mechanisms don't end up conflicting.

Response:

{
  "success": true,
  "agent": { ... }
}

Example:

curl -X PATCH http://localhost:8080/api/agents/agent-uuid \
  -H "Content-Type: application/json" \
  -d '{"model": null}'

GET /api/workspaces

List all available workspaces with agent counts.

Response:

{
  "workspaces": [
    {
      "name": "my-workspace",
      "path": "/path/to/workspace",
      "agentCount": 5
    }
  ]
}

Example:

curl http://localhost:8080/api/workspaces

Model Catalog

GET /api/models

Return the cached Anthropic model catalog used to populate model dropdowns (dashboard agent/default-model selects). Returns the live catalog if a successful fetch has occurred (scheduled refresh, manual refresh, or passive capture from a proxied GET /v1/models); otherwise the bundled static fallback shipped with better-ccflare.

Response:

{
  "models": [
    { "id": "claude-sonnet-5", "displayName": "Claude Sonnet 5", "createdAt": "2026-01-15T00:00:00Z" }
  ],
  "fetchedAt": 1751270400000,
  "source": "live"
}

source is "live" when the catalog came from a real Anthropic response, or "fallback" when no live fetch has ever succeeded and the bundled model list is being served instead (fetchedAt is then the bundled list's snapshot date, not the current time — see Model Catalog in the configuration guide).

Example:

curl http://localhost:8080/api/models

POST /api/models/refresh

Force an immediate live model catalog refresh, bypassing the scheduled interval. Prefers a console/API-key account but falls back to an OAuth account if BETTER_CCFLARE_MODELS_OAUTH_REFRESH (or the equivalent config toggle) is enabled. Never throws — always returns 200 with the outcome, even on failure (e.g. no eligible account, network error).

Response:

{
  "success": true,
  "catalog": {
    "models": [ ... ],
    "fetchedAt": 1751270400000,
    "source": "live"
  }
}

On failure, success is false and an error field describes the reason; catalog still reflects the current (unchanged) cached catalog.

Example:

curl -X POST http://localhost:8080/api/models/refresh

Logs

GET /api/logs/stream

Stream real-time logs via Server-Sent Events (SSE).

Response: SSE stream with log events

Example:

curl -N http://localhost:8080/api/logs/stream

GET /api/logs/history

Get historical logs.

Response:

[
  {
    "timestamp": "2024-12-17T10:30:45.123Z",
    "level": "info",
    "component": "proxy",
    "message": "Request completed",
    "metadata": {...}
  }
]

Example:

curl http://localhost:8080/api/logs/history

Error Handling

All API errors follow a consistent format:

{
  "error": "Error message",
  "details": {
    // Optional additional error details
  }
}

Common Status Codes

  • 200 OK - Request successful
  • 400 Bad Request - Invalid request parameters
  • 404 Not Found - Resource not found
  • 429 Too Many Requests - Rate limited
  • 500 Internal Server Error - Server error
  • 502 Bad Gateway - Upstream provider error
  • 503 Service Unavailable - All accounts failed

Rate Limiting

When an account hits rate limits, better-ccflare automatically fails over to the next available account. If all accounts are rate limited, a 503 error is returned.

Rate limit information is included in account responses:

  • rateLimitStatus - Current status (e.g., "allowed", "allowed_warning", "rate_limited")
  • rateLimitReset - When the rate limit resets
  • rateLimitRemaining - Remaining requests (if available)

Streaming Responses

The proxy endpoints support streaming responses for compatible Claude API calls. When making a streaming request:

  1. Include "stream": true in your request body
  2. The response will be Content-Type: text/event-stream
  3. Each chunk is delivered as a Server-Sent Event

Streaming Response Capture: better-ccflare automatically captures streaming response bodies for analytics and debugging purposes:

  • Captured data is limited to CF_STREAM_BODY_MAX_BYTES (default: 256KB)
  • The capture process doesn't interfere with the client's stream
  • Captured bodies are stored base64-encoded in the request history
  • If the response exceeds the size limit, it's marked as truncated in metadata

Example:

curl -X POST http://localhost:8080/v1/messages \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-opus-20240229",
    "messages": [{"role": "user", "content": "Write a poem"}],
    "max_tokens": 100,
    "stream": true
  }'

Dashboard

A web dashboard is available at:

http://localhost:8080/dashboard
http://localhost:8080/          # Redirects to /dashboard

The dashboard provides a visual interface for:

  • Monitoring account status and usage
  • Viewing real-time analytics
  • Managing configuration
  • Examining request history

Configuration

Environment Variables

better-ccflare can be configured using the following environment variables:

  • PORT - Server port (default: 8080)
  • LB_STRATEGY - Load balancing strategy (default: session)
  • SESSION_DURATION_MS - Session duration in milliseconds (default: 18000000 / 5 hours)
  • CLIENT_ID - OAuth client ID for Anthropic authentication (default: 9d1c250a-e61b-44d9-88ed-5944d1962f5e)
  • CF_STREAM_BODY_MAX_BYTES - Maximum bytes to capture from streaming responses (default: 262144 / 256KB)
  • RETRY_ATTEMPTS - Number of retry attempts for failed requests (default: 3)
  • RETRY_DELAY_MS - Initial delay between retries in milliseconds (default: 1000)
  • RETRY_BACKOFF - Exponential backoff multiplier for retries (default: 2)
  • BETTER_CCFLARE_MODELS_REFRESH_HOURS - Hours between scheduled model catalog refreshes, 0 disables scheduled refresh (default: 168 / 7 days). See Model Catalog.
  • BETTER_CCFLARE_MODELS_OFFLINE - Disable scheduled/manual model catalog refresh and passive /v1/models capture (default: unset)
  • BETTER_CCFLARE_MODELS_CACHE_DIR - Directory for the persisted model catalog cache file (default: platform config dir)
  • BETTER_CCFLARE_MODELS_OAUTH_REFRESH - Allow OAuth accounts as a fallback source for manual model catalog refreshes (default: unset / console-only)

Configuration File

In addition to environment variables, better-ccflare supports configuration through a JSON file. The config file location varies by platform:

  • macOS: ~/Library/Application Support/better-ccflare/config.json
  • Linux: ~/.config/better-ccflare/config.json
  • Windows: %APPDATA%\better-ccflare\config.json

Supported Configuration Keys:

{
  "lb_strategy": "session",
  "client_id": "your-oauth-client-id",
  "retry_attempts": 3,
  "retry_delay_ms": 1000,
  "retry_backoff": 2,
  "session_duration_ms": 18000000,
  "port": 8080,
  "stream_body_max_bytes": 262144
}

Note: Environment variables take precedence over config file settings.

Load Balancing Strategies

The following strategy is available:

  • session - Session-based routing that maintains 5-hour sessions with individual accounts

⚠️ WARNING: Only use the session strategy. Other strategies can trigger Claude's anti-abuse systems and result in account bans.

Notes

  1. No Authentication: The API endpoints do not require authentication. better-ccflare manages the OAuth tokens internally for proxying to Claude.

  2. Automatic Failover: When a request fails or an account is rate limited, better-ccflare automatically tries the next available account. If no accounts are available, requests are forwarded without authentication as a fallback.

  3. Token Refresh: Access tokens are automatically refreshed when they expire.

  4. Request Logging: All requests are logged with detailed metrics including tokens used, cost, and response times. Database writes are performed asynchronously to avoid blocking request processing.

  5. Account Priority System: Accounts can have different priority values (0-100) which determine their order in load balancing.

  6. Session Affinity: The "session" strategy maintains sticky sessions for consistent routing within a time window.

  7. Rate Limit Tracking: Rate limit information is automatically extracted from responses and stored for each account, including reset times and remaining requests.

  8. Provider Filtering: Accounts are automatically filtered by provider when selecting for requests, ensuring compatibility.