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

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

• 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').
• 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').

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').
• POST /v1/images/generations – Creates images from prompts using Stable Diffusion, DALL-E, or other configured providers. Source: proxy.ts → router.post('/images/generations').
• POST /v1/audio/speech – Text-to-speech conversion returning raw audio bytes. Source: proxy.ts → router.post('/audio/speech').

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').
• 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#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).

All remaining /v1/* paths fall through to the generic OpenAI proxy handler mounted in [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.

API Key Management

The keys API in 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('/').
• POST /api/keys – Adds a new key for any supported platform. Source: keys.ts → router.post('/').
• 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').
• PATCH /api/keys/:id – Toggles a key's enabled flag or edits its label. Source: keys.ts → router.patch('/:id').
• PATCH /api/keys/platform/:platform – Bulk enables or disables all keys for a specific platform. Source: keys.ts → router.patch('/platform/:platform').
• DELETE /api/keys/:id – Removes a key and cascades deletion to dependent custom models. Source: keys.ts → router.delete('/:id').

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('/').
• PATCH /api/models/:id – Updates model metadata (display name, limits, size labels) and fallback-chain inclusion. Source: models.ts → router.patch('/:id').
• DELETE /api/models/:id – Deletes a model with catalog-managed tombstoning. Source: models.ts → router.delete('/:id').
• DELETE /api/models/custom/:id – Removes custom models and cleans up unused keys. Source: models.ts → router.delete('/custom/:id').
• 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).
• 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).

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).
• 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).
• 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).
• 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).
• 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).

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 as follows:

// 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

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

Generate Chat Completion with Auto-Routing

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

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

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 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, while rate-limiting is handled in 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 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.

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. These routes are mounted before the generic OpenAI router to ensure proper request handling for Anthropic's message format.

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