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

> Access complete OmniRoute API documentation for the open-source LLM gateway. Explore endpoints, authentication, schemas, and streaming in our reference guide and OpenAPI spec.

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

---

**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](https://github.com/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/API_REFERENCE.md)

### Machine-Readable OpenAPI Specification

The file [`public/openapi.yaml`](https://github.com/diegosouzapw/OmniRoute/blob/main/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](https://github.com/diegosouzapw/OmniRoute/blob/main/public/openapi.yaml)

## 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts) | Chat completions with streaming support |
| `POST /v1/embeddings` | [`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/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 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.

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts) delegates to handlers in `open-sse/handlers/` for provider-specific translation.

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

```bash

# 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:

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/API_REFERENCE.md) (human-readable) and [`public/openapi.yaml`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/API_REFERENCE.md) or [`public/openapi.yaml`](https://github.com/diegosouzapw/OmniRoute/blob/main/public/openapi.yaml) to reflect custom endpoints, then update the release checklist to preserve your changes across updates.