# How free-claude-code Handles FastAPI Request Detection and Routing: A Complete Technical Guide

> Discover how free-claude-code handles FastAPI request detection and routing. Learn about pure-Python helpers for instant vs. streamed responses in this technical guide.

- Repository: [Ali Khokhar/free-claude-code](https://github.com/Alishahryar1/free-claude-code)
- Tags: deep-dive
- Published: 2026-04-24

---

**The free-claude-code FastAPI application inspects every incoming `/v1/messages` request using pure-Python detection helpers in [`api/detection.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/detection.py) to determine whether it can be answered instantly via fast-path optimizations or must be streamed from an external LLM provider.**

The `free-claude-code` repository implements a high-performance proxy service built with FastAPI that minimizes latency for common Claude client operations. Understanding how this FastAPI application handles request detection and routing reveals an elegant three-layer architecture that prioritizes sub-millisecond responses for probe requests while seamlessly falling back to external providers for genuine LLM queries.

## Receiving Requests at the `/v1/messages` Endpoint

All client traffic enters through the **`create_message`** function defined in **[`api/routes.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/routes.py)** (lines 70-78). This async endpoint accepts a `MessagesRequest` Pydantic model and validates authentication via the `require_api_key` dependency.

```python
async def create_message(
    request_data: MessagesRequest,
    raw_request: Request,
    settings: Settings = Depends(get_settings),
    _auth=Depends(require_api_key),
):

```

Once the request payload is parsed and validated, the function immediately delegates to the optimization layer. If no fast-path handler matches, it proceeds to resolve the appropriate LLM provider and stream the response.

## The Detection Layer: Pattern Matching in [`api/detection.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/detection.py)

Before any external API calls occur, the service attempts to classify the request using five specialized detection helpers located in **[`api/detection.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/detection.py)**. These pure-Python functions inspect the `MessagesRequest` payload for specific patterns that indicate the client is performing metadata operations rather than seeking LLM-generated content.

**`is_quota_check_request`** (lines 12-26) identifies single-message requests where `max_tokens` equals 1 and the content contains the string "quota". This pattern indicates the Claude client is performing a network probe to verify API access.

**`is_title_generation_request`** (lines 29-38) detects system prompts mentioning "new conversation topic" and "title", which triggers when the client auto-generates conversation titles.

**`is_prefix_detection_request`** (lines 41-62) extracts command strings from user messages containing `<policy_spec>` tags followed by a `Command:` block, returning the command for instant echo responses.

**`is_suggestion_mode_request`** (lines 65-77) scans for the marker `[SUGGESTION MODE:` in user messages, identifying a specific Claude client interaction pattern that can be short-circuited.

**`is_filepath_extraction_request`** (lines 79-110) parses messages containing both `Command:` and `Output:` sections with file-path cues, extracting the command and output strings for mock responses.

## The Optimization Layer: Fast-Path Handlers

When the endpoint receives a request, it calls **`try_optimizations`** from **[`api/optimization_handlers.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/optimization_handlers.py)** before hitting any external provider. This function iterates over a static ordered list of handler functions (lines 29-36), executing the cheapest and most common checks first to enable early short-circuiting.

Each handler follows a consistent three-step pattern:

1. Verify the corresponding **feature flag** from [`config/settings.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/config/settings.py) (such as `settings.fast_prefix_detection` or `settings.enable_network_probe_mock`) is enabled.
2. Invoke the appropriate detection helper from [`api/detection.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/detection.py).
3. If a match exists, construct and return a pre-crafted `MessagesResponse` object.

The handler list includes:

- **`try_prefix_detection`** (lines 25-44): Returns an echo response containing the extracted command prefix.
- **`try_quota_mock`** (lines 46-64): Returns "Quota check passed." for probe requests.
- **`try_title_skip`** (lines 66-84): Returns a generic title response to avoid LLM overhead.
- **`try_suggestion_skip`** (lines 86-104): Returns an empty suggestion response.
- **`try_filepath_mock`** (lines 66-76): Returns the extracted file path as the response content.

If any handler returns a `MessagesResponse` object, the endpoint immediately sends it as the HTTP response, achieving **sub-millisecond latency** for these common probe operations.

## Routing to External Providers

When `try_optimizations` returns `None`, indicating no fast-path pattern matched, the endpoint proceeds to the provider routing logic in **[`api/routes.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/routes.py)** (lines 88-102).

```python
provider_type = Settings.parse_provider_type(
    request_data.resolved_provider_model or settings.model
)
provider = get_provider_for_type(provider_type)

```

The `parse_provider_type` method converts model names like `claude-3-opus-20240229` into internal provider enums, while `get_provider_for_type` (defined in **[`api/dependencies.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/dependencies.py)**) returns a provider instance implementing the `stream_response` interface.

The request is then wrapped in a `StreamingResponse`:

```python
return StreamingResponse(
    provider.stream_response(
        request_data,
        input_tokens=input_tokens,
        request_id=request_id,
    ),
    media_type="text/event-stream",
)

```

This streams Server-Sent Events from the external LLM provider back to the client, maintaining full compatibility with the Claude API specification.

## Application Bootstrap and Lifecycle

The FastAPI application factory resides in **[`api/app.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/app.py)**, where the lifespan context manager initializes optional messaging platforms (Telegram, Discord) and stores them in `app.state`. The core routing is attached via:

```python
app.include_router(router)  # Lines 104-106

```

This wires the detection-to-optimization-to-provider flow into the FastAPI lifecycle at application startup.

## Practical Implementation Examples

The following examples demonstrate how the detection and routing logic processes different request types.

### Example 1: Quota Probe (Instant Response)

```bash
curl -X POST https://my-proxy/v1/messages \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "claude-3-opus-20240229",
        "max_tokens": 1,
        "messages": [{"role":"user","content":"quota"}]
      }'

```

Because `max_tokens` equals 1 and the message contains "quota", `is_quota_check_request` returns `True`. The `try_quota_mock` handler creates an instant response with **"Quota check passed."**, bypassing the external provider entirely.

### Example 2: Prefix Detection (Fast-Path)

```bash
curl -X POST https://my-proxy/v1/messages \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "claude-3-sonnet-20241022",
        "messages": [{
          "role":"user",
          "content":"<policy_spec>…</policy_spec>\nCommand: echo hello"
        }]
      }'

```

The `is_prefix_detection_request` helper extracts `echo hello`, triggering `try_prefix_detection` to return a response where `content[0]["text"]` contains the command prefix. No LLM provider is contacted.

### Example 3: Normal LLM Query (Provider Stream)

```bash
curl -X POST https://my-proxy/v1/messages \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "claude-3-opus-20240229",
        "messages": [{"role":"user","content":"Explain quantum entanglement"}]
      }'

```

No detection rule matches this generic query. The request routes to the configured provider (OpenRouter, OpenAI-compatible, or LMStudio) and streams back via `StreamingResponse`.

## Summary

- The **`create_message`** endpoint in [`api/routes.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/routes.py) serves as the entry point, delegating to the optimization layer before attempting provider routing.
- **[`api/detection.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/detection.py)** contains five pure-Python helpers that classify requests into patterns like quota checks, title generation, and command extraction.
- **[`api/optimization_handlers.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/optimization_handlers.py)** implements `try_optimizations`, which runs an ordered list of fast-path handlers gated by feature flags from [`config/settings.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/config/settings.py).
- Fast-path responses achieve sub-millisecond latency by returning pre-crafted `MessagesResponse` objects without external API calls.
- Unmatched requests flow through `Settings.parse_provider_type` and `get_provider_for_type` to stream responses from external LLM providers as Server-Sent Events.

## Frequently Asked Questions

### What triggers the fast-path optimization in free-claude-code?

Fast-path optimization triggers when a request matches one of five detection patterns implemented in [`api/detection.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/detection.py). The system checks for quota probes (`max_tokens=1` with "quota" content), title generation prompts, prefix detection with `<policy_spec>` tags, suggestion mode markers, or filepath extraction blocks. If the corresponding feature flag in [`config/settings.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/config/settings.py) is enabled and the pattern matches, the optimization handler returns an instant response.

### How does the detection layer identify quota check requests?

The **`is_quota_check_request`** function (lines 12-26 in [`api/detection.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/detection.py)) identifies quota checks by verifying two conditions: the request contains exactly one message, and that message has `max_tokens` set to 1 with content including the string "quota". This pattern indicates the Claude client is performing a network connectivity probe rather than requesting generated content.

### What happens when no optimization pattern matches?

When `try_optimizations` returns `None`, the endpoint resolves the provider using `Settings.parse_provider_type` and retrieves the provider instance via `get_provider_for_type` from [`api/dependencies.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/dependencies.py). The request is then wrapped in a `StreamingResponse` with `media_type="text/event-stream"`, which streams the LLM response from the external provider back to the client using Server-Sent Events.

### Where are the feature flags for optimizations configured?

Feature flags such as `fast_prefix_detection`, `enable_network_probe_mock`, and others are defined in **[`config/settings.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/config/settings.py)**. Each optimization handler in [`api/optimization_handlers.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/optimization_handlers.py) checks its corresponding flag before executing the detection logic, allowing operators to enable or disable specific fast-path behaviors via environment variables or configuration files.