How to Specify a Profile Per Request in FreeLLMAPI: Syntax and Implementation

You specify a profile per request in FreeLLMAPI by adding a profile query-string parameter to the API endpoint URL, which overrides the globally active profile stored in the database settings.

FreeLLMAPI supports dynamic model fallback chains through profiles—configurable sets of enabled models and system prompts. According to the tashfeenahmed/freellmapi source code, you can override the default active profile on a per-request basis without changing global server settings.

Understanding Profile Routing in FreeLLMAPI

A profile in FreeLLMAPI represents a prioritized list of AI models with optional system prompts. When you send a request, the router must determine which profile's model chain to use. The system checks for an explicit profile parameter first, then falls back to the active profile ID stored in the SQLite settings table under the key active_profile_id.

Syntax for Specifying a Profile Per Request

Query String Parameter Method

Append ?profile=<name> to any chat completions endpoint to force the router to use that specific profile's model configuration.

POST https://api.free-llmapi.com/v1/chat/completions?profile=creative
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "model": "gpt-4o-mini",
  "messages": [{ "role": "user", "content": "Write a haiku about sunrise." }]
}

In this request, the server extracts the value creative and queries the profiles table to resolve the name to an internal ID before building the model fallback chain.

How the Server Processes Profile Selection

Profile Lookup by Name

When you provide the profile parameter, the server validates it against the database. In server/src/routes/profiles.ts (lines 115-120), the lookup executes a case-insensitive query:

SELECT id FROM profiles WHERE LOWER(name) = ?

If the profile exists, the router uses this ID to filter enabled models. If omitted, the system proceeds to the active profile fallback.

Active Profile Fallback

The default behavior relies on getActiveProfileId() implemented in server/src/services/profile-models.ts (lines 4-9). This function queries the settings table:

SELECT value FROM settings WHERE key = 'active_profile_id'

When no profile parameter exists in the request URL, the router uses this globally configured ID to determine model priority.

Model Chain Construction

The actual routing logic resides in server/src/services/router.ts (lines 1122-1185). Here, the system joins the profile_models table using the resolved profile ID. The query in server/src/services/profile-models.ts (lines 43-49) performs a LEFT JOIN to retrieve only models enabled for that specific profile, ordered by priority:

LEFT JOIN profile_models pm ON m.id = pm.model_id AND pm.profile_id = ?

This ensures requests use only the models explicitly allowed within the specified profile.

Examples of Profile Specification

Using a Named Profile

Specify the profile explicitly to ensure consistent model selection regardless of global settings:

POST https://api.free-llmapi.com/v1/chat/completions?profile=enterprise
Content-Type: application/json
Authorization: Bearer sk-xxx

{
  "model": "claude-3-sonnet",
  "messages": [{ "role": "user", "content": "Analyze Q3 financials." }]
}

The router checks the profiles table for a row named "enterprise" and builds the fallback chain using only models linked to that profile ID.

Using the Default Active Profile

Omit the parameter to use the currently active profile:

POST https://api.free-llmapi.com/v1/chat/completions
Content-Type: application/json
Authorization: Bearer sk-xxx

{
  "model": "gpt-4o-mini",
  "messages": [{ "role": "user", "content": "Explain quantum entanglement." }]
}

Without the profile query string, getActiveProfileId() reads from settings.active_profile_id to determine the model chain.

Changing the Active Profile (Admin Only)

Administrators can update the global default so all subsequent parameter-less requests use a new profile:

POST https://api.free-llmapi.com/api/profiles/active
Content-Type: application/json
Authorization: Bearer ADMIN_API_KEY

{ "profileId": 3 }

After executing this against the profiles endpoint, the server updates settings.active_profile_id to 3, affecting all future requests that do not specify a profile parameter.

Summary

• Per-request syntax: Append ?profile=<name> to the API URL to override the global active profile.
• Fallback behavior: When the parameter is missing, the system uses getActiveProfileId() from server/src/services/profile-models.ts to read settings.active_profile_id.
• Resolution flow: router.ts extracts the parameter, profiles.ts validates the name, and profile-models.ts constructs the enabled model chain.
• Admin control: The active profile default can be changed via the /api/profiles/active endpoint, but per-request parameters take precedence.

Frequently Asked Questions

What happens if the profile parameter is invalid?

If the profile query string specifies a name not found in the database, the lookup in server/src/routes/profiles.ts returns no results. The server typically falls back to the active profile or returns a 404 error depending on the router's error handling configuration in server/src/services/router.ts.

Can I switch profiles mid-conversation?

Yes. Each request is stateless regarding profile selection. You can send the first request with ?profile=technical and the next with ?profile=creative, or omit the parameter entirely. The profile applies per request, not per conversation thread.

Is the profile parameter case-sensitive?

No. The lookup query in server/src/routes/profiles.ts (lines 115-120) uses LOWER(name) = ?, converting both the stored profile name and the input parameter to lowercase before comparison. However, using the exact case defined in your profile configuration is recommended for clarity.

Do I need admin privileges to use custom profiles?

No. Any valid API key can use the profile query parameter to select available profiles. Admin privileges are only required to modify the global active profile via the /api/profiles/active endpoint or to create and delete profiles in the system.

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