OmniRoute API Documentation: Complete Reference for the Open-Source LLM Gateway

Yes. OmniRoute provides comprehensive API documentation including a human-readable reference guide and a machine-readable OpenAPI/Swagger specification that covers every public endpoint, authentication method, request/response schema, and streaming capability.

The OmniRoute API documentation is maintained directly in the diegosouzapw/OmniRoute repository and kept in sync with the source code through automated release processes. This guide explains where to find the docs, how to use them, and what endpoints are available.

Where to Find the OmniRoute API Documentation

OmniRoute distributes its documentation across two primary artifacts located in predictable repository paths.

Human-Readable API Reference

The file docs/reference/API_REFERENCE.md contains the complete manual for developers. It lists every route with:

• Endpoint URLs and HTTP methods
• Required and optional parameters
• JSON request/response examples
• Type definitions for TypeScript users

Access it directly: API_REFERENCE.md on GitHub

Machine-Readable OpenAPI Specification

The file public/openapi.yaml provides a Swagger-compliant specification importable into Postman, Insomnia, Swagger UI, or any OpenAPI code generator.

Access it directly: openapi.yaml on GitHub

Core API Endpoints

OmniRoute implements an OpenAI-compatible chat completions API with additional provider-routing capabilities. The source code defines these primary routes:

Endpoint	Implementation File	Purpose
POST /v1/chat/completions	src/app/api/v1/chat/completions/route.ts	Chat completions with streaming support
POST /v1/embeddings	src/app/api/v1/embeddings/route.ts	Text embedding generation
POST /v1/images/generations	src/app/api/v1/images/generations/route.ts	Image generation via DALL-E compatible providers

All routes support bearer token authentication using the OMNIRoute_API_KEY environment variable or header.

Authentication and Request Format

OmniRoute uses standard HTTP Bearer authentication. Include your API key in the Authorization header for every request.

curl -X POST https://api.omniroute.dev/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OMNIRoute_API_KEY" \
  -d '{
        "model": "gpt-4o-mini",
        "messages": [{ "role": "user", "content": "Hello, world!" }]
      }'

The request payload follows the OpenAI chat completions schema:

• model: Target model identifier (e.g., gpt-4o-mini, claude-3-sonnet)
• messages: Array of {role, content} objects
• stream: Boolean to enable server-sent events (SSE) streaming
• temperature, max_tokens, top_p: Standard sampling parameters

Streaming Responses

Enable real-time token streaming by setting stream: true. The implementation in src/app/api/v1/chat/completions/route.ts delegates to handlers in open-sse/handlers/ for provider-specific translation.

import fetch from 'node-fetch';

const res = await fetch('https://api.omniroute.dev/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.OMNIRoute_API_KEY}`,
  },
  body: JSON.stringify({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: 'Give me a streaming joke.' }],
    stream: true,
  }),
});

// Stream SSE chunks
for await (const chunk of res.body) {
  console.log(chunk.toString());
}

Generating Client SDKs from the OpenAPI Spec

The OpenAPI specification enables automatic client generation in any supported language.

TypeScript/Axios Client

# Install openapi-generator-cli

openapi-generator-cli generate \
  -i https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/public/openapi.yaml \
  -g typescript-axios \
  -o ./omniroute-client

Using the generated client:

import { DefaultApi } from './omniroute-client';

const api = new DefaultApi({ basePath: 'https://api.omniroute.dev/v1' });

api.chatCompletionsCreate({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Hello, world!' }],
}).then(resp => console.log(resp.data));

Data Layer and Quota Management

API routes integrate with SQLite persistence via src/lib/db/ for:

• Quota tracking: Request limits per API key
• Combo management: Provider routing rules
• Provider state: Failover and load balancing data

These mechanisms are transparent to API consumers but documented in the reference for self-hosted deployments.

Documentation Maintenance and Versioning

According to the release checklist in docs/ops/RELEASE_CHECKLIST.md, maintainers must regenerate both documentation artifacts before every release. This ensures the API documentation always matches the deployed behavior.

To verify your local deployment against the current spec:

1. Download public/openapi.yaml from your deployed commit
2. Import into Swagger UI or run swagger-codegen validate -i openapi.yaml

Summary

• Primary documentation location: docs/reference/API_REFERENCE.md (human-readable) and public/openapi.yaml (machine-readable)
• Authentication: Bearer token via Authorization header
• Compatible endpoints: /v1/chat/completions, /v1/embeddings, /v1/images/generations
• Streaming: Enabled via stream: true with SSE response format
• Client generation: Supported for all OpenAPI-compatible tools and languages
• Sync guarantees: Documentation updates are enforced by release checklist automation

Frequently Asked Questions

How do I import the OmniRoute API into Postman?

Download the raw public/openapi.yaml file from the repository and use Postman's Import → OpenAPI 3.0 feature. The specification automatically populates collections with all endpoints, example requests, and response schemas.

Does OmniRoute follow the OpenAI API specification exactly?

OmniRoute maintains ** compatibility** for chat completions, embeddings, and image generations. The core routing logic in src/app/api/v1/chat/completions/route.ts handles provider-specific adaptations internally while exposing a uniform interface.

Can I self-host OmniRoute and customize the API documentation?

Yes. The documentation files are static assets in the repository. Modify docs/reference/API_REFERENCE.md or public/openapi.yaml to reflect custom endpoints, then update the release checklist to preserve your changes across updates.

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