API Reference (Română)

May 13, 2026 · View on GitHub

🌐 Languages: 🇺🇸 English · 🇸🇦 ar · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇪🇸 es · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇳 gu · 🇮🇱 he · 🇮🇳 hi · 🇭🇺 hu · 🇮🇩 id · 🇮🇹 it · 🇯🇵 ja · 🇰🇷 ko · 🇮🇳 mr · 🇲🇾 ms · 🇳🇱 nl · 🇳🇴 no · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇸🇰 sk · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇻🇳 vi · 🇨🇳 zh-CN

Complete reference for all OmniRoute API endpoints.

Chat Completions
Embeddings
Image Generation
List Models
Compatibility Endpoints
Semantic Cache
Dashboard & Management
Request Processing
Authentication

Chat Completions

POST /v1/chat/completions
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "Write a function to..."}
  ],
  "stream": true
}

Custom Headers

Header	Direction	Description
`X-OmniRoute-No-Cache`	Request	Set to `true` to bypass cache
`X-OmniRoute-Progress`	Request	Set to `true` for progress events
`X-Session-Id`	Request	Sticky session key for external session affinity
`x_session_id`	Request	Underscore variant also accepted (direct HTTP)
`Idempotency-Key`	Request	Dedup key (5s window)
`X-Request-Id`	Request	Alternative dedup key
`X-OmniRoute-Cache`	Response	`HIT` or `MISS` (non-streaming)
`X-OmniRoute-Idempotent`	Response	`true` if deduplicated
`X-OmniRoute-Progress`	Response	`enabled` if progress tracking on
`X-OmniRoute-Session-Id`	Response	Effective session ID used by OmniRoute

Nginx note: if you rely on underscore headers (for example x_session_id), enable underscores_in_headers on;.

Embeddings

POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "nebius/Qwen/Qwen3-Embedding-8B",
  "input": "The food was delicious"
}

Available providers: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, GitHub Models.

# List all embedding models
GET /v1/embeddings

Image Generation

POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "openai/gpt-image-2",
  "prompt": "A beautiful sunset over mountains",
  "size": "1024x1024"
}

Available providers: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, SD WebUI (local), ComfyUI (local).

# List all image models
GET /v1/images/generations

List Models

GET /v1/models
Authorization: Bearer your-api-key

→ Returns all chat, embedding, and image models + combos in OpenAI format

Compatibility Endpoints

Method	Path	Format
POST	`/v1/chat/completions`	OpenAI
POST	`/v1/messages`	Anthropic
POST	`/v1/responses`	OpenAI Responses
POST	`/v1/embeddings`	OpenAI
POST	`/v1/images/generations`	OpenAI
GET	`/v1/models`	OpenAI
POST	`/v1/messages/count_tokens`	Anthropic
GET	`/v1beta/models`	Gemini
POST	`/v1beta/models/{...path}`	Gemini generateContent
POST	`/v1/api/chat`	Ollama

Dedicated Provider Routes

POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations

The provider prefix is auto-added if missing. Mismatched models return 400.

Semantic Cache

# Get cache stats
GET /api/cache/stats

# Clear all caches
DELETE /api/cache/stats

Response example:

{
  "semanticCache": {
    "memorySize": 42,
    "memoryMaxSize": 500,
    "dbSize": 128,
    "hitRate": 0.65
  },
  "idempotency": {
    "activeKeys": 3,
    "windowMs": 5000
  }
}

Dashboard & Management

Authentication

Endpoint	Method	Description
`/api/auth/login`	POST	Login
`/api/auth/logout`	POST	Logout
`/api/settings/require-login`	GET/PUT	Toggle login required

Provider Management

Endpoint	Method	Description
`/api/providers`	GET/POST	List / create providers
`/api/providers/[id]`	GET/PUT/DELETE	Manage a provider
`/api/providers/[id]/test`	POST	Test provider connection
`/api/providers/[id]/models`	GET	List provider models
`/api/providers/validate`	POST	Validate provider config
`/api/provider-nodes*`	Various	Provider node management
`/api/provider-models`	GET/POST/PATCH/DELETE	Custom models (add, update, hide/show, delete)

OAuth Flows

Endpoint	Method	Description
`/api/oauth/[provider]/[action]`	Various	Provider-specific OAuth

Routing & Config

Endpoint	Method	Description
`/api/models/alias`	GET/POST	Model aliases
`/api/models/catalog`	GET	All models by provider + type
`/api/combos*`	Various	Combo management
`/api/keys*`	Various	API key management
`/api/pricing`	GET	Model pricing

Usage & Analytics

Endpoint	Method	Description
`/api/usage/history`	GET	Usage history
`/api/usage/logs`	GET	Usage logs
`/api/usage/request-logs`	GET	Request-level logs
`/api/usage/[connectionId]`	GET	Per-connection usage

Settings

Endpoint	Method	Description
`/api/settings`	GET/PUT/PATCH	General settings
`/api/settings/proxy`	GET/PUT	Network proxy config
`/api/settings/proxy/test`	POST	Test proxy connection
`/api/settings/ip-filter`	GET/PUT	IP allowlist/blocklist
`/api/settings/thinking-budget`	GET/PUT	Reasoning token budget
`/api/settings/system-prompt`	GET/PUT	Global system prompt

Monitoring

Endpoint	Method	Description
`/api/sessions`	GET	Active session tracking
`/api/rate-limits`	GET	Per-account rate limits
`/api/monitoring/health`	GET	Health check + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`)
`/api/cache/stats`	GET/DELETE	Cache stats / clear

Backup & Export/Import

Endpoint	Method	Description
`/api/db-backups`	GET	List available backups
`/api/db-backups`	PUT	Create a manual backup
`/api/db-backups`	POST	Restore from a specific backup
`/api/db-backups/export`	GET	Download database as .sqlite file
`/api/db-backups/import`	POST	Upload .sqlite file to replace database
`/api/db-backups/exportAll`	GET	Download full backup as .tar.gz archive

Cloud Sync

Endpoint	Method	Description
`/api/sync/cloud`	Various	Cloud sync operations
`/api/sync/initialize`	POST	Initialize sync
`/api/cloud/*`	Various	Cloud management

Tunnels

Endpoint	Method	Description
`/api/tunnels/cloudflared`	GET	Read Cloudflare Quick Tunnel install/runtime status for the dashboard
`/api/tunnels/cloudflared`	POST	Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`)

CLI Tools

Endpoint	Method	Description
`/api/cli-tools/claude-settings`	GET	Claude CLI status
`/api/cli-tools/codex-settings`	GET	Codex CLI status
`/api/cli-tools/droid-settings`	GET	Droid CLI status
`/api/cli-tools/openclaw-settings`	GET	OpenClaw CLI status
`/api/cli-tools/runtime/[toolId]`	GET	Generic CLI runtime

CLI responses include: installed, runnable, command, commandPath, runtimeMode, reason.

ACP Agents

Endpoint	Method	Description
`/api/acp/agents`	GET	List all detected agents (built-in + custom) with status
`/api/acp/agents`	POST	Add custom agent or refresh detection cache
`/api/acp/agents`	DELETE	Remove a custom agent by `id` query param

GET response includes agents[] (id, name, binary, version, installed, protocol, isCustom) and summary (total, installed, notFound, builtIn, custom).

Resilience & Rate Limits

Endpoint	Method	Description
`/api/resilience`	GET/PATCH	Get/update request queue, connection cooldown, provider breaker, and wait settings
`/api/resilience/reset`	POST	Reset provider circuit breakers
`/api/rate-limits`	GET	Per-account rate limit status
`/api/rate-limit`	GET	Global rate limit configuration

Evals

Endpoint	Method	Description
`/api/evals`	GET/POST	List eval suites / run evaluation

Policies

Endpoint	Method	Description
`/api/policies`	GET/POST/DELETE	Manage routing policies

Compliance

Endpoint	Method	Description
`/api/compliance/audit-log`	GET	Compliance audit log (last N)

v1beta (Gemini-Compatible)

Endpoint	Method	Description
`/v1beta/models`	GET	List models in Gemini format
`/v1beta/models/{...path}`	POST	Gemini `generateContent` endpoint

These endpoints mirror Gemini's API format for clients that expect native Gemini SDK compatibility.

Internal / System APIs

Endpoint	Method	Description
`/api/init`	GET	Application initialization check (used on first run)
`/api/tags`	GET	Ollama-compatible model tags (for Ollama clients)
`/api/restart`	POST	Trigger graceful server restart
`/api/shutdown`	POST	Trigger graceful server shutdown
`/api/system/env/repair`	POST	Repair OAuth provider environment variables
`/api/system-info`	GET	Generate system diagnostics report

Note: These endpoints are used internally by the system or for Ollama client compatibility. They are not typically called by end users.

OAuth Environment Repair (v3.6.1+)

POST /api/system/env/repair
Content-Type: application/json

{
  "provider": "claude-code"
}

Repairs missing or corrupted OAuth environment variables for a specific provider. Returns:

{
  "success": true,
  "repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
  "backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
}

Audio Transcription

POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data

Transcribe audio files using Deepgram or AssemblyAI.

Request:

curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@recording.mp3" \
  -F "model=deepgram/nova-3"

Response:

{
  "text": "Hello, this is the transcribed audio content.",
  "task": "transcribe",
  "language": "en",
  "duration": 12.5
}

Supported providers: deepgram/nova-3, assemblyai/best.

Supported formats: mp3, wav, m4a, flac, ogg, webm.

Ollama Compatibility

For clients that use Ollama's API format:

# Chat endpoint (Ollama format)
POST /v1/api/chat

# Model listing (Ollama format)
GET /api/tags

Requests are automatically translated between Ollama and internal formats.

Telemetry

# Get latency telemetry summary (p50/p95/p99 per provider)
GET /api/telemetry/summary

Response:

{
  "providers": {
    "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
    "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
  }
}

Budget

# Get budget status for all API keys
GET /api/usage/budget

# Set or update a budget
POST /api/usage/budget
Content-Type: application/json

{
  "keyId": "key-123",
  "limit": 50.00,
  "period": "monthly"
}

Request Processing

Client sends request to /v1/*
Route handler calls handleChat, handleEmbedding, handleAudioTranscription, or handleImageGeneration
Model is resolved (direct provider/model or alias/combo)
Credentials selected from local DB with account availability filtering
For chat: handleChatCore — format detection, translation, cache check, idempotency check
Provider executor sends upstream request
Response translated back to client format (chat) or returned as-is (embeddings/images/audio)
Usage/logging recorded
Fallback applies on errors according to combo rules

Full architecture reference: ARCHITECTURE.md

Authentication

Dashboard routes (/dashboard/*) use auth_token cookie
Login uses saved password hash; fallback to INITIAL_PASSWORD
requireLogin toggleable via /api/settings/require-login
/v1/* routes optionally require Bearer API key when REQUIRE_API_KEY=true