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

> Learn how to specify a profile per request in FreeLLMAPI by adding a profile query parameter to override global settings. Get the syntax and implementation details now.

- Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi)
- Tags: how-to-guide
- Published: 2026-08-26

---

**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.

```http
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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/profiles.ts) (lines 115-120), the lookup executes a case-insensitive query:

```sql
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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/profile-models.ts) (lines 4-9). This function queries the `settings` table:

```sql
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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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:

```sql
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:

```http
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:

```http
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:

```http
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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/profile-models.ts) to read `settings.active_profile_id`.
- **Resolution flow**: [`router.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/router.ts) extracts the parameter, [`profiles.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/profiles.ts) validates the name, and [`profile-models.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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.