Where Are OmniRoute's API Routes Located? A Complete Guide to the v1 Endpoint Structure

OmniRoute's API routes are located in src/app/api/v1/ within the Next.js App Router, with each endpoint defined in its own route.ts file.

OmniRoute exposes its HTTP API through a well-organized directory structure that follows Next.js 13+ App Router conventions. Understanding where these routes live and how they're structured is essential for anyone contributing to the codebase, debugging endpoint behavior, or extending the API with new capabilities.

OmniRoute API Routes Directory Structure

All OmniRoute API routes live under the base path:

src/app/api/v1/

The versioning scheme (v1) allows for future API iterations without breaking existing integrations. Each logical endpoint occupies its own subfolder, with the actual request handler implemented in a file named route.ts.

Core Endpoints and Their Locations

Endpoint	File Path	Purpose
/v1/chat/completions	src/app/api/v1/chat/completions/route.ts	Primary LLM chat interface
/v1/models	src/app/api/v1/models/route.ts	List available models
/v1/images/generations	src/app/api/v1/images/generations/route.ts	Image generation
/v1/providers/[provider]/models	src/app/api/v1/providers/[provider]/models/route.ts	Provider-specific model discovery

The dynamic route [provider] enables per-provider customization while maintaining a consistent interface across different LLM backends.

How the Route.ts Pattern Works

Each route.ts file exports named functions corresponding to HTTP methods: GET, POST, PUT, DELETE, etc. Next.js automatically maps these to the appropriate verb for that path.

For example, the Chat Completions endpoint in src/app/api/v1/chat/completions/route.ts exports a POST handler that:

1. Applies CORS headers via a shared helper
2. Validates the request body with Zod schemas
3. Performs optional API key authentication
4. Routes the request to the appropriate provider backend
5. Returns sanitized responses through buildErrorBody() on failure

Shared Middleware and Error Handling

All routes in src/app/api/v1/ share a common middleware stack implemented consistently across route.ts files:

• CORS handling — Applied via a cors helper to enable cross-origin requests
• Zod validation — Request parsing and schema validation before handler execution
• Optional authentication — API key or OAuth verification where required
• Error sanitization — Stack traces are suppressed via buildErrorBody() to prevent information leakage

The root file src/app/api/v1/route.ts serves as a global fallback. Any request to an undefined path under /v1/ receives a standardized 404 response from this catch-all handler.

Calling OmniRoute API Endpoints

Chat Completions Example (Node.js)

import fetch from 'node-fetch';

const response = await fetch('http://localhost:20128/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    // 'Authorization': 'Bearer <your-api-key>'  // optional
  },
  body: JSON.stringify({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: 'What is the weather today?' }],
    max_tokens: 256,
  }),
});

const data = await response.json();
console.log(data);

Models Endpoint (cURL)

curl -X GET http://localhost:20128/v1/models

Key Files for API Route Navigation

File	Purpose
[src/app/api/v1/route.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/src/app/api/v1/route.ts)	Fallback handler for undefined paths
[src/app/api/v1/chat/completions/route.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/src/app/api/v1/chat/completions/route.ts)	Main chat completion endpoint
[src/app/api/v1/models/route.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/src/app/api/v1/models/route.ts)	Model listing and metadata
[src/app/api/v1/images/generations/route.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/src/app/api/v1/images/generations/route.ts)	DALL-E compatible image generation
src/app/api/v1/providers/[provider]/models/route.ts	Dynamic provider-specific models

Adding New API Routes

To extend OmniRoute with a new endpoint:

1. Create a folder structure under src/app/api/v1/ matching your desired path
2. Add a route.ts file exporting the relevant HTTP method handlers
3. Import and apply the shared cors helper for cross-origin compatibility
4. Define Zod schemas for request validation
5. Use buildErrorBody() for consistent error responses

The convention-based structure means no manual route registration is required—Next.js discovers and mounts endpoints automatically based on the file system.

Summary

• OmniRoute's API routes are located in src/app/api/v1/ following Next.js App Router conventions
• Each endpoint is implemented in a route.ts file within its own subfolder
• The structure supports dynamic segments like [provider] for flexible routing
• Shared middleware (CORS, Zod validation, auth, error handling) is applied consistently across all routes
• src/app/api/v1/route.ts provides a global 404 fallback for undefined paths

Frequently Asked Questions

What version of the API does OmniRoute currently expose?

OmniRoute exposes version v1 as the stable API surface, with all routes nested under src/app/api/v1/. This versioning strategy allows for future v2 development without breaking existing integrations.

How do I find the handler for a specific OmniRoute endpoint?

Locate the corresponding route.ts file by mapping the URL path to the directory structure. For /v1/chat/completions, the handler lives at src/app/api/v1/chat/completions/route.ts. Each HTTP method (GET, POST, etc.) is exported as a named function from that file.

Does OmniRoute use Express or another routing library?

No—OmniRoute leverages Next.js's native App Router. Route handlers are defined directly in route.ts files without an external routing framework. This provides automatic file-system based routing, API route colocation with the frontend, and built-in middleware support.

What happens if I request an undefined API path?

Requests to non-existent paths under /v1/ are caught by src/app/api/v1/route.ts, which returns a standardized 404 response. This prevents leaking internal server details and ensures consistent error formatting across the API.

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