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

> Discover the key API route files in OmniRoute and understand its REST endpoint structure. Learn how route.ts files manage requests and integrate with the streaming engine.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: deep-dive
- Published: 2026-08-27

---

**OmniRoute exposes its public HTTP API through Next.js App Router files located under `src/app/api/v1/`, where each [`route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts). This file handles OpenAI-compatible chat requests and forwards them to [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts) for provider selection and streaming. The route validates incoming payloads against schemas defined in [`src/shared/schemas/chatCompletions.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/schemas/chatCompletions.ts) before invoking the core handler.

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/images/generations/route.ts) handles `/v1/images/generations`
- **Editing**: [`src/app/api/v1/images/edits/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/images/edits/route.ts) provides inpainting and modification capabilities
- **Upscaling**: [`src/app/api/v1/images/upscale/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/images/upscale/route.ts) handles resolution enhancement

These endpoints utilize shared utilities from [`src/app/api/v1/_shared/mediaGenerationRoute.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/transcriptions/route.ts) for speech-to-text
- **Translations**: [`translations/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/translations/route.ts) for cross-lingual speech conversion
- **Speech**: [`speech/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/proxies/route.ts) and [`proxies/health/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/rateLimit.ts)**: Centralized rate-limiting logic consumed by multiple endpoints
- **[`mediaGenerationRoute.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/chat/completions/route.ts)), legacy completions ([`completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/completions/route.ts)), and the relay layer ([`relay/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/relay/chat/completions/route.ts)).
- **Model discovery** happens via [`models/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/_shared/mediaGenerationRoute.ts).
- **Advanced routing** is implemented in [`combos/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts). The [`route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts) and [`src/app/api/v1/embeddings/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.