OmniRoute API: Complete REST Reference and Integration Guide

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.

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.

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. 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, which manages the Open-SSE layer. This handler resolves target models via 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:

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:

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

Direct provider request:

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:

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
• Provider-specific chat route – src/app/api/v1/providers/[provider]/chat/completions/route.ts
• Model listing route – src/app/api/v1/models/route.ts
• Health endpoint – src/app/api/v1/health/route.ts
• Core chat handler – 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, 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.

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