# Where Are the API Routes Located in the OmniRoute Monorepo?

> Discover API route locations in the OmniRoute monorepo. Find public HTTP endpoints under src/app/api/, with v1 routes exposing an OpenAI-compatible API.

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

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts)** – Handles `POST /v1/chat/completions` by delegating to `handleChatCore`
- **[`src/app/api/v1/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/completions/route.ts)** – Legacy completion endpoints (`POST /v1/completions`)
- **[`src/app/api/v1/embeddings/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/embeddings/route.ts)** – Text embedding generation (`POST /v1/embeddings`)
- **[`src/app/api/v1/models/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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

```javascript
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

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

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