# Where to Find API Documentation for OmniRoute: A Complete Guide

> Find OmniRoute API documentation easily. Access human-readable guides and machine-readable OpenAPI specs in sync with releases for seamless integration.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-11

---

**You can find OmniRoute's API documentation in two locations: a human-readable reference at [`docs/reference/API_REFERENCE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/API_REFERENCE.md) and a machine-readable OpenAPI specification at [`public/openapi.yaml`](https://github.com/diegosouzapw/OmniRoute/blob/main/public/openapi.yaml), both kept in sync with every release.**

The **OmniRoute** service (available at `diegosouzapw/OmniRoute` on GitHub) provides unified routing for AI model APIs. Whether you are integrating chat completions, embeddings, or image generation, understanding where to find accurate **API documentation for OmniRoute** ensures you can implement requests correctly and generate compatible clients automatically.

## Official API Documentation Locations

OmniRoute maintains dual documentation tracks to serve both manual readers and automated tooling.

### Human-Readable API Reference

The primary reference document lives at [`docs/reference/API_REFERENCE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/API_REFERENCE.md). This file contains a concise, human-readable list of all public endpoints, complete with example curl commands, request/response payload definitions, and authentication requirements.

This markdown file is version-controlled and directly accessible via GitHub, making it the fastest way to understand endpoint behavior without parsing machine specifications.

### Machine-Readable OpenAPI Specification

For automated integration, OmniRoute ships a complete **OpenAPI (Swagger)** specification at [`public/openapi.yaml`](https://github.com/diegosouzapw/OmniRoute/blob/main/public/openapi.yaml). This YAML file describes every route, schema, and security scheme in a standardized format compatible with Postman, Insomnia, and OpenAPI client generators.

The specification supports automatic client generation in languages like TypeScript, Python, and Go, ensuring type-safe interactions with the service.

## Key Implementation Files

Beyond documentation, the source code reveals implementation details for advanced debugging. The following files constitute the core API surface:

- **[`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts)** – Implements the `/v1/chat/completions` endpoint, handling core routing logic, request validation, and Server-Sent Events (SSE) streaming.

- **[`src/app/api/v1/embeddings/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/embeddings/route.ts)** – Contains the embedding endpoint implementation for text vectorization.

- **[`src/app/api/v1/images/generations/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/images/generations/route.ts)** – Powers the image generation workflow.

- **`src/lib/db/`** – Houses the SQLite persistence layer used by API routes for quota management, combo tracking, and provider data throttling.

- **`open-sse/handlers/`** – Contains the streaming engine that translates OmniRoute requests into provider-specific formats for real-time responses.

## How to Use the OpenAPI Specification

Import the specification into your toolchain to generate typed clients or validate requests.

### Generating a TypeScript Client

Use the OpenAPI Generator CLI to create a type-safe client:

```bash

# Install the OpenAPI client generator

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

```

Then consume 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));

```

### Manual curl Requests

For quick testing without client generation, the API reference provides curl templates:

```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!" }]
      }'

```

## Streaming API Examples

OmniRoute supports streaming responses via Server-Sent Events. Implement streaming in Node.js using the native fetch API:

```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());
}

```

According to the [`docs/ops/RELEASE_CHECKLIST.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/RELEASE_CHECKLIST.md), maintainers must update both documentation files whenever new endpoints are added, ensuring the docs remain synchronized with the implementation in `src/app/api/v1/`.

## Summary

- **Primary documentation** resides in [`docs/reference/API_REFERENCE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/API_REFERENCE.md) for human reading and [`public/openapi.yaml`](https://github.com/diegosouzapw/OmniRoute/blob/main/public/openapi.yaml) for machine processing.
- **Implementation details** are found in `src/app/api/v1/` routes, with specific logic for chat completions, embeddings, and image generation.
- **Client generation** is supported via the OpenAPI specification, enabling automatic TypeScript, Python, or other language client creation.
- **Documentation synchronization** is enforced through the release checklist at [`docs/ops/RELEASE_CHECKLIST.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/RELEASE_CHECKLIST.md), guaranteeing accuracy with each update.

## Frequently Asked Questions

### Where is the OmniRoute API documentation hosted?

The documentation is hosted directly in the GitHub repository at `diegosouzapw/OmniRoute`. You can view the human-readable reference at [`docs/reference/API_REFERENCE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/API_REFERENCE.md) and the OpenAPI specification at [`public/openapi.yaml`](https://github.com/diegosouzapw/OmniRoute/blob/main/public/openapi.yaml). Both files are accessible via raw GitHub URLs for integration into documentation generators or IDEs.

### What format does the OmniRoute API specification use?

OmniRoute uses the **OpenAPI 3.0** (Swagger) format for its machine-readable specification, located at [`public/openapi.yaml`](https://github.com/diegosouzapw/OmniRoute/blob/main/public/openapi.yaml). This standard format allows import into Postman, Swagger UI, and automated client generators like `openapi-generator-cli`.

### How does OmniRoute keep documentation synchronized with code changes?

The repository maintains a release checklist at [`docs/ops/RELEASE_CHECKLIST.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/ops/RELEASE_CHECKLIST.md) that requires maintainers to update [`docs/reference/API_REFERENCE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/API_REFERENCE.md) and [`public/openapi.yaml`](https://github.com/diegosouzapw/OmniRoute/blob/main/public/openapi.yaml) whenever new endpoints are added to `src/app/api/v1/`. This process ensures the documentation remains the authoritative source of truth for the current API version.

### Can I generate a client library from the OmniRoute documentation?

Yes. The [`public/openapi.yaml`](https://github.com/diegosouzapw/OmniRoute/blob/main/public/openapi.yaml) file supports standard OpenAPI client generation tools. You can generate TypeScript, Python, Java, or other language clients using tools like OpenAPI Generator or Swagger Codegen, pointing them to the raw YAML URL from the repository.