# How Auto Routing Suffixes Work in FreeLLMAPI > Discover how auto routing suffixes in FreeLLMAPI optimize model requests. Learn to use them for global sorting or specific profile routing. Enhance your API performance now. - Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi) - Tags: how-to-guide - Published: 2026-09-01 --- **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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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: ```http GET /v1/chat/completions?model=auto:fast HTTP/1.1 Host: api.example.com Authorization: Bearer ``` 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: ```http GET /v1/chat/completions?model=auto:budget HTTP/1.1 Host: api.example.com Authorization: Bearer ``` 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: ```http GET /v1/chat/completions?model=auto:my-group HTTP/1.1 Host: api.example.com Authorization: Bearer ``` 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: ```http GET /v1/chat/completions?model=auto HTTP/1.1 Host: api.example.com Authorization: Bearer ``` 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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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.