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

> Discover where OmniRoute API routes are located within the Next.js App Router at src/app/api/v1/. Understand the v1 endpoint structure and how each route is defined.

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

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/route.ts).

### Core Endpoints and Their Locations

| Endpoint | File Path | Purpose |
|----------|-----------|---------|
| `/v1/chat/completions` | [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts) | Primary LLM chat interface |
| `/v1/models` | [`src/app/api/v1/models/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/models/route.ts) | List available models |
| `/v1/images/generations` | [`src/app/api/v1/images/generations/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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)

```typescript
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)

```bash
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/main/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/main/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/main/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/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/src/app/api/v1/providers/%5Bprovider%5D/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.