### Install and Run FreeLLMAPI

Source: https://github.com/tashfeenahmed/freellmapi/blob/main/README.md

Steps to clone the repository, install dependencies, generate an encryption key, and start the development server.

```bash
git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
npm install

# Generate an encryption key for at-rest key storage
cp .env.example .env
echo "ENCRYPTION_KEY=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")" >> .env

# Start server + dashboard together
npm run dev
```

```bash
npm run build
node server/dist/index.js     # server + dashboard both served on :3001
```

--------------------------------

### Install Dependencies and Start Development Server

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Clone the repository, install Node.js dependencies, and set up the encryption key. Then, start the development server which runs the API on port 3001 and the Vite dashboard on port 5173.

```bash
git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
npm install

# Copy the example env and generate a 32-byte AES encryption key
cp .env.example .env
echo "ENCRYPTION_KEY=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")" >> .env

# Development: server on :3001 + Vite dashboard on :5173 (HMR)
npm run dev

# Production build: both dashboard and API served from :3001
npm run build
node server/dist/index.js
```

--------------------------------

### Clone, Install, and Run FreeLLMAPI

Source: https://github.com/tashfeenahmed/freellmapi/blob/main/docs/index.html

Follow these steps to set up and start the FreeLLMAPI server locally. Ensure Node.js 20+ is installed. The server will be accessible at http://localhost:3001.

```bash
# 1. clone, install, run
$git clone https://github.com/tashfeenahmed/freellmapi.git
$cd freellmapi
$npm install && npm run dev
```

--------------------------------

### Install Dependencies and Run Development Server

Source: https://github.com/tashfeenahmed/freellmapi/blob/main/README.md

Installs project dependencies and starts the development server. The server runs on port 3001 and the dashboard on port 5173, both with Hot Module Replacement (HMR).

```bash
npm install
npm run dev
```

--------------------------------

### Tool Calling Configuration

Source: https://github.com/tashfeenahmed/freellmapi/blob/main/README.md

Example of defining tools for function calling, compatible with OpenAI's API structure, to be used with FreeLLMAPI.

```python
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

```

--------------------------------

### Python OpenAI Client Usage

Source: https://github.com/tashfeenahmed/freellmapi/blob/main/README.md

Example of using the OpenAI Python SDK with FreeLLMAPI by setting the base URL and providing a unified API key.

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3001/v1",
    api_key="freellmapi-your-unified-key",
)

resp = client.chat.completions.create(
    model="auto",  # let the router pick; or specify e.g. "gemini-2.5-flash"
    messages=[{"role": "user", "content": "Summarise the fall of Rome in one sentence."}]
)
print(resp.choices[0].message.content)
print("Routed via:", resp.headers.get("x-routed-via"))
```

--------------------------------

### Call FreeLLMAPI with cURL

Source: https://github.com/tashfeenahmed/freellmapi/blob/main/docs/index.html

Once the server is running, you can interact with it using any OpenAI-compatible client. This example demonstrates how to send a chat completion request using cURL to the local proxy.

```bash
# 3. call it like OpenAI
$curl http://localhost:3001/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{"messages":[{"role":"user","content":"hi"}]}'
```

--------------------------------

### Get Per-Platform Analytics

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Retrieve aggregated analytics data for each platform. Use the `range` parameter to specify the time window.

```bash
curl "http://localhost:3001/api/analytics/by-platform?range=7d"
```

--------------------------------

### curl Request to FreeLLMAPI

Source: https://github.com/tashfeenahmed/freellmapi/blob/main/README.md

Example of making a chat completions request to FreeLLMAPI using curl, including authorization and content type headers.

```bash
curl http://localhost:3001/v1/chat/completions \
  -H "Authorization: Bearer freellmapi-your-unified-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "hi"}]
  }'
```

--------------------------------

### Get Monthly Token Budget Overview

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Retrieves the combined monthly token budget, tokens consumed, and a per-model budget breakdown. This endpoint filters results to platforms with enabled keys. Use this to monitor token usage and budget allocation.

```bash
curl http://localhost:3001/api/fallback/token-usage
```

--------------------------------

### Get Request Volume Timeline

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Fetch time-bucketed request counts for volume charting. The `interval` parameter defaults to `hour` for 24h ranges and `day` for longer ranges.

```bash
curl "http://localhost:3001/api/analytics/timeline?range=7d&interval=day"
```

```bash
curl "http://localhost:3001/api/analytics/timeline?range=24h&interval=hour"
```

--------------------------------

### GET /v1/models — List Available Models

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Retrieves a list of all available models that the proxy accepts, compatible with OpenAI's model listing. Returns enabled models ordered by `intelligence_rank`.

```APIDOC
## GET /v1/models — List Available Models

OpenAI-compatible models listing, used by clients like LangChain, LlamaIndex, or Continue to discover which model IDs the proxy accepts. Returns only enabled models ordered by `intelligence_rank`.

### Method
GET

### Endpoint
/v1/models

### Parameters
None

### Request Example
```bash
curl http://localhost:3001/v1/models \
  -H "Authorization: Bearer freellmapi-your-unified-key"
```

### Response
#### Success Response (200)
- **object** (string) - The type of object, e.g., `list`.
- **data** (array) - A list of model objects.
  - **id** (string) - The ID of the model.
  - **object** (string) - The type of object, e.g., `model`.
  - **owned_by** (string) - The provider of the model.
  - **name** (string) - The display name of the model.
  - **context_window** (integer) - The context window size of the model.

#### Response Example
```json
{
  "object": "list",
  "data": [
    {"id": "gemini-2.5-pro", "object": "model", "owned_by": "google",
     "name": "Gemini 2.5 Pro", "context_window": 1048576},
    {"id": "llama-3.3-70b-versatile", "object": "model", "owned_by": "groq",
     "name": "Llama 3.3 70B", "context_window": 128000},
    ...
  ]
}
```
```

--------------------------------

### Pin Chat Completion to a Specific Model

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Make a chat completion request, specifying a particular model ID (e.g., `gemini-2.5-flash`) to route the request to that exact model. This example also demonstrates setting `temperature` and `max_tokens`.

```bash
# Pin to a specific model
curl http://localhost:3001/v1/chat/completions \
  -H "Authorization: Bearer freellmapi-your-unified-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "What is SQLite?"}
    ],
    "temperature": 0.3,
    "max_tokens": 200
  }'
```

--------------------------------

### Get Unified API Key

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Retrieve the single bearer token used for client authentication with the local server. This key is local and never leaves the machine.

```bash
curl http://localhost:3001/api/settings/api-key
```

--------------------------------

### Get Admin Model Catalog

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Retrieve the complete internal model catalog, including disabled models. This endpoint provides rate-limit parameters, capability ranks, context windows, and fallback configurations.

```bash
curl http://localhost:3001/api/models
```

--------------------------------

### Get Analytics Summary

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Retrieves aggregate request statistics for a specified time window (`24h`, `7d`, or `30d`). Includes total requests, success rate, token counts, average latency, and estimated cost savings. Use this for high-level performance monitoring.

```bash
curl "http://localhost:3001/api/analytics/summary?range=7d"
```

```bash
curl "http://localhost:3001/api/analytics/summary?range=24h"
```

--------------------------------

### Get Unified API Key

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Retrieves the single `freellmapi-…` bearer token used by client applications to authenticate with the proxy. This key authenticates to your local server only.

```APIDOC
## GET /api/settings/api-key — Get Unified API Key

Returns the single `freellmapi-…` bearer token that client applications use to authenticate with the proxy. This key authenticates to your local server only — it never leaves the machine.

### Method
GET

### Endpoint
/api/settings/api-key

### Response
#### Success Response (200)
- **apiKey** (string) - The unified API key.
```

--------------------------------

### Get Per-Model Analytics

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Breaks down request counts, success rates, latency, and token consumption by `(platform, modelId)` for a selected range. This provides detailed insights into the performance of individual models.

```bash
curl "http://localhost:3001/api/analytics/by-model?range=30d"
```

--------------------------------

### Get Error Distribution Breakdown

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Categorize failed requests by error type, platform, or detailed (platform, modelId, category). Use the `range` parameter to specify the time window.

```bash
curl "http://localhost:3001/api/analytics/error-distribution?range=7d"
```

--------------------------------

### Get Fallback Chain

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Retrieves the ordered priority list of all models in the fallback chain, including dynamic penalty scores and enabled key counts per platform. Use this to understand the current model prioritization.

```bash
curl http://localhost:3001/api/fallback
```

--------------------------------

### GET /api/keys — List Provider Keys

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Retrieves a list of all stored provider API keys, including their masked values, health status, and timestamps. Actual key material is never exposed.

```APIDOC
## GET /api/keys — List Provider Keys

Returns all stored provider keys with masked values (first 4 + last 4 chars), health status (`healthy`, `rate_limited`, `invalid`, `error`, `unknown`), and timestamps. Actual key material is never exposed via the API.

### Method
GET

### Endpoint
/api/keys

### Parameters
None

### Request Example
```bash
curl http://localhost:3001/api/keys
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the key.
- **platform** (string) - The API provider platform (e.g., `google`, `groq`).
- **label** (string) - A user-defined label for the key.
- **maskedKey** (string) - The masked API key.
- **status** (string) - The health status of the key.
- **enabled** (boolean) - Indicates if the key is currently enabled.
- **createdAt** (string) - The timestamp when the key was created.
- **lastCheckedAt** (string) - The timestamp of the last health check.

#### Response Example
```json
[
  {
    "id": 1,
    "platform": "google",
    "label": "personal",
    "maskedKey": "AIza****9fXk",
    "status": "healthy",
    "enabled": true,
    "createdAt": "2025-01-15T10:23:00Z",
    "lastCheckedAt": "2025-07-14T08:00:00Z"
  },
  ...
]
```
```

--------------------------------

### Get Key Health Status

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Returns a summary of key health per platform and a per-key breakdown. Statuses include `healthy`, `rate_limited`, `invalid`, `error`, or `unknown`. This is useful for monitoring the operational status of your API keys.

```bash
curl http://localhost:3001/api/health
```

--------------------------------

### Chat Completions

Source: https://github.com/tashfeenahmed/freellmapi/blob/main/README.md

Submit chat messages to the API to get a response. Supports streaming and tool calls.

```APIDOC
## POST /v1/chat/completions

### Description
Generates a chat completion based on the provided messages. This endpoint is compatible with OpenAI's chat completions API and supports features like streaming and tool calling.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Request Body
- **model** (string) - Required - The model to use for generation. Use "auto" to let the router pick.
- **messages** (array) - Required - A list of message objects representing the conversation history.
  - **role** (string) - Required - The role of the author of the message (e.g., "user", "assistant").
  - **content** (string) - Required - The content of the message.
- **stream** (boolean) - Optional - Whether to stream the response as Server-Sent Events.
- **tools** (array) - Optional - A list of tools the model may call.
- **tool_choice** (string or object) - Optional - Controls how the tools are used.

### Request Example
```json
{
  "model": "auto",
  "messages": [{"role": "user", "content": "Summarise the fall of Rome in one sentence."}]
}
```

### Response
#### Success Response (200)
- **choices** (array) - A list of chat completion choices.
  - **message** (object) - The generated message.
    - **content** (string) - The content of the message.
  - **headers** (object) - Response headers, including "x-routed-via".

#### Response Example
```json
{
  "choices": [
    {
      "message": {
        "content": "The Roman Empire collapsed due to a combination of internal strife, economic instability, and external invasions."
      }
    }
  ],
  "headers": {
    "x-routed-via": "provider-name"
  }
}
```
```

--------------------------------

### Run Tests with Vitest

Source: https://github.com/tashfeenahmed/freellmapi/blob/main/README.md

Executes the project's test suite using Vitest. The suite includes 75 tests covering providers, routes, the router, and rate limiting.

```bash
npm test
```

--------------------------------

### Tool Use in Chat Completions

Source: https://github.com/tashfeenahmed/freellmapi/blob/main/README.md

Demonstrates how to use tool calls with chat completions. First, request a tool call from the model, then execute the tool and feed the result back to the model for a final response.

```python
first = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "What's the weather in Karachi?"}],
    tools=tools,
    tool_choice="required",
)
call = first.choices[0].message.tool_calls[0]

final = client.chat.completions.create(
    model="auto",
    messages=[
        {"role": "user", "content": "What's the weather in Karachi?"},
        first.choices[0].message,
        {"role": "tool", "tool_call_id": call.id, "content": '{"temp_c": 32, "cond": "sunny"}'},
    ],
    tools=tools,
)
print(final.choices[0].message.content)
```

--------------------------------

### Python: Chat Completions with Tool Calling

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Demonstrates a two-step process for tool calling: first, the model requests a tool call, and second, the tool's result is sent back to the model for a final answer. Ensure the OpenAI client is configured with the correct base URL and API key.

```python
from openai import OpenAI
import json

client = OpenAI(base_url="http://localhost:3001/v1", api_key="freellmapi-your-unified-key")

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

# Step 1: Model requests a tool call
first = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "What's the weather in Karachi?"}],
    tools=tools,
    tool_choice="required",
)
call = first.choices[0].message.tool_calls[0]
print(f"Tool called: {call.function.name}({call.function.arguments})")
# Tool called: get_weather({"city": "Karachi"})

# Step 2: Execute the tool locally and send the result back
final = client.chat.completions.create(
    model="auto",
    messages=[
        {"role": "user", "content": "What's the weather in Karachi?"},
        first.choices[0].message,
        {
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps({"temp_c": 32, "condition": "sunny"}),
        },
    ],
    tools=tools,
)
print(final.choices[0].message.content)
# "The current weather in Karachi is 32°C and sunny."
```

--------------------------------

### Bash: List Available Models

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Fetches a list of all models supported by the API, including their IDs, providers, and context window sizes. This is useful for clients like LangChain or LlamaIndex to discover compatible models.

```bash
curl http://localhost:3001/v1/models \
  -H "Authorization: Bearer freellmapi-your-unified-key"
# {
#   "object": "list",
#   "data": [
#     {"id": "gemini-2.5-pro", "object": "model", "owned_by": "google",
#      "name": "Gemini 2.5 Pro", "context_window": 1048576},
#     {"id": "llama-3.3-70b-versatile", "object": "model", "owned_by": "groq",
#      "name": "Llama 3.3 70B", "context_window": 128000},
#     ...
#   ]
# }
```

--------------------------------

### Monthly Token Budget Overview

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Provides an overview of the combined monthly token budget, current usage, and a breakdown per model.

```APIDOC
## GET /api/fallback/token-usage — Monthly Token Budget Overview

### Description
Returns the combined monthly token budget across all configured models (filtered to platforms that have enabled keys), how many tokens have been consumed this calendar month, and a per-model budget breakdown.

### Method
GET

### Endpoint
/api/fallback/token-usage

### Response
#### Success Response (200)
- **totalBudget** (integer) - The total combined monthly token budget.
- **totalUsed** (integer) - The total number of tokens consumed this month.
- **models** (array) - An array of objects, each detailing the budget for a specific model.
  - **displayName** (string) - The display name of the model.
  - **platform** (string) - The platform the model belongs to.
  - **budget** (integer) - The monthly token budget for this specific model.

### Response Example
```json
{
  "totalBudget": 1320000000,
  "totalUsed": 4823190,
  "models": [
    {"displayName": "Gemini 2.5 Pro", "platform": "google", "budget": 120000000},
    {"displayName": "Llama 3.3 70B", "platform": "groq", "budget": 100000000},
    ...
  ]
}
```
```

--------------------------------

### Get Fallback Chain

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Retrieves the ordered priority list of all models in the fallback chain, including dynamic penalty scores and enabled key counts per platform.

```APIDOC
## GET /api/fallback — Get Fallback Chain

### Description
Returns the ordered priority list of all models in the fallback chain, including dynamic penalty scores accumulated from recent 429s and the number of enabled keys per platform.

### Method
GET

### Endpoint
/api/fallback

### Response
#### Success Response (200)
- **modelDbId** (integer) - Unique identifier for the model in the database.
- **priority** (integer) - The base priority of the model.
- **effectivePriority** (integer) - The calculated priority after considering penalties.
- **penalty** (integer) - The current penalty score due to rate limiting.
- **rateLimitHits** (integer) - The number of times the model has hit its rate limit.
- **enabled** (boolean) - Whether the model is currently enabled.
- **platform** (string) - The platform the model belongs to (e.g., google, groq).
- **modelId** (string) - The identifier of the model (e.g., gemini-2.5-pro).
- **displayName** (string) - A user-friendly name for the model.
- **intelligenceRank** (integer) - Rank based on intelligence.
- **speedRank** (integer) - Rank based on speed.
- **rpmLimit** (integer) - Requests per minute limit.
- **rpdLimit** (integer) - Requests per day limit.
- **monthlyTokenBudget** (string) - The monthly token budget for the model.
- **keyCount** (integer) - The number of enabled keys for this platform.

### Response Example
```json
[
  {
    "modelDbId": 1, "priority": 1, "effectivePriority": 1, "penalty": 0,
    "rateLimitHits": 0, "enabled": true,
    "platform": "google", "modelId": "gemini-2.5-pro",
    "displayName": "Gemini 2.5 Pro", "intelligenceRank": 1, "speedRank": 4,
    "rpmLimit": 5, "rpdLimit": 25, "monthlyTokenBudget": "~120M", "keyCount": 2
  },
  {
    "modelDbId": 5, "priority": 2, "effectivePriority": 5, "penalty": 3,
    "rateLimitHits": 1, "enabled": true,
    "platform": "groq", "modelId": "llama-3.3-70b-versatile", ...
  },
  ...
]
```
```

--------------------------------

### Streaming Chat Completions with Python

Source: https://github.com/tashfeenahmed/freellmapi/blob/main/README.md

Demonstrates how to receive streaming responses from FreeLLMAPI using the OpenAI Python SDK.

```python
stream = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Stream me a haiku about SQLite." }],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)
```

--------------------------------

### OpenAI Python SDK Integration with FreeLLMAPI

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Use the OpenAI Python SDK to interact with FreeLLMAPI by setting the `base_url` to your local FreeLLMAPI instance. This allows you to leverage FreeLLMAPI's aggregated free tiers without changing your existing OpenAI SDK code.

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3001/v1",
    api_key="freellmapi-your-unified-key",
)

resp = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Summarise the fall of Rome in one sentence." }],
)
print(resp.choices[0].message.content)
print("Routed via:", resp.headers.get("x-routed-via"))
# Routed via: google/gemini-2.5-flash
```

--------------------------------

### Get Recent Error Log

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Retrieve the 50 most recent error records within the specified time window. Includes platform, model, error message, latency, and timestamp.

```bash
curl "http://localhost:3001/api/analytics/errors?range=24h"
```

--------------------------------

### Bash: List Provider Keys

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Retrieves a list of all configured provider API keys. The response includes masked key values, health status, and timestamps, but never the actual key material.

```bash
curl http://localhost:3001/api/keys
# [
#   {
#     "id": 1,
#     "platform": "google",
#     "label": "personal",
#     "maskedKey": "AIza****9fXk",
#     "status": "healthy",
#     "enabled": true,
#     "createdAt": "2025-01-15T10:23:00Z",
#     "lastCheckedAt": "2025-07-14T08:00:00Z"
#   },
#   ...
# ]
```

--------------------------------

### Python: Use with LangChain

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Integrates the API with LangChain by initializing the ChatOpenAI client with the proxy's base URL and API key. This allows LangChain applications to leverage the models available through the proxy.

```python
# Use with LangChain
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    base_url="http://localhost:3001/v1",
    api_key="freellmapi-your-unified-key",
    model="auto",
)
print(llm.invoke("What is the capital of France?").content)
```

--------------------------------

### Bash: Add a Provider Key

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Adds a new API key for a specified provider. The key is encrypted before storage. Supported platforms include Google, Groq, and others. A label can be optionally provided.

```bash
# Add a Google API key
curl -X POST http://localhost:3001/api/keys \
  -H "Content-Type: application/json" \
  -d '{"platform": "google", "key": "AIzaSy...", "label": "personal-gemini"}'
# {"id": 3, "platform": "google", "label": "personal-gemini",
#  "maskedKey": "AIza****tY9k", "status": "unknown", "enabled": true}

# Add a Groq key
curl -X POST http://localhost:3001/api/keys \
  -H "Content-Type: application/json" \
  -d '{"platform": "groq", "key": "gsk_..."}'

# Add an OpenRouter key
curl -X POST http://localhost:3001/api/keys \
  -H "Content-Type: application/json" \
  -d '{"platform": "openrouter", "key": "sk-or-v1-...", "label": "free-tier"}'
```

--------------------------------

### List Models

Source: https://github.com/tashfeenahmed/freellmapi/blob/main/README.md

Retrieve a list of available models.

```APIDOC
## GET /v1/models

### Description
Retrieves a list of all models available through the API. This endpoint is compatible with OpenAI's model retrieval endpoint.

### Method
GET

### Endpoint
/v1/models

### Response
#### Success Response (200)
- **data** (array) - A list of model objects.
  - **id** (string) - The unique identifier of the model.
  - **object** (string) - The type of object, typically "model".
  - **owned_by** (string) - The entity that owns the model.
```

--------------------------------

### Server Health Check

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Perform a lightweight liveness probe to check server health. Returns a status of 'ok' and the current server timestamp.

```bash
curl http://localhost:3001/api/ping
```

--------------------------------

### Sort Fallback Chain by Preset

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Reorders the fallback chain using a built-in sorting strategy. Presets include `intelligence`, `speed`, and `budget`. Use this to quickly reconfigure model prioritization based on predefined criteria.

```bash
# Sort by intelligence rank (best models first)
curl -X POST http://localhost:3001/api/fallback/sort/intelligence
```

```bash
# Sort by speed (fastest providers first — Cerebras, Groq)
curl -X POST http://localhost:3001/api/fallback/sort/speed
```

```bash
# Sort by monthly token budget (highest allocation first)
curl -X POST http://localhost:3001/api/fallback/sort/budget
```

--------------------------------

### POST /v1/chat/completions (tools) — Tool Calling

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

This endpoint allows for chat completions with tool calling capabilities, compatible with OpenAI's function calling. It supports multi-step tool flows and automatic translation for providers like Google Gemini.

```APIDOC
## POST /v1/chat/completions (tools) — Tool Calling

OpenAI-style function calling passes through verbatim to OpenAI-compatible providers. For Google Gemini, the proxy translates `tools` → `functionDeclarations` and `functionResponse` role messages ↔ Google's format automatically. Multi-step tool flows (assistant `tool_calls` → `tool` role → final answer) work across all providers.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Request Body
- **model** (string) - Required - The model to use for chat completions.
- **messages** (array) - Required - A list of messages comprising the conversation.
- **tools** (array) - Optional - A list of tools the model may call.
- **tool_choice** (string) - Optional - Controls how the model must respond to tool calls.

### Request Example
```python
from openai import OpenAI
import json

client = OpenAI(base_url="http://localhost:3001/v1", api_key="freellmapi-your-unified-key")

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

# Step 1: Model requests a tool call
first = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "What's the weather in Karachi?"}],
    tools=tools,
    tool_choice="required",
)
call = first.choices[0].message.tool_calls[0]
print(f"Tool called: {call.function.name}({call.function.arguments})")

# Step 2: Execute the tool locally and send the result back
final = client.chat.completions.create(
    model="auto",
    messages=[
        {"role": "user", "content": "What's the weather in Karachi?"},
        first.choices[0].message,
        {
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps({"temp_c": 32, "condition": "sunny"}),
        },
    ],
    tools=tools,
)
print(final.choices[0].message.content)
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the completion.
- **object** (string) - The type of object, e.g., `chat.completion`.
- **created** (integer) - Unix timestamp of creation.
- **model** (string) - The model used.
- **choices** (array) - A list of completion choices.
- **usage** (object) - Usage statistics for the completion.

#### Response Example
```json
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "auto",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "The current weather in Karachi is 32°C and sunny."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}
```
```

--------------------------------

### POST /api/keys — Add a Provider Key

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Adds a new provider API key to the system. The key is encrypted before storage. Supports various platforms including Google, Groq, and OpenAI.

```APIDOC
## POST /api/keys — Add a Provider Key

Encrypts a provider API key with AES-256-GCM before storing it in SQLite. The `platform` must be one of: `google`, `groq`, `cerebras`, `sambanova`, `nvidia`, `mistral`, `openrouter`, `github`, `cohere`, `cloudflare`, `zhipu`.

### Method
POST

### Endpoint
/api/keys

### Parameters
#### Request Body
- **platform** (string) - Required - The API provider platform.
- **key** (string) - Required - The API key to store.
- **label** (string) - Optional - A user-defined label for the key.

### Request Example
```bash
# Add a Google API key
curl -X POST http://localhost:3001/api/keys \
  -H "Content-Type: application/json" \
  -d '{"platform": "google", "key": "AIzaSy...", "label": "personal-gemini"}'

# Add a Groq key
curl -X POST http://localhost:3001/api/keys \
  -H "Content-Type: application/json" \
  -d '{"platform": "groq", "key": "gsk_..."}'

# Add an OpenRouter key
curl -X POST http://localhost:3001/api/keys \
  -H "Content-Type: application/json" \
  -d '{"platform": "openrouter", "key": "sk-or-v1-...", "label": "free-tier"}'
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the newly added key.
- **platform** (string) - The API provider platform.
- **label** (string) - The user-defined label for the key.
- **maskedKey** (string) - The masked API key.
- **status** (string) - The initial health status of the key.
- **enabled** (boolean) - Indicates if the key is enabled by default.

#### Response Example
```json
{"id": 3, "platform": "google", "label": "personal-gemini",
 "maskedKey": "AIza****tY9k", "status": "unknown", "enabled": true}
```
```

--------------------------------

### Basic Chat Completion Request with FreeLLMAPI

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Send a basic chat completion request to the FreeLLMAPI endpoint. The `model: "auto"` option allows the router to select the best available provider. Ensure you replace `freellmapi-your-unified-key` with your actual key.

```bash
# Basic request — let the router pick
curl http://localhost:3001/v1/chat/completions \
  -H "Authorization: Bearer freellmapi-your-unified-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Explain recursion in one sentence."}]
  }'
# Response headers include: X-Routed-Via: groq/llama-3.3-70b-versatile
```

--------------------------------

### Streaming Chat Completion with OpenAI Python SDK

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Implement streaming chat completions using the OpenAI Python SDK. The `stream=True` parameter enables Server-Sent Events. The response is processed chunk by chunk, and the `x-routed-via` header indicates the provider used.

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:3001/v1", api_key="freellmapi-your-unified-key")

stream = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Write a haiku about SQLite." }],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)
print()  # newline after stream ends
```

--------------------------------

### Sort Fallback Chain by Preset

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Reorders the fallback chain using a predefined sorting strategy. Presets include 'intelligence', 'speed', and 'budget'.

```APIDOC
## POST /api/fallback/sort/:preset — Sort Fallback Chain by Preset

### Description
Reorders the fallback chain using a built-in sorting strategy. Valid presets: `intelligence` (highest capability first), `speed` (lowest latency first), `budget` (largest monthly token allowance first).

### Method
POST

### Endpoint
/api/fallback/sort/:preset

### Parameters
#### Path Parameters
- **preset** (string) - Required - The sorting strategy to apply. Options: `intelligence`, `speed`, `budget`.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the sorting was successful.
- **preset** (string) - The preset used for sorting.

### Response Example
```json
{"success": true, "preset": "intelligence"}
```
```

--------------------------------

### Expand ESLint for React-Specific Rules

Source: https://github.com/tashfeenahmed/freellmapi/blob/main/client/README.md

Integrate `eslint-plugin-react-x` and `eslint-plugin-react-dom` to enable lint rules specifically for React and React DOM development. Ensure the `project` option in `parserOptions` is correctly configured.

```javascript
// eslint.config.js
import reactX from 'eslint-plugin-react-x'
import reactDom from 'eslint-plugin-react-dom'

export default defineConfig([
  globalIgnores(['dist']),
  {
    files: ['**/*.{ts,tsx}'],
    extends: [
      // Other configs...
      // Enable lint rules for React
      reactX.configs['recommended-typescript'],
      // Enable lint rules for React DOM
      reactDom.configs.recommended,
    ],
    languageOptions: {
      parserOptions: {
        project: ['./tsconfig.node.json', './tsconfig.app.json'],
        tsconfigRootDir: import.meta.dirname,
      },
      // other options...
    },
  },
])
```

--------------------------------

### Check a Single Key's Health

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Runs a live health probe for a specific key and updates its stored status. Returns the resulting status string. Use this to verify the health of an individual key.

```bash
curl -X POST http://localhost:3001/api/health/check/1
```

```bash
curl -X POST http://localhost:3001/api/health/check/2
```

--------------------------------

### Server Health Check

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

A lightweight liveness probe that returns the server's status and the current server timestamp.

```APIDOC
## GET /api/ping — Server Health Check

Lightweight liveness probe. Returns status `"ok"` and the current server timestamp.

### Method
GET

### Endpoint
/api/ping

### Response
#### Success Response (200)
- **status** (string) - The status of the server, expected to be 'ok'.
- **timestamp** (string) - The current server timestamp in ISO 8601 format.
```

--------------------------------

### POST /v1/chat/completions (stream: true) — Streaming Chat Completion

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Enables streaming mode for chat completions, returning Server-Sent Events in the standard OpenAI `data: {...}

` format. The router handles fallover logic before the first byte. Mid-stream provider errors result in a `data: {"error": ...}

` frame instead of truncation.

```APIDOC
## POST /v1/chat/completions (stream: true) — Streaming Chat Completion

### Description
Streaming mode sends Server-Sent Events in the standard OpenAI `data: {...}\n\n` format, terminated with `data: [DONE]\n\n`. The router applies the same fallover logic before the first byte is written; a mid-stream provider error emits a final `data: {"error": ...}\n\n` frame rather than silently truncating the response.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Request Body
- **model** (string) - Optional - The model to use for completion. `"auto"` selects the best available provider.
- **messages** (array) - Required - An array of message objects, each with a `role` and `content`.
- **temperature** (number) - Optional - Controls randomness.
- **max_tokens** (integer) - Optional - The maximum number of tokens to generate.
- **top_p** (number) - Optional - Nucleus sampling parameter.
- **stream** (boolean) - Required - Set to `true` to enable streaming.
- **tools** (array) - Optional - A list of tools the model may call.
- **tool_choice** (object or string) - Optional - Controls how the tools are used.

### Request Example
```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:3001/v1", api_key="freellmapi-your-unified-key")

stream = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Write a haiku about SQLite.")},
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)
print()  # newline after stream ends
```

```bash
# curl equivalent
curl -N http://localhost:3001/v1/chat/completions \
  -H "Authorization: Bearer freellmapi-your-unified-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "auto", "messages": [{"role":"user","content":"Count to 5"}], "stream": true}'
```

### Response
#### Success Response (200)
- **data** (string) - Server-Sent Event data frames, each starting with `data: ` and ending with `\n\n`. The stream is terminated with `data: [DONE]\n\n`.

#### Response Example
```
data: {"id":"chatcmpl-xxxxxxxxxxxxxxxxxxxxxxxxx","object":"chat.completion.chunk","choices":[{"delta":{"content":"1"},...}]}

data: {"id":"chatcmpl-xxxxxxxxxxxxxxxxxxxxxxxxx","object":"chat.completion.chunk","choices":[{"delta":{"content":", 2"},...}]}

...

data: [DONE]

```
```

--------------------------------

### Request Volume Timeline

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Returns time-bucketed request counts suitable for a volume chart. The interval defaults to 'hour' for 24h ranges and 'day' for 7d/30d ranges.

```APIDOC
## GET /api/analytics/timeline — Request Volume Timeline

Returns time-bucketed request counts suitable for a volume chart. The `interval` defaults to `hour` for 24h ranges and `day` for 7d/30d ranges.

### Method
GET

### Endpoint
/api/analytics/timeline

#### Query Parameters
- **range** (string) - Required - The time range for the analytics data (e.g., '7d', '24h').
- **interval** (string) - Optional - The time interval for bucketing requests (e.g., 'hour', 'day').

### Response
#### Success Response (200)
- **timestamp** (string) - The timestamp for the data bucket.
- **requests** (integer) - The total number of requests in the bucket.
- **successCount** (integer) - The number of successful requests.
- **failureCount** (integer) - The number of failed requests.
```

--------------------------------

### Regenerate Unified API Key

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Rotate the unified API key. All existing clients must be updated with the new key after regeneration.

```bash
curl -X POST http://localhost:3001/api/settings/api-key/regenerate
```

--------------------------------

### Check All Keys

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Initiates a comprehensive health probe sweep across all stored API keys. This is useful after adding a batch of new keys.

```APIDOC
## POST /api/health/check-all — Check All Keys

### Description
Triggers a full health probe sweep across every stored key. Useful after adding a batch of keys.

### Method
POST

### Endpoint
/api/health/check-all

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the check-all operation was initiated successfully.

### Response Example
```json
{"success": true}
```
```

--------------------------------

### Bash: Delete a Provider Key

Source: https://context7.com/tashfeenahmed/freellmapi/llms.txt

Removes a provider API key from the database using its ID. Attempting to delete a non-existent key will result in a 404 error.

```bash
curl -X DELETE http://localhost:3001/api/keys/3
# {"success": true}

# Trying to delete a non-existent key returns 404
curl -X DELETE http://localhost:3001/api/keys/999
# {"error": {"message": "Key not found"}}
```