Where to Find API Documentation for OmniRoute: A Complete Guide

You can find OmniRoute's API documentation in two locations: a human-readable reference at docs/reference/API_REFERENCE.md and a machine-readable OpenAPI specification at 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. 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. 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 – 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 – Contains the embedding endpoint implementation for text vectorization.

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

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

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:

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:

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, 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 for human reading and 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, 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 and the OpenAPI specification at 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. 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 that requires maintainers to update docs/reference/API_REFERENCE.md and 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 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.

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