How Auto Routing Suffixes Work in FreeLLMAPI

Auto routing suffixes are strings appended to the auto: model prefix that instruct the FreeLLMAPI router to either apply a global sorting strategy (such as speed or cost optimization) or route requests to a specific named profile defined in the database.

FreeLLMAPI provides intelligent request routing through its auto: syntax, allowing developers to specify optimization strategies or custom model groups via suffixes. Understanding how these auto routing suffixes function is essential for controlling cost, latency, and quality in production applications. The routing logic resides primarily in server/src/services/router.ts where the resolveRoutingChain function processes these directives according to strict parsing rules.

Parsing the Auto Routing Suffix

When a request arrives with a model string like auto:fast, the router normalizes and processes the directive through a specific parsing sequence.

In server/src/services/router.ts (lines 1235-1236), the system lower-cases the input and strips the auto: prefix, storing the remainder in a variable called suffix. If the suffix is empty—meaning the model string was simply auto—the router immediately returns the active chain, which represents the currently selected profile in the dashboard or the fallback chain if no profile is active (lines 1226-1229).

Global-Sort Suffixes and Optimization Strategies

FreeLLMAPI defines a mapping called GLOBAL_SORT_ALIASES (lines 1103-1109 of router.ts) that translates human-friendly keywords into canonical sort identifiers. These identifiers determine how the system builds a priority chain that orders available models by specific performance axes.

When your suffix matches one of these aliases, the router invokes getChainByGlobalSort (lines 1240-1248) to return a strategy-specific chain tagged with the original request key.

Available Global Sort Options

The router accepts multiple synonyms for each canonical sorting strategy:

• smart (intelligence-first): Accepts smart, smartest, intelligence
• fast (speed-first): Accepts fast, fastest, speed
• cheap (price-first): Accepts cheap, cheapest, price, budget
• reliable (reliability-first): Accepts reliable, reliability
• balanced (default bandit preset): Accepts balanced

For example, using auto:budget resolves to the cheap canonical sort through the alias mapping, prioritizing the lowest-cost available models.

Profile-Named Suffixes for Custom Model Groups

If the suffix does not match any entry in GLOBAL_SORT_ALIASES, the router treats the string as a profile name. The system queries the profiles database table for a record whose name (lower-cased) equals the provided suffix.

If a matching profile exists, the router builds a custom chain via getChainByProfileName (lines 1249-1255) using only the models defined in that profile's profile_models association. This enables users to create arbitrary groupings of models (such as "production-grade" or "experimental") and route to them by name.

The router enforces two validation rules:

• If no profile matches the suffix name, it throws a 400 error with the message "Profile 'xyz' not found..." (lines 1251-1256)
• If the profile exists but contains no enabled models, it raises a similar error indicating the profile is unusable (lines 1258-1262)

Default Behavior and Fallback Chains

When the model parameter is omitted, equals auto, or lacks the auto: prefix entirely, the resolveRoutingChain function (spanning lines 1223-1266) bypasses suffix parsing entirely. Instead, it returns the currently active chain, ensuring continuity with the dashboard-configured default profile.

Practical Implementation Examples

Requesting the Fast Global-Sort Chain

To prioritize response speed over other factors, use the fast suffix:

GET /v1/chat/completions?model=auto:fast HTTP/1.1
Host: api.example.com
Authorization: Bearer <your-token>

The router resolves the suffix fast to the canonical sort fast and returns a chain prioritizing low-latency models.

Targeting Cost Efficiency with Synonyms

You can use budget-focused aliases that map to the cheap canonical sort:

GET /v1/chat/completions?model=auto:budget HTTP/1.1
Host: api.example.com
Authorization: Bearer <your-token>

Here, budget is translated to cheap via GLOBAL_SORT_ALIASES, selecting the most economical available models.

Routing to a Custom Profile

To route through a specific model group defined in your dashboard:

GET /v1/chat/completions?model=auto:my-group HTTP/1.1
Host: api.example.com
Authorization: Bearer <your-token>

Assuming a profile named "my-group" exists with enabled models attached, the router constructs a chain exclusively from that profile's configured models.

Using Default Auto Routing

To rely on the currently active dashboard configuration without explicit sorting:

GET /v1/chat/completions?model=auto HTTP/1.1
Host: api.example.com
Authorization: Bearer <your-token>

This invokes the fallback logic in resolveRoutingChain, using whichever profile is currently active or the system fallback chain.

Summary

• Auto routing suffixes follow the auto: prefix and drive model selection logic in server/src/services/router.ts
• Global-sort suffixes (fast, cheap, smart, etc.) leverage GLOBAL_SORT_ALIASES to prioritize models by performance metrics via getChainByGlobalSort
• Profile-named suffixes route to custom user-defined model groups using getChainByProfileName, requiring the profile to exist and contain enabled models
• Empty or missing suffixes trigger the active chain fallback, maintaining consistency with dashboard settings
• All routing decisions converge in the resolveRoutingChain function (lines 1223-1266), which handles validation, alias resolution, and error states

Frequently Asked Questions

What happens if I specify a profile name that doesn't exist?

The router validates profile-named suffixes against the database in server/src/services/router.ts (lines 1251-1256). If no matching profile is found, the system immediately returns a 400 status code with an error message indicating the profile was not found, preventing the request from proceeding to model selection.

Are auto routing suffixes case-sensitive?

No. According to the parsing logic in router.ts (lines 1235-1236), the router lower-cases the entire model string before processing. This means auto:Fast, auto:FAST, and auto:fast are treated identically, as are profile names like auto:My-Group and auto:my-group.

What is the difference between auto:fast and auto:balanced?

auto:fast invokes the speed-first global sort via getChainByGlobalSort, prioritizing models with the lowest latency regardless of cost or capability. auto:balanced uses the default bandit preset that considers multiple factors simultaneously, offering a compromise between speed, cost, and intelligence rather than optimizing for a single axis.

How does the router handle an empty suffix like auto: or just auto?

When the suffix is empty—either through auto: with nothing following or the bare string auto—the router skips suffix processing and returns the active chain as implemented in lines 1226-1229. This chain represents the currently selected profile in the FreeLLMAPI dashboard, or the system fallback if no profile is active, ensuring predictable behavior when no specific strategy is requested.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}