Documentation - v3.1.9

OmniRoute Docs

AI gateway for multi-provider LLMs. One endpoint for OpenAI, Anthropic, Gemini, GitHub Copilot, Claude Code, Cursor, and 20+ more providers.

Open Dashboard Endpoint Page GitHub open_in_new Report Issue

Quick Start

1. Install and run
Run npx omniroute or clone from GitHub and run npm start.
2. Create API key
Go to Endpoint -> Registered Keys. Generate one key per environment.
3. Connect providers
Add provider accounts via OAuth login, API key, or free-tier auto-connect.
4. Set client base URL
Point your IDE or API client to https://<host>/v1. Use provider prefix, for example gh/gpt-5.1-codex.

Features

hub

Multi-Provider Routing

Route requests to 30+ AI providers through a single OpenAI-compatible endpoint. Supports chat, responses, audio, and image APIs.

layers

Combos and Balancing

Create model combos with fallback chains and balancing strategies: round-robin, priority, random, least-used, and cost-optimized.

bar_chart

Usage and Cost Tracking

Real-time token counting, cost calculation per provider/model, and detailed usage breakdown by API key and account.

analytics

Analytics Dashboard

Visual analytics with charts for requests, tokens, errors, latency, costs, and model popularity over time.

health_and_safety

Health Monitoring

Live health checks, provider status, circuit breaker states, and automatic rate limit detection with exponential backoff.

terminal

CLI Tools

Manage IDE configurations, export/import backups, discover codex profiles, and configure settings from the dashboard.

shield

Security and Policies

API key authentication, IP filtering, prompt injection guard, domain policies, session management, and audit logging.

cloud_sync

Cloud Sync

Sync your configuration to Cloudflare Workers for remote access with encrypted credentials and automatic failover.

Supported Providers

67 providers across three connection types.

Manage Providers

Free Tier

4 providers

iFlow AIif/

Qwen Codeqw/

Gemini CLIgc/

Kiro AIkr/

OAuth

8 providers

Claude Codecc/

Antigravityag/

OpenAI Codexcx/

GitHub Copilotgh/

Cursor IDEcu/

Kimi Codingkmc/

Kilo Codekc/

Clinecl/

API Key

55 providers

OpenRouteropenrouter/

GLM Codingglm/

Alibaba Coding Planbcp/

Kimikimi/

Kimi Coding (API Key)kmca/

Minimax Codingminimax/

Minimax (China)minimax-cn/

Alibabaalicode/

Alibaba Intlalicode-intl/

OpenAIopenai/

Anthropicanthropic/

Gemini (Google AI Studio)gemini/

DeepSeekds/

Groqgroq/

Blackbox AIbb/

xAI (Grok)xai/

Mistralmistral/

Perplexitypplx/

Together AItogether/

Fireworks AIfireworks/

Cerebrascerebras/

Coherecohere/

NVIDIA NIMnvidia/

Nebius AInebius/

SiliconFlowsiliconflow/

Hyperbolichyp/

Deepgramdg/

AssemblyAIaai/

NanoBanananb/

Ollama Cloudollamacloud/

ElevenLabsel/

Cartesiacartesia/

PlayHTplayht/

Inworldinworld/

SD WebUIsdwebui/

ComfyUIcomfyui/

HuggingFacehf/

Syntheticsynthetic/

Kilo Gatewaykg/

Vertex AIvertex/

Z.AIzai/

Perplexity Searchpplx-search/

Serper Searchserper-search/

Brave Searchbrave-search/

Exa Searchexa-search/

Tavily Searchtavily-search/

OpenCode Zenopencode-zen/

OpenCode Goopencode-go/

Alibaba Cloud (DashScope)ali/

LongCat AIlc/

Pollinations AIpol/

Puter AIpu/

Cloudflare Workers AIcf/

Scaleway AIscw/

AI/ML APIaiml/

Common Use Cases

Single endpoint for many providers

Point clients to one base URL and route by model prefix (for example: gh/, cc/, kr/, openai/).

Fallback and model switching with combos

Create combo models in Dashboard and keep client config stable while providers rotate internally.

Usage, cost and debug visibility

Track tokens and cost by provider, account, and API key in Usage and Analytics tabs.

Client Compatibility

Cherry Studio

Base URL: https://<host>/v1
Chat endpoint: /chat/completions
Model recommendation: explicit prefix (gh/..., cc/...)

Codex / GitHub Copilot Models

Use model IDs with gh/.
Codex-family models auto-route to /responses.
Non-Codex models continue on /chat/completions.

Cursor IDE

Use cu/ prefix for Cursor models.
OAuth connection - login from the Providers page.
Supports both chat and responses endpoints.

Claude Code / Antigravity

Use cc/ (Claude) or ag/ (Antigravity) prefix.
OAuth connection with automatic token refresh.
Full streaming support for all models.

Protocols: MCP & A2A

OmniRoute exposes two operational protocols in addition to OpenAI-compatible APIs: MCP for tool execution and A2A for agent-to-agent workflows.

MCP (Model Context Protocol)

Use MCP over stdio to let clients discover and call OmniRoute tools with audit visibility.

Start MCP transport with `omniroute --mcp`.
Point your MCP client to stdio transport.
Call `omniroute_get_health` and `omniroute_list_combos` to validate connectivity.

omniroute --mcp

A2A (Agent2Agent)

Use A2A JSON-RPC to submit tasks synchronously or via SSE streaming.

Read `/.well-known/agent.json` for agent discovery.
Send `message/send` or `message/stream` requests to `POST /a2a`.
Manage task lifecycle with `tasks/get` and `tasks/cancel`.

GET /.well-known/agent.json
POST /a2a  (JSON-RPC: message/send | message/stream)

Protocol Troubleshooting

If MCP status is offline, verify the stdio process is running and heartbeat file is updating.
If A2A tasks stay in `working`, inspect `/api/a2a/tasks/:id` and stream events for terminal state.
Use `/dashboard/mcp` and `/dashboard/a2a` for operational controls and audit visibility.

API Reference

Method	Path	Notes
`POST`	/v1/chat/completions	OpenAI-compatible chat endpoint (default).
`POST`	/v1/responses	Responses API endpoint (Codex, o-series).
`GET`	/v1/models	Model catalog for all connected providers.
`POST`	/v1/embeddings	Text embedding generation (OpenAI, Cohere, Voyage).
`POST`	/v1/audio/transcriptions	Audio transcription (Deepgram, AssemblyAI).
`POST`	/v1/audio/speech	Text-to-speech generation (ElevenLabs, OpenAI TTS).
`POST`	/v1/images/generations	Image generation (NanoBanana).
`POST`	/chat/completions	Rewrite helper for clients without /v1.
`POST`	/responses	Rewrite helper for Responses without /v1.
`GET`	/models	Rewrite helper for model discovery without /v1.

Model Prefixes

Use the provider prefix before the model name to route to a specific provider. Example: gh/gpt-5.1-codex routes to GitHub Copilot.

Prefix	Provider	Type
`if/`	iFlow AI	Free Tier
`qw/`	Qwen Code	Free Tier
`gc/`	Gemini CLI	Free Tier
`kr/`	Kiro AI	Free Tier
`cc/`	Claude Code	OAuth
`ag/`	Antigravity	OAuth
`cx/`	OpenAI Codex	OAuth
`gh/`	GitHub Copilot	OAuth
`cu/`	Cursor IDE	OAuth
`kmc/`	Kimi Coding	OAuth
`kc/`	Kilo Code	OAuth
`cl/`	Cline	OAuth
`openrouter/`	OpenRouter	API Key
`glm/`	GLM Coding	API Key
`bcp/`	Alibaba Coding Plan	API Key
`kimi/`	Kimi	API Key
`kmca/`	Kimi Coding (API Key)	API Key
`minimax/`	Minimax Coding	API Key
`minimax-cn/`	Minimax (China)	API Key
`alicode/`	Alibaba	API Key
`alicode-intl/`	Alibaba Intl	API Key
`openai/`	OpenAI	API Key
`anthropic/`	Anthropic	API Key
`gemini/`	Gemini (Google AI Studio)	API Key
`ds/`	DeepSeek	API Key
`groq/`	Groq	API Key
`bb/`	Blackbox AI	API Key
`xai/`	xAI (Grok)	API Key
`mistral/`	Mistral	API Key
`pplx/`	Perplexity	API Key
`together/`	Together AI	API Key
`fireworks/`	Fireworks AI	API Key
`cerebras/`	Cerebras	API Key
`cohere/`	Cohere	API Key
`nvidia/`	NVIDIA NIM	API Key
`nebius/`	Nebius AI	API Key
`siliconflow/`	SiliconFlow	API Key
`hyp/`	Hyperbolic	API Key
`dg/`	Deepgram	API Key
`aai/`	AssemblyAI	API Key
`nb/`	NanoBanana	API Key
`ollamacloud/`	Ollama Cloud	API Key
`el/`	ElevenLabs	API Key
`cartesia/`	Cartesia	API Key
`playht/`	PlayHT	API Key
`inworld/`	Inworld	API Key
`sdwebui/`	SD WebUI	API Key
`comfyui/`	ComfyUI	API Key
`hf/`	HuggingFace	API Key
`synthetic/`	Synthetic	API Key
`kg/`	Kilo Gateway	API Key
`vertex/`	Vertex AI	API Key
`zai/`	Z.AI	API Key
`pplx-search/`	Perplexity Search	API Key
`serper-search/`	Serper Search	API Key
`brave-search/`	Brave Search	API Key
`exa-search/`	Exa Search	API Key
`tavily-search/`	Tavily Search	API Key
`opencode-zen/`	OpenCode Zen	API Key
`opencode-go/`	OpenCode Go	API Key
`ali/`	Alibaba Cloud (DashScope)	API Key
`lc/`	LongCat AI	API Key
`pol/`	Pollinations AI	API Key
`pu/`	Puter AI	API Key
`cf/`	Cloudflare Workers AI	API Key
`scw/`	Scaleway AI	API Key
`aiml/`	AI/ML API	API Key

Management API Reference

Automation endpoints for proxy registry, scope assignments, and legacy proxy migration.

Method	Path	Notes
`GET`	/api/v1/management/proxies	List saved proxy registry items (supports pagination).
`POST`	/api/v1/management/proxies	Create a reusable proxy item in the registry.
`GET`	/api/v1/management/proxies/health	Get 24h/rolling health metrics per saved proxy from proxy logs.
`PUT`	/api/v1/management/proxies/bulk-assign	Assign or clear one proxy across many scope IDs in one request.
`GET`	/api/v1/management/proxies/assignments	List proxy assignments by scope, scope_id, or proxy_id.
`PUT`	/api/v1/management/proxies/assignments	Assign or clear proxy for global/provider/account/combo scope.
`POST`	/api/settings/proxies/migrate	Import legacy proxyConfig maps into registry assignments.

Troubleshooting

If the client fails with model routing, use explicit provider/model (for example: gh/gpt-5.1-codex).
If you receive ambiguous model errors, pick a provider prefix instead of a bare model ID.
For GitHub Codex-family models, keep model as gh/codex-model; router selects /responses automatically.
Use Dashboard > Providers > Test Connection before testing from IDEs or external clients.
If a provider shows circuit breaker open, wait for the cooldown or check Health page for details.
For OAuth providers, re-authenticate if tokens expire. Check the provider card status indicator.

Loading OmniRoute...