# OmniRoute API: Complete REST Reference and Integration Guide

> Explore the OmniRoute API with our complete REST reference. Integrate seamlessly using OpenAI-compatible endpoints for chat completions, embeddings, and intelligent model routing.

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

---

**Yes, OmniRoute exposes a full-featured REST API under the `/v1/` namespace that provides OpenAI-compatible endpoints for chat completions, embeddings, and intelligent model routing.**

OmniRoute is an open-source LLM routing engine that unifies multiple providers behind a single interface. The **OmniRoute API** implements a RESTful architecture using Next.js App Router endpoints, offering a standardized `/v1/` namespace that mirrors OpenAI's API structure while adding advanced features like combo routing and provider fallback logic.

## Core OmniRoute API Endpoints

The API surface is organized under `src/app/api/v1/` and covers the full lifecycle of LLM interactions:

### Chat Completions

The primary endpoint `POST /v1/chat/completions` accepts standard OpenAI-compatible chat requests and routes them through the combo engine. The implementation resides in [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts).

### Embeddings

Use `POST /v1/embeddings` to generate vector representations. This follows the same validation and authentication middleware chain as chat endpoints.

### Model Discovery

`GET /v1/models` returns the complete catalog of available models across all configured providers. The route handler is defined in [`src/app/api/v1/models/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/models/route.ts).

### Provider-Specific Routing

Bypass the combo router by calling `POST /v1/providers/{provider}/chat/completions`. This targets a single provider directly, implemented in `src/app/api/v1/providers/[provider]/chat/completions/route.ts`.

### Health and Monitoring

`GET /v1/health` exposes service health status including degradation information, located at [`src/app/api/v1/health/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/health/route.ts). Additional management endpoints include `GET /v1/pricing/models` for cost metadata and `POST /v1/combos` for creating multi-model strategies.

### Authentication

The auth layer provides `POST /v1/auth/login` and `GET /v1/auth/status` endpoints, supporting API keys, OAuth, or optional no-auth modes. Configuration lives in `src/app/api/auth/*`.

## Request Processing Architecture

Every request traverses a consistent middleware pipeline: **CORS** → **Zod validation** → **optional authentication** → **request handling**.

The core orchestration happens in [`open-sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chat.ts), which manages the **Open-SSE** layer. This handler resolves target models via [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts), applies circuit-breaker and cooldown logic, and streams responses through `open-sse/executors/` back to the client in OpenAI-compatible format.

Validation schemas are strictly enforced using Zod definitions in `src/shared/validation/schemas/*`, ensuring type safety before requests reach the execution layer.

## Integration Examples

Authenticate using Bearer tokens in the Authorization header.

Simple chat request:

```bash
curl -X POST https://your.omniroute.instance/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
        "model": "gpt-4o-mini",
        "messages": [{"role":"user","content":"Hello, world!"}]
      }'

```

Fetching the model catalog:

```bash
curl https://your.omniroute.instance/v1/models \
  -H "Authorization: Bearer <API_KEY>"

```

Direct provider request:

```bash
curl -X POST https://your.omniroute.instance/v1/providers/openai/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Explain quantum tunneling"}]}'

```

Health check:

```bash
curl https://your.omniroute.instance/v1/health

```

## Key Source Files

Understanding the codebase structure helps when extending or debugging the **OmniRoute API**:

- **Chat completions route** – [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts)
- **Provider-specific chat route** – `src/app/api/v1/providers/[provider]/chat/completions/route.ts`
- **Model listing route** – [`src/app/api/v1/models/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/models/route.ts)
- **Health endpoint** – [`src/app/api/v1/health/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/health/route.ts)
- **Core chat handler** – [`open-sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chat.ts)

## Summary

- OmniRoute provides a **REST API** under the `/v1/` namespace with OpenAI-compatible endpoints.
- All routes implement **Zod validation**, **CORS**, and **authentication** middleware.
- **Combo routing** enables intelligent multi-provider failover and load balancing.
- **Provider-specific endpoints** allow direct targeting of individual LLM providers.
- The architecture separates concerns between route handlers (`src/app/api/v1/*/route.ts`), business logic (`open-sse/handlers/`), and provider executors (`open-sse/executors/`).

## Frequently Asked Questions

### Is the OmniRoute API compatible with OpenAI SDKs?

Yes, the **OmniRoute API** follows the OpenAI API specification for request and response formats. You can point official OpenAI client libraries to your OmniRoute base URL by changing the `baseURL` parameter, and existing code will function without modification.

### What authentication methods does OmniRoute support?

The API supports **API key authentication** via Bearer tokens, **OAuth** flows through the `/v1/auth/*` endpoints, and optional **no-auth mode** for development environments. Configuration is managed in `src/app/api/auth/*`.

### How does combo routing work in the OmniRoute API?

Combo routing, implemented in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts), allows you to define multi-model strategies that automatically failover between providers based on availability, latency, or cost. When you call `/v1/chat/completions`, the combo service evaluates the strategy and routes to the optimal provider.

### Can I bypass the combo router and target specific providers?

Yes. Use the `POST /v1/providers/{provider}/chat/completions` endpoint to send requests directly to a specific provider without combo logic. This is useful when you need deterministic routing to a particular model or provider.