Key API Route Files in OmniRoute: A Complete Guide to the REST Endpoint Structure

OmniRoute exposes its public HTTP API through Next.js App Router files located under src/app/api/v1/, where each route.ts file acts as a thin wrapper that validates requests with Zod and delegates to handlers in the open-sse/ streaming engine.

OmniRoute is an open-source AI gateway that standardizes access to multiple LLM providers through a unified REST interface. Understanding the key API route files is essential for developers extending the platform or debugging routing behavior. All public endpoints follow a consistent request lifecycle: apply CORS headers, validate the body with Zod schemas, enforce policy via the auth service, and delegate to the appropriate handler in open-sse/handlers/.

Core Chat and Completion Endpoints

The primary interaction points for LLM inference reside in the completions namespaces. These endpoints support both JSON and Server-Sent Events (SSE) streaming responses.

Chat Completions

The flagship endpoint /v1/chat/completions is implemented in src/app/api/v1/chat/completions/route.ts. This file handles OpenAI-compatible chat requests and forwards them to open-sse/handlers/chatCore.ts for provider selection and streaming. The route validates incoming payloads against schemas defined in src/shared/schemas/chatCompletions.ts before invoking the core handler.

curl -X POST https://localhost:20128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -d '{
        "model":"gpt-4o-mini",
        "messages":[{"role":"user","content":"Explain quantum tunnelling"}],
        "temperature":0.7
      }'

Text Completions

Legacy single-turn completions are served from src/app/api/v1/completions/route.ts. This maintains backward compatibility with older OpenAI API clients that target the /v1/completions endpoint rather than the chat-specific interface.

Relay Layer for OpenAI Compatibility

The /v1/relay/chat/completions endpoint in src/app/api/v1/relay/chat/completions/route.ts acts as a compatibility layer that forwards requests directly to the internal routing engine. This is useful for clients that require strict OpenAI API parity while still leveraging OmniRoute's provider aggregation logic.

Model Discovery and Provider Routing

OmniRoute exposes detailed model metadata and allows direct access to specific providers through parameterized routes.

Model Catalog

The src/app/api/v1/models/route.ts file serves the /v1/models endpoint, returning a comprehensive list of available models, their capabilities, and associated policies. This powers client-side model selection UIs and capability detection.

Per-Model Shortcuts

Dynamic model-specific routes are handled by src/app/api/v1/models/[...model]/route.ts. This enables URL patterns like /v1/models/gpt-4/chat/completions, providing shortcuts that bypass the generic routing layer for direct model targeting.

Provider-Specific Endpoints

For debugging or provider-pinned requests, OmniRoute exposes direct provider access:

• Chat: src/app/api/v1/providers/[provider]/chat/completions/route.ts (e.g., /v1/providers/openai/chat/completions)
• Models: src/app/api/v1/providers/[provider]/models/route.ts

These routes skip the multi-provider selection logic and route directly to the specified backend.

Multimodal and Embedding APIs

Beyond text generation, the API surface covers image generation, vector embeddings, and audio processing.

Image Generation and Editing

The images namespace follows the DALL-E API specification:

• Generations: src/app/api/v1/images/generations/route.ts handles /v1/images/generations
• Editing: src/app/api/v1/images/edits/route.ts provides inpainting and modification capabilities
• Upscaling: src/app/api/v1/images/upscale/route.ts handles resolution enhancement

These endpoints utilize shared utilities from src/app/api/v1/_shared/mediaGenerationRoute.ts to standardize file handling and response streaming across media types.

Embeddings

Text vectorization is exposed through src/app/api/v1/embeddings/route.ts, implementing the standard /v1/embeddings interface compatible with OpenAI's embedding models.

Audio Processing

The audio namespace in src/app/api/v1/audio/ contains three distinct endpoints:

• Transcriptions: transcriptions/route.ts for speech-to-text
• Translations: translations/route.ts for cross-lingual speech conversion
• Speech: speech/route.ts for text-to-speech generation

Advanced Routing Strategies

OmniRoute implements sophisticated load-balancing and fallback strategies through specialized combo endpoints.

Combo Routing

The src/app/api/v1/combos/route.ts file implements the Auto-Combo strategy, allowing a single request to fan out across multiple models simultaneously. This endpoint accepts a strategy parameter (e.g., "auto") and aggregates responses from several providers to improve reliability or compare outputs.

curl -X POST https://localhost:20128/v1/combos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -d '{
        "strategy":"auto",
        "messages":[{"role":"user","content":"Write a haiku about AI"}]
      }'

Auto-Combo Candidate Enumeration

Supporting the combo system, src/app/api/v1/auto-combo/[channel]/candidates/route.ts provides the UI layer with a list of viable model targets for a specific routing channel. This enables dynamic population of model selection interfaces based on current provider health and capacity.

Management and Shared Infrastructure

Administrative functions and cross-cutting concerns are centralized in specific subdirectories.

Administrative Endpoints

The src/app/api/v1/management/ directory contains operational routes for system maintenance. Key files include proxies/route.ts and proxies/health/route.ts, which expose proxy health checks, bulk assignments, and subscription handling for enterprise deployments.

Shared Middleware Utilities

Cross-cutting logic is extracted into the src/app/api/v1/_shared/ directory to ensure consistency:

• rateLimit.ts: Centralized rate-limiting logic consumed by multiple endpoints
• mediaGenerationRoute.ts: Generic plumbing for image and audio generation routes, handling SSE streaming and error normalization

These shared modules prevent code duplication across the dozens of individual route.ts files scattered throughout the API tree.

Summary

• Entry points for all OmniRoute HTTP traffic reside in src/app/api/v1/**/route.ts files using the Next.js App Router convention.
• Core LLM endpoints include chat completions (chat/completions/route.ts), legacy completions (completions/route.ts), and the relay layer (relay/chat/completions/route.ts).
• Model discovery happens via models/route.ts, with dynamic routing available through [...model]/route.ts and provider-specific paths under providers/[provider]/.
• Multimodal features are organized under images/, embeddings/, and audio/ directories, sharing common utilities from _shared/mediaGenerationRoute.ts.
• Advanced routing is implemented in combos/route.ts and auto-combo/[channel]/candidates/route.ts for multi-model strategies.
• Business logic is delegated to the open-sse/handlers/ workspace after request validation and authentication.

Frequently Asked Questions

What pattern do OmniRoute API routes follow?

Every route follows a four-stage pipeline: CORS header application, Zod schema validation (using schemas from src/shared/schemas/), optional authentication via the auth service, and handler delegation to the open-sse/handlers/ directory. This pattern ensures consistent security and error handling across all endpoints.

Where is the business logic for API routes implemented?

The heavy lifting— including provider selection, circuit-breaker handling, request translation, and SSE streaming—is implemented in the open-sse/ sub-workspace, specifically within files like open-sse/handlers/chatCore.ts. The route.ts files in src/app/api/v1/ are intentionally thin wrappers responsible only for HTTP-level concerns.

How does OmniRoute handle OpenAI-compatible endpoints?

OmniRoute maintains strict API parity with OpenAI through dedicated route files like src/app/api/v1/chat/completions/route.ts and src/app/api/v1/embeddings/route.ts. These accept standard OpenAI request payloads and return identically formatted responses, allowing existing OpenAI SDK clients to connect to OmniRoute by simply changing the base URL.

What is the purpose of the combo routing endpoints?

The /v1/combos endpoint (implemented in src/app/api/v1/combos/route.ts) enables Auto-Combo strategies that distribute a single request across multiple models simultaneously. This provides automatic failover, consensus-based response selection, or performance benchmarking by aggregating outputs from different providers in real-time.

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