# FreeLLMAPI API Endpoints: Complete Reference to OpenAI-Compatible and Admin Routes

> Explore FreeLLMAPI API endpoints including OpenAI-compatible routes for inference and admin routes for management. Discover all implemented API routes in the tashfeenahmed/freellmapi repository.

- Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi)
- Tags: api-reference
- Published: 2026-06-29

---

**FreeLLMAPI exposes two distinct families of HTTP endpoints—OpenAI-compatible public routes under `/v1/*` for LLM inference and administrative routes under `/api/*` for key management, model configuration, and analytics—both implemented in the tashfeenahmed/freellmapi repository using Express.js routers.**

FreeLLMAPI is an open-source proxy and aggregation layer that unifies multiple LLM providers behind a single API interface. Understanding the complete FreeLLMAPI API endpoints architecture is essential for developers integrating generative AI capabilities or managing self-hosted deployments. This guide examines every public and administrative route defined in the source code, including implementation details from [`server/src/routes/proxy.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/proxy.ts) and the administrative route handlers.

## Public OpenAI-Compatible Endpoints (`/v1/*`)

The public API surface follows OpenAI's REST conventions and handles all inference requests, including routing, rate-limiting, and provider fallback logic. All routes in this family require authentication via `Authorization: Bearer <key>` or the `x-api-key` header, validated using `timingSafeStringEqual` for timing-attack resistance.

### Chat Completions and Legacy Text Endpoints

The primary inference endpoints are implemented in [`server/src/routes/proxy.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/proxy.ts):

- **POST `/v1/chat/completions`** – The main chat completion endpoint supporting streaming, tool-calling, image inputs, and the virtual `auto` and `fusion` models. Implemented at [`proxy.ts → router.post('/chat/completions')`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/proxy.ts#L180).
- **POST `/v1/completions`** – Legacy text-completion endpoint (e.g., for Codex-style autocomplete) that translates requests into chat completions internally. Found at [`proxy.ts → router.post('/completions')`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/proxy.ts#L99).

### Embeddings and Media Generation

Multimedia and embedding capabilities are also exposed under the `/v1` prefix:

- **POST `/v1/embeddings`** – Generates vector embeddings for text input. The `model` field selects a family, with `auto` routing to the default family. Source: [`proxy.ts → router.post('/embeddings')`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/proxy.ts#L32).
- **POST `/v1/images/generations`** – Creates images from prompts using Stable Diffusion, DALL-E, or other configured providers. Source: [`proxy.ts → router.post('/images/generations')`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/proxy.ts#L80).
- **POST `/v1/audio/speech`** – Text-to-speech conversion returning raw audio bytes. Source: [`proxy.ts → router.post('/audio/speech')`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/proxy.ts#L18).

### Model Listing and Special Formats

Additional compatibility endpoints include:

- **GET `/v1/models`** – Retrieves available models including the virtual `auto` and `fusion` models. Supports `?available=true` to filter for currently serving models. Source: [`proxy.ts → router.get('/models')`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/proxy.ts#L75).
- **POST `/v1/responses`** – OpenAI Responses API shim used by Codex-style agents, accepting `instructions` and `input` arrays with SSE event streaming. Implemented in [[`server/src/routes/responses.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/responses.ts)](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/responses.ts#L84).
- **POST `/v1/anthropic/*`** – Anthropic-compatible Messages API (including `/v1/messages`) mounted before the generic OpenAI router. Source: [[`server/src/routes/anthropic.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts)](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts).

All remaining `/v1/*` paths fall through to the generic OpenAI proxy handler mounted in [[`app.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/app.ts)](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/app.ts#L76).

## Admin Dashboard Endpoints (`/api/*`)

Administrative endpoints manage the proxy configuration, API keys, and system analytics. These routes sit behind `requireAuth` middleware (session-based dashboard login) and are mounted in [`server/src/app.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/app.ts).

### API Key Management

The keys API in [`server/src/routes/keys.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/keys.ts) provides full CRUD operations for provider credentials:

- **GET `/api/keys`** – Lists all stored API keys (masked) and attached custom models. Implementation: [`keys.ts → router.get('/')`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/keys.ts#L36).
- **POST `/api/keys`** – Adds a new key for any supported platform. Source: [`keys.ts → router.post('/')`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/keys.ts#L5).
- **POST `/api/keys/custom`** – Registers custom OpenAI-compatible endpoints (e.g., Ollama, vLLM) and auto-adds models to the fallback chain. Source: [`keys.ts → router.post('/custom')`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/keys.ts#L88).
- **PATCH `/api/keys/:id`** – Toggles a key's `enabled` flag or edits its label. Source: [`keys.ts → router.patch('/:id')`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/keys.ts#L77).
- **PATCH `/api/keys/platform/:platform`** – Bulk enables or disables all keys for a specific platform. Source: [`keys.ts → router.patch('/platform/:platform')`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/keys.ts#L58).
- **DELETE `/api/keys/:id`** – Removes a key and cascades deletion to dependent custom models. Source: [`keys.ts → router.delete('/:id')`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/keys.ts#L6).

### Model and Profile Configuration

Model lifecycle and routing profile management:

- **GET `/api/models`** – Returns the full model catalog enriched with fallback priority, enabled status, key counts, and provider availability. Source: [`models.ts → router.get('/')`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/models.ts#L81).
- **PATCH `/api/models/:id`** – Updates model metadata (display name, limits, size labels) and fallback-chain inclusion. Source: [`models.ts → router.patch('/:id')`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/models.ts#L90).
- **DELETE `/api/models/:id`** – Deletes a model with catalog-managed tombstoning. Source: [`models.ts → router.delete('/:id')`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/models.ts#L54).
- **DELETE `/api/models/custom/:id`** – Removes custom models and cleans up unused keys. Source: [`models.ts → router.delete('/custom/:id')`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/models.ts#L67).
- **GET / POST / PATCH / DELETE `/api/profiles/*`** – Manages named fallback-chain configurations. Source: [[`server/src/routes/profiles.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/profiles.ts)](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/profiles.ts).
- **GET `/api/fallback`** – Retrieves or modifies the global fallback chain (default model ordering). Source: [[`server/src/routes/fallback.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/fallback.ts)](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/fallback.ts).

### System Analytics and Settings

Operational and configuration endpoints:

- **GET `/api/analytics`** – Usage statistics, routing scores, and penalty tables for the dashboard. Source: [[`server/src/routes/analytics.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/analytics.ts)](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/analytics.ts).
- **GET / PATCH `/api/settings`** – Global configuration including routing strategy and custom weights. Source: [[`server/src/routes/settings.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/settings.ts)](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/settings.ts).
- **GET `/api/health`** – Health-check endpoint for monitoring. Source: [[`server/src/routes/health.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/health.ts)](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/health.ts).
- **GET / PATCH `/api/premium`** – Premium-tier toggles (e.g., free tier disabling). Source: [[`server/src/routes/premium.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/premium.ts)](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/premium.ts).
- **GET / POST `/api/auth/*`** – Dashboard authentication flow (setup, login, status). Source: [[`server/src/routes/auth.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/auth.ts)](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/auth.ts).

## Authentication and Security

All FreeLLMAPI API endpoints require the unified API key. Public endpoints accept the key as either a `Bearer` token in the `Authorization` header or via the `x-api-key` header. The comparison uses `timingSafeStringEqual` to prevent timing attacks.

Administration endpoints (`/api/*`) require both the unified API key and session-based authentication via the `requireAuth` middleware. Routes are mounted in [`server/src/app.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/app.ts) as follows:

```typescript
// server/src/app.ts
app.use('/api/keys', requireAuth, keysRouter);
app.use('/api/models', requireAuth, modelsRouter);
app.use('/api/profiles', requireAuth, profilesRouter);
app.use('/api/analytics', requireAuth, analyticsRouter);

```

## Integration Examples

Replace `<UNIFIED_KEY>` with your setup key from the environment configuration.

### List Available Models

```bash
curl -s -H "Authorization: Bearer <UNIFIED_KEY>" \
  https://localhost:3000/v1/models | jq .

```

### Generate Chat Completion with Auto-Routing

```bash
curl -s -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer <UNIFIED_KEY>" \
  -d '{
    "model": "auto",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain quantum tunneling in one sentence."}
    ],
    "temperature": 0.7,
    "stream": false
  }' \
  https://localhost:3000/v1/chat/completions | jq .

```

### Create Embeddings

```bash
curl -s -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer <UNIFIED_KEY>" \
  -d '{"model": "auto", "input": "OpenAI provides powerful language models"}' \
  https://localhost:3000/v1/embeddings | jq .

```

### Admin: List Stored Keys

```bash
curl -s -b cookie.txt -H "Authorization: Bearer <UNIFIED_KEY>" \
  https://localhost:3000/api/keys | jq .

```

## Summary

- **Public endpoints** (`/v1/*`) in [`server/src/routes/proxy.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/proxy.ts) provide OpenAI-compatible chat completions, embeddings, image generation, text-to-speech, and legacy text completions.
- **Virtual models** `auto` and `fusion` enable intelligent routing and panel-based synthesis, listed alongside standard models via `/v1/models`.
- **Administrative endpoints** (`/api/*`) secured by `requireAuth` middleware manage API keys, model catalogs, fallback chains, and analytics.
- **Authentication** requires the unified API key for all routes, with admin endpoints additionally requiring session-based dashboard login.
- **Core routing logic** resides in [`server/src/services/router.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/router.ts), while rate-limiting is handled in [`server/src/services/ratelimit.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/ratelimit.ts).

## Frequently Asked Questions

### What authentication method does FreeLLMAPI use for its API endpoints?

FreeLLMAPI requires a unified API key for all requests, passed either as a `Bearer` token in the `Authorization` header or via the `x-api-key` header. The comparison uses `timingSafeStringEqual` for timing-attack resistance. Administrative endpoints in `/api/*` additionally require session-based authentication through the `requireAuth` middleware.

### How does the virtual `auto` model work in FreeLLMAPI?

The `auto` model is a virtual endpoint that triggers the routing engine in [`server/src/services/router.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/router.ts) to select the best available model based on the active routing strategy, key availability, and rate-limit status. It appears in the `/v1/models` listing and can be used with any completion or embedding endpoint to delegate provider selection.

### What is the difference between `/v1/chat/completions` and `/v1/responses`?

The `/v1/chat/completions` endpoint follows the standard OpenAI chat format with `messages` arrays, while `/v1/responses` implements the older OpenAI Responses API used by Codex-style agents. The Responses endpoint accepts `instructions` and `input` arrays and returns SSE events formatted as response objects, implemented separately in [`server/src/routes/responses.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/responses.ts).

### Can FreeLLMAPI proxy requests to Anthropic's Claude models?

Yes, FreeLLMAPI exposes Anthropic-compatible endpoints under `/v1/anthropic/*`, including `/v1/messages` and `/v1/count_tokens`, implemented in [`server/src/routes/anthropic.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/anthropic.ts). These routes are mounted before the generic OpenAI router to ensure proper request handling for Anthropic's message format.