Where Are the API Routes Located in the OmniRoute Monorepo?

OmniRoute’s public HTTP endpoints are implemented using Next.js App Router and located under src/app/api/, with production-grade routes grouped in the v1 version folder that exposes an OpenAI-compatible API surface.

OmniRoute is an open-source routing layer that provides a unified interface for AI model providers. If you are contributing to or deploying this monorepo, understanding exactly where the API routes are located is essential for customization, debugging, or adding new endpoints. The codebase follows Next.js 13+ conventions, mapping the filesystem directly to URL paths under the /api namespace.

Next.js App Router Structure in src/app/api/

The routing architecture centers on the Next.js App Router convention introduced in version 13. Every folder inside src/app/api/ represents a route segment, with route.ts files defining the HTTP methods for that path.

The top-level structure is:

src/app/api/                # Top-level API entry point

│
├─ v1/                      # Primary versioned API surface (/v1/*)

│   ├─ chat/completions/    # POST /v1/chat/completions

│   ├─ completions/         # POST /v1/completions

│   ├─ embeddings/          # POST /v1/embeddings

│   ├─ models/              # GET /v1/models and /v1/models/{model}

│   ├─ relay/               # Internal streaming and routing layer

│   ├─ audio/               # Audio transcription and generation

│   ├─ images/              # Image generation endpoints

│   ├─ files/               # File upload and management

│   └─ [...omnirouteCatchAll]/
│
└─ ...                      # Non-v1 experimental routes (ws, web, etc.)

Each route.ts file exports functions named after HTTP verbs (e.g., POST, GET) that Next.js automatically maps to incoming requests.

The v1 API Version Folder

All production-grade endpoints reside under src/app/api/v1/, which implements the OpenAI-compatible API surface. This versioning strategy allows the project to maintain backward compatibility while iterating on future releases.

Key route files within v1/ include:

• src/app/api/v1/chat/completions/route.ts – Handles POST /v1/chat/completions by delegating to handleChatCore
• src/app/api/v1/completions/route.ts – Legacy completion endpoints (POST /v1/completions)
• src/app/api/v1/embeddings/route.ts – Text embedding generation (POST /v1/embeddings)
• src/app/api/v1/models/route.ts – Lists all models (GET /v1/models)
• src/app/api/v1/models/[...model]/route.ts – Returns specific model metadata (GET /v1/models/{model})
• src/app/api/v1/relay/chat/completions/route.ts – SSE streaming relay for real-time completions

The relay infrastructure in src/app/api/v1/relay/ provides internal request routing, load balancing, and provider abstraction for streaming responses.

Route Implementation Pattern

Every endpoint in the OmniRoute monorepo follows a consistent middleware pipeline defined within its respective route.ts file:

1. CORS pre-flight handling – Configures cross-origin resource sharing headers
2. Zod validation – Validates incoming request payloads against strict schemas
3. Optional authentication – Verifies Bearer tokens when required
4. Handler delegation – Routes the request to business logic in open-sse/handlers/

For example, the chat completions endpoint imports handleChatCore from the open-sse/handlers/ directory. After processing, responses pass through the transformer layer in open-sse/transformer/ to ensure OpenAI-compatible JSON formatting.

Catch-All Routes and Error Handling

The monorepo implements a fallback mechanism to ensure consistent error responses for undefined paths. The file src/app/api/v1/[...omnirouteCatchAll]/route.ts captures any request to /v1/* that does not match a defined route.

This catch-all handler returns a standardized error payload, preventing Next.js default 404 pages and maintaining API consistency for client integrations.

Practical Examples for Calling OmniRoute Endpoints

Because the routes follow standard HTTP conventions, you can interact with them using any HTTP client. The following examples assume a local OmniRoute instance running on port 20128.

Chat Completions Request

await fetch('http://localhost:20128/v1/chat/completions', {
  method: 'POST',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': `Bearer ${API_KEY}` 
  },
  body: JSON.stringify({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Hello, OmniRoute!' }],
    temperature: 0.7,
  }),
});

List Available Models

const res = await fetch('http://localhost:20128/v1/models', {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const { data } = await res.json();   
// data = [{ id: 'gpt-4o', ... }, …]

Streaming via Relay Route

For Server-Sent Events (SSE) streaming through the relay infrastructure:

const ev = new EventSource('http://localhost:20128/v1/relay/chat/completions/stream?model=gpt-4o');
ev.onmessage = e => console.log(e.data);

Summary

• OmniRoute API routes are located in src/app/api/ using Next.js App Router conventions
• Production endpoints are versioned under src/app/api/v1/ (OpenAI-compatible API)
• Filesystem paths map directly to URL paths (e.g., v1/chat/completions/route.ts → POST /v1/chat/completions)
• Business logic is delegated to handlers in open-sse/handlers/ and transformed via open-sse/transformer/
• Undefined routes are caught by src/app/api/v1/[...omnirouteCatchAll]/route.ts for consistent error handling

Frequently Asked Questions

How does OmniRoute handle API versioning?

OmniRoute uses filesystem-based versioning under src/app/api/. The v1 folder contains the stable, OpenAI-compatible API surface, while sibling folders (like experimental ws or web directories) house non-production routes. This structure allows developers to iterate on new versions without breaking existing integrations.

Where is the business logic for chat completions implemented?

While the route definition lives in src/app/api/v1/chat/completions/route.ts, the core processing logic is imported from open-sse/handlers/ (specifically handleChatCore). This separation of concerns keeps route files focused on HTTP-specific concerns (headers, validation, CORS) while delegating provider routing and stream management to dedicated handler modules.

What happens when I request an undefined endpoint under /v1/?

Requests to non-existent paths under /v1/* are intercepted by the catch-all route at src/app/api/v1/[...omnirouteCatchAll]/route.ts. This file exports a handler that returns a consistent JSON error payload, ensuring that clients receive predictable error responses rather than HTML 404 pages.

Can I add custom routes to OmniRoute?

Yes. Create a new folder structure under src/app/api/ (or src/app/api/v1/ for versioned endpoints) and add a route.ts file exporting the appropriate HTTP method handlers. Ensure your implementation follows the established pattern of Zod validation, optional authentication, and handler delegation to maintain consistency with the existing codebase.

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