mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-09-14 10:52:17 +03:00

Files

Diego Rodrigues de Sa e Souza 9debec71ec feat(i18n): 9 new locales — all 24 official EU languages (51 locales) (#13044 )

Batch 1 of the locale expansion: Greek, Croatian, Serbian, Lithuanian, Estonian, Latvian, Slovenian, Maltese and Irish across the dashboard catalog, docs mirrors, CLI catalog, README, locale index and the site. 42 → 51 locales.

Also fixes the ICU literal escape the translation backend dropped around angle placeholders, four translations that invented or renamed a placeholder, the language bars that linked to mirrors that do not exist, and the migration count drift (171 → 172).

⚠️ base-red inherited: #12732 — the four unit shards and Fast Quality Gates fail identically on unrelated PRs cut from the same base.

2026-09-10 10:13:09 -03:00

134 KiB

Raw Blame History

API_REFERENCE (Српски)

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

title: "API Reference" version: 3.8.51 lastUpdated: 2026-08-31

API Reference

Основна референца за OmniRoute API. Обухвата јавну /v1 површину и најчешће коришћене крајње тачке за управљање; машински читљив docs/openapi.yaml и стабло рута под src/app/api/ представљају потпуне изворе.

Садржај

Chat Completions
Exclusive Managed Session Leases
Embeddings
Image Generation
Document OCR
List Models
Provider Plugin Manifest
Compatibility Endpoints
Files API
Batches API
Search API
WebSocket Streaming
Quotas & Issues Reporting
Semantic Cache
Dashboard & Management
Combo Management
Webhooks
Registered Keys (Auto-Management)
Agents Protocol
Management Proxies
Resilience (extended)
Skills
Memory
MCP Server
A2A Server
Cloud, Evals & Assess
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
}

Прилагођена заглавља

Заглавље	Смер	Опис
`X-OmniRoute-No-Cache`	Захтев	Поставите на `true` да заобиђете кеш
`x-omniroute-no-memory`	Захтев	Поставите на `true` да прескочите убацивање памћења + вештина за овај захтев (по узору на no-cache; избегава додатни трошак токена/цене по позиву)
`X-OmniRoute-Progress`	Захтев	Поставите на `true` за догађаје напредовања
`X-Session-Id`	Захтев	Стални кључ сесије за спољашњу афинитет сесије
`x_session_id`	Захтев	Прихватљива је и варијанта са доњом цртом (директан HTTP)
`X-OmniRoute-Session-Id`	Захтев	Ознака сесије/конверзације коју доставља позивач (такође утиче на памћење). Када је присутна, чува се дословно у `call_logs.session_tag` за атрибуцију трошкова по сесији (#8249) — никада се не генерише самостално када недостаје
`Idempotency-Key`	Захтев	Кључ за дедупликацију (прозор од 5с)
`X-Request-Id`	Захтев	Алтернативни кључ за дедупликацију
`X-OmniRoute-Cache`	Одговор	`HIT` или `MISS` (без стримовања)
`X-OmniRoute-Idempotent`	Одговор	`true` ако је дедуплицирано
`X-OmniRoute-Progress`	Одговор	`enabled` ако је праћење напредовања укључено
`X-OmniRoute-Session-Id`	Одговор	Ефективни ID сесије који користи OmniRoute
`X-OmniRoute-Request-Id`	Одговор	ID корелације захтева (када је познат)
`X-OmniRoute-Version`	Одговор	Верзија OmniRoute билда (увек присутна)
`X-OmniRoute-Cost-Saved`	Одговор	Износ у USD који је кеш избегао приликом HIT-а (само за кеш погодке)
`X-OmniRoute-Decision`	Одговор	Траг рутирања: `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` је стратегија комбинације, или `single` за захтев који није комбинован) — увек присутно у одговорима на завршене захтеве

Напомена о Nginx-у: ако се ослањате на заглавља са доњом цртом (на пример, x_session_id), омогућите underscores_in_headers on;.

Заглавља за телеметрију трошкова: одговори са успешним завршетком без стримовања такође носе скуп X-OmniRoute-* заглавља за телеметрију трошкова — X-OmniRoute-Response-Cost (у USD, фиксно на 10 децимала; 0.0000000000 за бесплатне/непроцењене случајеве), X-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out, X-OmniRoute-Model, X-OmniRoute-Provider, X-OmniRoute-Latency-Ms, X-OmniRoute-Cache-Hit, и X-OmniRoute-Fallback-Attempts (само када је > 0), као и X-OmniRoute-Request-Id и X-OmniRoute-Version. Ова заглавља генеришу chat completions, /v1/responses, /v1/messages, и медијски крајњи endpoint-и — /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/rerank, /v1/videos/generations, /v1/music/generations, и /v1/moderations (увек трошак 0). Трошак медија се израчунава по модалитету (по слици, по секунди, по карактеру, по јединици претраге) када је доступна ценовна информација, у супротном 0 (fail-open — не блокира при грешци).

Семантика трошка код кеш погодка (cache-hit): приликом семантичког кеш погодка (X-OmniRoute-Cache-Hit: true) не позива се провајдер узводно, тако да је X-OmniRoute-Response-Cost 0.0000000000 (инкрементални трошак опслуживања погодка). Оригинални/потенцијални трошак се пријављује одвојено у X-OmniRoute-Cost-Saved. Потрошачи наплате треба да сабирају X-OmniRoute-Response-Cost (погоци не коштају ништа); аналитика кеша може агрегирати X-OmniRoute-Cost-Saved.

Ексклузивни закупи управљане сесије

Ексклузивно закупљивање управљане сесије је опциони, клијентски неутралан рутирајући уговор: један активни власник држи једну подобну OmniRoute везу. Он не закупљује модел, не захтева OAuth, не идентификује одређеног клијента, ни не захтева одређеног провајдера.

API кључ који врши аутентикацију мора имати опсег lease:exclusive и експлицитну непразну листу allowedConnections. Граница мутације базе података намеће оба поља заједно приликом креирања кључа и делимичних ажурирања.

POST /api/v1/session-leases
Authorization: Bearer <managed-api-key>
Content-Type: application/json
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>

{"action":"acquire","model":"glm/glm-4.6"}

Успешни одговори на acquire, renew и release излажу временске ознаке, state и тачну позитивну вредност generation, али никада изабрану везу или креденцијале. Renew и release достављају generation у JSON телу:

{ "action": "renew", "generation": 1 }

{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }

Активни власник закупа може експлицитно затражити приватносно безбедне метаподатке приказа за своје тренутно везивање:

{ "action": "status", "generation": 1 }

{
  "state": "ACTIVE",
  "generation": 1,
  "acquiredAt": "2026-08-28T12:00:00.000Z",
  "renewedAt": "2026-08-28T12:00:30.000Z",
  "expiresAt": "2026-08-28T12:02:30.000Z",
  "connection": {
    "displayName": "Primary Codex",
    "provider": "codex"
  }
}

Ова опциона акција статуса је оивичена непрозирним власником, аутентикованим управљаним API кључем и тачном активном generation вредношћу у једној трансакцији базе података. displayName је само подрезано конфигурисано име везе; вредност је null када не постоји безбедно конфигурисано име. OmniRoute никада не замењује имејл или генерисан идентитет налога. Вредност provider је ознака приказа без осетљивих података и никада генерисан идентификатор компатибилног провајдера. Креденцијали, токени, колачићи (cookies), сирови идентификатори везе или API кључа, хешеви власника, тајне ограђивања и интерни подаци рутирања су искључени.

Претраге са погрешним кључем, погрешним власником, застарелом generation вредношћу, недостајуће, истекле, ослобођене и поништене све враћају исту грешку 409 LEASE_FENCE_STALE без метаподатака везе. Клијент који је примио одговор о чекању на капацитет нема активно везивање за преглед. Када рутирање пренесе активни закуп на другу везу, исти generation остаје важећи и status атомски враћа ново везивање, никада старо. Постојећи клијенти остају непромењени јер acquire, renew, release и одговори чекања задржавају своје претходне облике.

Овај серверски уговор не мења стандардни OpenAI Codex /status. Стандардни Codex тренутно пријављује свог провајдера модела и уграђено стање аутентикације/налога, али не приказује произвољне метаподатке налога прилагођеног провајдера; каснија клијентска интеграција мора позвати ову акцију и одлучити како да прикаже connection.displayName.

Сваки управљани захтев за инференцију тада доставља оба контролна заглавља:

X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1

Тачан власник, generation, активна веза и аутентикован API кључ се ограђују непосредно пре сваког подржаног покушаја узводно (upstream). Понављање власника и generation вредности са другим кључем не успева и када тај кључ дозвољава исту везу. Сирови власници се не чувају трајно, не логују, не задржавају у снимку захтева ни прослеђују узводно.

Привремена контенција враћа HTTP 429 са Retry-After и:

{
  "state": "WAITING_FOR_CAPACITY",
  "error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
  "reason": "NO_FREE_ELIGIBLE_CONNECTION",
  "retryAfter": 30
}

Овај одговор значи само да обичан подобан скуп није био празан и да је сваки слободан кандидат био заузет туђим активним закупом. Неподржани модели/провајдери, неусклађеност политике, cooldown, квота, здравствено стање и остале обичне неуспешне провере подобности задржавају своје постојеће OmniRoute одговоре.

`x-omniroute-compression`

Прекорачење плана компресије по захтеву. Има највиши приоритет — надјачава прекорачење routing-комбинације, активни профил, аутоматски покретач и подразумевану вредност панела. Вредности:

Вредност	Ефекат
`off`	Без компресије за овај захтев.
`default`	Подразумевани профил изведен из панела (игнорише активни профил).
`engine:<id>`	Појединачни мотор када је омогућен, нпр. `engine:rtk`.
`<combo>`	Именована комбинација, поклапа се по имену (без разлике велика/мала слова) прво, затим по id-у.

Напомене:

Непознате вредности се игноришу (захтев се никада не одбија); резолуција прелази на нормалан приоритет оператора.
Ако више комбинација дели исто име, проследите id комбинације за детерминистичко поклапање.
Комбинација чије је име off или default не може бити изабрана по имену (те кључне речи се тумаче прво); референцирајте такву комбинацију по њеном id-у.
Главни прекидач компресије је чврста препрека: када је компресија глобално онемогућена, ово заглавље је не може омогућити.

Примењени план се враћа у заглављу одговора:

X-OmniRoute-Compression: <mode>; source=<source>

где је <source> једно од request-header, routing-override, active-profile, auto-trigger, default, или off.

Embeddings

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

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

Dostupni provajderi: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, Jina AI.

ID-jevi u katalogu su u formatu provider/model (primer: jina-ai/jina-embeddings-v5-omni-small). Goli Jina ID-jevi modela koji se pojavljuju u registru (na primer jina-embeddings-v5-text-small, jina-reranker-v3.5) se takođe razrešavaju. Jina embed/rerank/classify/segment prvo koriste jina-ai kredencijale iz dashboard-a; JINA_AI_API_KEY je rezervni izbor samo kada ne postoji ključ u dashboard-u. Kartica jina-reader je namenjena samo za Reader / r.jina.ai (POST /v1/web/fetch) i nikada ne opslužuje embeddings ili rerank.

Modeli iz registra koji podržavaju multimodalnost takođe prihvataju do 32 provajder-neutralne strukturirane stavke. Tipovi media stavki su text, image, audio, video i document. Njihov media source je ili {"type":"url","url":"https://..."} ili {"type":"base64","data":"...","media_type":"..."}.

Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano, i alias familije jina-ai/jina-embeddings-v5-omni → omni-small) takođe prihvata Jina-ine izvorne EmbeddingsV5Request dokumente i prosleđuje ih neizmenjene na https://api.jina.ai/v1/embeddings:

{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "task": "retrieval.query",
  "normalized": true,
  "input": [
    { "text": "a red bicycle" },
    { "image": "https://example.com/bike.png" },
    {
      "content": [{ "text": "caption" }, { "image": "data:image/png;base64,..." }]
    }
  ]
}

Izvorne { image | audio | video | pdf } vrednosti mogu biti javni HTTPS URL, data: URI, ili sirovi base64. OmniRoute ne pretvara te objekte u stringove i ne preuzima izvorne image URL-ove — Jina sama preuzima javne medije. Dodatna Jina polja (task, normalized, truncate, embedding_type) se prosleđuju. Jina SKU-ovi koji rade samo sa tekstom i dalje odbijaju dokumente koji nisu tekstualni.

Bezbednosna i transportna ograničenja:

URL-ovi udaljenih medija moraju biti javni HTTPS. Kanonske {type,source:url} stavke se preuzimaju na strani servera (revalidacija redirekcija, timeout, ograničenja veličine, javni DNS, connection pinning) i ugrađuju pre pozivanja provajdera. Jina-izvorne {image:"https://..."} stavke se prosleđuju kao takve nakon istog javnog HTTPS provera; Jina preuzima URL.
Inline base64 medija je ograničen na 8 MiB dekodovano po stavci i 16 MiB dekodovano ukupno po zahtevu.

Prevod na strani provajdera (kanonske stavke se nikada ne prosleđuju neizmenjene):

Jina multimodalni modeli: svaka stavka na najvišem nivou postaje jedan objekat obeležen modalitetom (text / image / audio / video / pdf) koristeći data URI-jeve za inline medije; jedan vektor po stavci na najvišem nivou.
Gemini Embedding 2 familija: jedan niz na najvišem nivou postaje jedan izvorni models/{model}:embedContent zahtev sa content.parts (text ili inline_data).
Nepoznati/dinamički modeli bez eksplicitnih metapodataka o modalitetu odbijaju strukturirani unos sa HTTP 400.

{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "input": [
    { "type": "text", "text": "A red bicycle" },
    {
      "type": "image",
      "source": { "type": "url", "url": "https://example.com/bicycle.png" }
    }
  ],
  "dimensions": 512,
  "encoding_format": "float"
}

Nepodržane kombinacije modela/modaliteta vraćaju HTTP 400 umesto da prilagođavaju stavku. Polja proširenja koja se ne odnose na input, u zahtevima sa zastarelim string/token formatom, i dalje se prosleđuju neizmenjena.

# Prikaz svih embedding modela
GET /v1/embeddings

Генерисање слика

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"
}

Доступни провајдери: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, SD WebUI (локално), ComfyUI (локално).

# Приказ свих модела за слике
GET /v1/images/generations

OCR за документе

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

{
  "model": "mistral/mistral-ocr-latest",
  "document": {
    "type": "document_url",
    "document_url": "https://example.com/invoice.pdf"
  }
}

model бира OCR провајдера преко префикса provider/model; чист идентификатор модела (нпр. mistral-ocr-latest) разрешава се до свог регистрованог провајдера, а ако је model изостављен, подразумевано се користи Mistral (mistral-ocr-latest). Регистровани провајдери (open-sse/config/ocrRegistry.ts):

ID провајдера	ID модела	Вредност `model`	Напомене
`mistral`	`mistral-ocr-latest`	`mistral/mistral-ocr-latest` (или чисто `mistral-ocr-latest`)	Синхроно — одговор се враћа директно из једног позива upstream-у.
`azure-document-intelligence`	`prebuilt-read`	`azure-document-intelligence/prebuilt-read`	Асинхрони upstream (`analyze` + polling) — погледајте испод.
`vertex-deepseek-ocr`	`deepseek-ocr-maas`	`vertex-deepseek-ocr/deepseek-ocr-maas`	Синхроно, преко Vertex AI-евог партнерског endpoint-а `openapi/chat/completions` — погледајте испод за аутентикацију/URL.

Сва три провајдера одговарају у истом облику као Mistral:

{
  "pages": [{ "index": 0, "markdown": "# Извучени текст..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}

Ток анкетирања (poll) за Azure Document Intelligence

Azure Document Intelligence-ов analyze API је асинхрон: почетни захтев враћа заглавље Operation-Location уместо тела одговора, а резултат се мора добавити анкетирањем (polling). Handler (open-sse/handlers/ocr.ts) анкетира тај URL сваке секунде до 30 покушаја, брзо прекида (не наставља анкетирање) уколико одговор анкетирања није ok или је статус "failed", и враћа 504 уколико операција још траје након што се потроши буџет покушаја. Коначни Azure одговор се нормализује у исти облик pages/markdown који користи Mistral пре него што се врати позиваоцу, тако да клијентски код не мора посебно обрађивати овог провајдера.

Vertex AI DeepSeek OCR аутентикација и разрешавање endpoint-а

vertex-deepseek-ocr користи исту Vertex AI аутентикацију која OmniRoute већ подржава за chat/image саобраћај (open-sse/executors/vertex.ts): API кључ конекције је или Service Account JSON акредитив (који се размењује за краткотрајан OAuth приступни токен путем JWT-bearer тока), или већ издат OAuth приступни токен који се користи такав какав је. Upstream endpoint URL је Vertex-ов генерички партнерски endpoint openapi/chat/completions, изграђен на основу пројекта и региона конекције — експлицитни providerSpecificData.project/providerSpecificData.region увек има приоритет; у супротном, пројекат се изводи из project_id вредности Service Account JSON-а, а регион подразумевано постаје us-central1. Оба разрешавања се дешавају у open-sse/handlers/ocr.ts (resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl), а користи их src/app/api/v1/ocr/route.ts пре прослеђивања ка handleOcr.

Листа модела

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

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

Префикси ID-а модела (`?prefix=`)

Већина модела се оглашава под префиксом провајдера. Који префикс добијате контролише фича-застава MODELS_CATALOG_PREFIX_MODE, а може се преклопити по захтеву помоћу query параметра — корисно за клијента који жели чисту листу без промене подешавања на нивоу сервера за све остале:

GET /v1/models?prefix=alias        # one id per model — the short alias prefix
GET /v1/models?prefix=dual         # both forms (server default)
GET /v1/models?prefix=canonical    # only the full provider-id prefix

Режим	Емитује	Напомене
`dual`	`cc/claude-sonnet-4-6` и `claude/claude-sonnet-4-6`	Подразумевано. Оба ID-а рутирају на исти модел; задржано да би конфигурације клијента које су чврсто кодирале било који облик наставиле да раде. Приближно дуплира каталог.
`alias`	`cc/claude-sonnet-4-6`	Један запис по моделу. Провајдери без посебног алиаса ипак емитују свој запис, тако да се ништа не губи.
`canonical`	`claude/claude-sonnet-4-6`	Један запис по моделу под потпуним префиксом provider-id. Провајдери без посебног алиаса (нпр. `antigravity/…`, `agy/…`) овде такође емитују свој јединствени ID, тако да се ништа не губи.

dual-режим огледала се такође може препознати без query параметра: носи поље parent које показује на примарни ID.

Клијенти који приказују бирач модела треба да захтевају ?prefix=alias — то је оно што ради OmniCopilot VS Code екстензија.

Варијанте модела без размишљања (no-thinking)

За Claude модele који су способни за размишљање, /v1/models такође оглашава no-thinking варијанту чији ID има префикс claude-3-omniroute-no-thinking/:

claude-3-omniroute-no-thinking/<provider>/<model>

Одабир овог ID-а (нпр. у конфигурацији Claude Code-а која увек прикачи thinking блок) резолвира се назад на стварни <provider>/<model> са потиснутим резоновањем — thinking:{type:"disabled"} на путу /v1/messages, или испуштена поља reasoning/reasoning_effort на путу /v1/chat/completions. Варијанта се наводи само за моделе из Claude породице који подржавају размишљање и прихватају disabled (тако да су, на пример, само-адаптивни модели који одбијају disabled искључени). Оператори могу да форсирају варијанту, укључено или искључено, по моделу преко ModelSpec.noThinkingAlias.

Manifest utičnih modula provajdera (Provider Plugin Manifest)

GET /api/v1/provider-plugin-manifest

Vraća JSON-bezbedan manifest utičnih modula provajdera koji koriste Bifrost, CLIProxyAPI i budući sidecar rutere. Odgovor se generiše iz TypeScript registra provajdera i namerno isključuje OAuth klijentske tajne, resolveovanje runtime okruženja, izvršne (executor) funkcije, request zaglavlja i podatke o nalozima.

Koristite ovaj endpoint kada sidecar radi izvan procesa (out-of-process) i ne može direktno da uveze open-sse/config/providerPluginManifestRegistry.ts.

Kompatibilni endpointi

Metoda	Putanja	Format
POST	`/v1/chat/completions`	OpenAI
POST	`/v1/messages`	Anthropic
POST	`/v1/responses`	OpenAI Responses
POST	`/v1/embeddings`	OpenAI
POST	`/v1/images/generations`	OpenAI Images
POST	`/v1/images/edits`	OpenAI Images (izmena/inpaint)
POST	`/v1/videos/generations`	Generisanje video sadržaja u OpenAI stilu
POST	`/v1/music/generations`	Generisanje muzike u OpenAI stilu
POST	`/v1/audio/transcriptions`	OpenAI Audio (STT)
POST	`/v1/audio/speech`	OpenAI TTS (vraća audio telo)
POST	`/v1/rerank`	Cohere/Voyage-stil rerangiranja
POST	`/v1/classify`	Jina klasifikacija (`api.jina.ai`)
POST	`/v1/segment`	Jina segmenter (`segment.jina.ai`)
POST	`/v1/moderations`	OpenAI Moderations
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
GET	`/api/v1/vscode/{token}/`	OpenAI alias za katalog
GET	`/api/v1/vscode/{token}/models`	OpenAI alias za modele
POST	`/api/v1/vscode/{token}/chat/completions`	OpenAI tokenizovani alias
POST	`/api/v1/vscode/{token}/responses`	OpenAI Responses tokenizovani alias
POST	`/api/v1/vscode/{token}/api/chat`	Ollama tokenizovani alias
GET	`/api/v1/vscode/{token}/api/tags`	Ollama tags tokenizovani alias

Svi POST ruteri prate isti oblik: Bearer your-api-key + Zod-validirano JSON telo (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema, itd., vidi src/shared/validation/schemas.ts). Prilikom neuspešne validacije šeme vraća se 4xx.

Za klijente koji ne mogu da dodaju Authorization: Bearer ..., OmniRoute takođe prihvata API ključeve u URL-u, bilo putem query-string kompatibilnosti (?token=..., ?apiKey=..., ?api_key=..., ?key=...) ili putem namenskih /api/v1/vscode/{token}/... endpointa dokumentovanih ispod.

# Rerank
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Jina klasifikacija (Foundation API akreditivi)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Jina segmenter
POST /v1/segment     { "content": "...", "return_chunks": true }

# Jina pretraga (s.jina.ai; aliasi provajdera: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# Moderacije
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — vraća audio/mpeg (ili traženi format) telo
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Izmena slike (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# Generisanje video/muzičkog sadržaja (id modela sa prefiksom provajdera)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

Namenski ruteri za provajdere

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

Prefiks provajdera se automatski dodaje ako nedostaje. Neusklađeni modeli vraćaju 400.

Files API

OpenAI-компатибилни endpoint за фајлове за batch input/output и upload фајлова по сврси (purpose).

Метод	Путања	Описание
POST	`/v1/files`	Отпремање фајла (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — максимум 512 MiB
GET	`/v1/files`	Листа фајлова за аутентификован API кључ
GET	`/v1/files/[id]`	Преузимање метаподатака фајла
DELETE	`/v1/files/[id]`	Брисање фајла
GET	`/v1/files/[id]/content`	Стримовање сирових података фајла

Аутентификација: Bearer API кључ — фајлови су ограничени по API кључу преко getApiKeyRequestScope.

Batches API

OpenAI-компатибилна batch обрада.

Метод	Путања	Описание
POST	`/v1/batches`	Креирање batch-а — тело захтева се валидира преко `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`)
GET	`/v1/batches`	Листа batch-ова
GET	`/v1/batches/[id]`	Преузимање статуса batch-а + `request_counts`
DELETE	`/v1/batches/[id]`	Брисање завршеног/неуспелог batch-а
POST	`/v1/batches/[id]/cancel`	Отказивање batch-а у току

Аутентификација: Bearer API кључ. Batch-ови су ограничени по API кључу.

Search API

Апстракција провајдера за веб претрагу (Tavily, Brave, Exa, Serper, итд.).

Метод	Путања	Описание
GET	`/v1/search`	Листа конфигурисаних провајдера претраге + могућности
POST	`/v1/search`	Извршавање упита за претрагу — тело захтева се валидира преко `v1SearchSchema`, подржава кеширање/спајање захтева (coalescing)
GET	`/v1/search/analytics`	Статистика по провајдеру (број погодака/латенција/кеш)

Аутентификација: Bearer API кључ (extractApiKey + isValidApiKey). Политика претраге се примењује преко enforceApiKeyPolicy.

Web Fetch API

Izvlačenje sadržaja sa URL-a preko konfigurisanog web-fetch provajdera (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

Metod	Putanja	Opis
POST	`/v1/web/fetch`	Preuzimanje/scraping URL-a — telo validirano preko `v1WebFetchSchema`

Autentifikacija: Bearer API ključ (extractApiKey + isValidApiKey). Politika se sprovodi preko enforceApiKeyPolicy.

Fallback svestan kvota (#8297): kada nije naveden eksplicitan provider, skup (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) se obilazi u fiksnom prioritetnom redosledu (fill-first) — provajder koji je ograničen brzinom, ali je konfigurisan, se preskače umesto da se zahtev prekine, a otkazivi/kvota-povezani otpremni neuspeh (HTTP 429 uvek; 402/403 za besplatne planove Firecrawl/Tavily/TinyFish tipa kvote — ne za Jina Reader, i nikad za običan 400 loš zahtev) prelazi na sledećeg neisprobanog provajdera sa akreditivima u trenutku zahteva. Kada su svi provajderi u skupu iscrpljeni, endpoint vraća jedinstven 429 (sa Retry-After zaglavljem) umesto prethodnog generičkog 400. Kada je zahtevan eksplicitan provider, nema tihog fallback-a — eksplicitni provajder koji je ograničen brzinom ili ne radi prikazuje svoju sopstvenu grešku (429 ako je ograničen brzinom, inače status sa strane provajdera).

WebSocket Streaming

GET /v1/ws?handshake=1

Validira WebSocket upgrade handshake i vraća primere poruka žičnog protokola (request, cancel). Stvarni WS okviri se obrađuju putem ugrađenog WS servera izvan Next.js tabele ruta.

Autentifikacija: Bearer API ključ prilikom handshake-a.

Responses API preko WebSocket-a (samo codex)

# Isti host:port kao HTTP API (podrazumevano 20128); upgrade-ujte konekciju:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (ili: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# Prvi okvir MORA biti response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

Responses-API-preko-WebSocket-a proxy je povezan isključivo na codex (ChatGPT backend). On sluša na istom portu kao API/dashboard na putanjama /v1/responses, /responses, i /api/v1/responses. Na prvi response.create okvir on autentifikuje + priprema preko internog codex-responses-ws bridge-a, bira codex OAuth konekciju, i tunelira do wss://chatgpt.com/backend-api/codex/responses preko wreq-js transporta. Modeli koji nisu codex se odbijaju (codex_ws_provider_required). Za rutiranje sa deljenjem kvote koristite model: "qtSd/<group>/codex/<model>". Implementirano u app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts.

Autentifikacija: Bearer API ključ prilikom handshake-a. Ugrađeni HTTP server (server-ws.mjs) mora biti aktivna ulazna tačka (jeste, po podrazumevanoj vrednosti, kada app/server-ws.mjs postoji).

ID modela: koristite goli ChatGPT id (bez `codex/` prefiksa)

OpenAI Codex CLI validira naziv modela na strani klijenta kada je supports_websockets = true i odbija id-ove sa prefiksom provajdera kao codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Pošaljite goli id (npr. gpt-5.5). OmniRoute-ov bridge je samo za codex, tako da ponovo razrešava goli id kao codex model (resolveCodexWsModelInfo) prije tuneliranja ka nadređenom serveru — čak i ako bi goli gpt-5.5 inače usmerio ka drugom provajderu preko HTTP-a.

Konfigurisanje OpenAI Codex CLI-ja

Usmerite Codex CLI ka OmniRoute-u dodavanjem prilagođenog provajdera sa WebSocket podrškom u ~/.codex/config.toml (koristite odvojeni CODEX_HOME da izbegnete diranje postojeće konfiguracije):

model = "gpt-5.5"                 # goli id — NE "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # bez pratećeg slash-a; WS URL se izvodi (koristite https/wss u produkciji)
wire_api = "responses"                    # jedina podržana vrednost od februara 2026
supports_websockets = true                # omogućava Responses-over-WS transport
env_key = "OMNIROUTE_API_KEY"             # sadrži OmniRoute API ključ (Bearer)

export OMNIROUTE_API_KEY=sk-...           # OmniRoute API ključ (bilo koji ključ ako je REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"

CLI podiže base_url + /responses na WebSocket i OmniRoute to tunelira do izabrane codex OAuth konekcije. Validirano end-to-end na lokalnom serveru: ChatGPT vraća codex.rate_limits + response.created i strimuje kompletiranje.

Извештавање о квотама и проблемима

Метод	Путања	Опис
GET	`/v1/quotas/check`	Претходна валидација квоте за `provider` + `accountId` пре издавања регистрованог кључа
POST	`/v1/issues/report`	Пријава грешке у квоти/издавању кључа на GitHub (захтева `GITHUB_ISSUES_REPO` + токен)

Аутентикација: Bearer API кључ (isAuthenticated).

Самостално коришћење (`/api/usage/om-usage`)

Сваки API кључ може да прочита сопствену потрошњу и квоте — без потребе за управљачком ауторизацијом. Ово је крајња тачка коју клијент (CLI, панел OmniCopilot) користи да прикаже власнику кључа његову потрошњу.

# Текстуални облик (историјски уговор — обичан текст за терминал)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Структурирани облик — оно што конзумира UI
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

Кључ мора имати укључено allowUsageCommand (подразумевано искључено — менаџер API кључева на контролној табли то укључује по кључу). Без тога, крајња тачка одговара са 403.

?format=json враћа дискриминовани облик, тако да позивалац никада не чита поље са подацима из одбијеног одговора. У случају успеха:

{
  "allowed": true,
  // присутно само када је кључ активирао ограничења потрошње по кључу (дневно/недељно у USD):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // снимак квоте изабраног провајдера, или null ако још ништа није кеширано:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // снимак сваке везе, тако да UI може приказати више провајдера један поред другог:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

У случају одбијања (401 погрешан кључ / 403 није дозвољено), исти route враћа { "allowed": false, "error": { "message": "…" } } — присутно, али празно personal/provider (кључ је дозвољен, али још ништа није научено) представља другачије стање од одбијања, и само JSON облик разликује ова два случаја.

Аутентикација: сопствени Bearer API кључ позиваоца, валидиран помоћу isValidApiKey — ово није управљачка површина (/api/keys/…), која остаје иза requireManagementAuth.

Семантички кеш

# Добијање статистике кеша
GET /api/cache/stats

# Брисање свих кешева
DELETE /api/cache/stats

Пример одговора:

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

Утицај на кашњење

Погодак (HIT) семантичког кеша служи одговор из кеша без позива ка upstream-у, тако да пријављено X-OmniRoute-Response-Latency буде близу нуле (без обзира на стварно upstream кашњење). Клијенти осетљиви на кашњење (benchmarking, p50/p99 мониторинг) треба да провере X-OmniRoute-Cache-Latency заглавље одговора:

Вредност	Значење
`synthetic`	Одговор је послужен из кеша; кашњење није стварно upstream време
(одсутно)	Одговор из стварног upstream позива

Заобилажење кеша по кључу

API кључеви могу да искључе читање из семантичког кеша путем cacheDefaultMode:

Вредност	Понашање
`legacy`	Нормално понашање кеша (подразумевано)
`bypass`	Потпуно прескочи претрагу кеша; увек контактира upstream

Подешава се приликом креирања кључа (POST /api/keys) или ажурирања (PATCH /api/keys/[id]):

{ "cacheDefaultMode": "bypass" }

Заобилажење по захтеву

Сваки захтев може заобићи кеш без обзира на подешавања кључа:

X-OmniRoute-No-Cache: true

Dashboard i upravljanje

Rute za upravljanje (/api/* osim javne prijave/autentikacije) nisu autorizovane pomoću običnih API ključeva za inferenciju. Porodice akreditiva, opsezi i curl primeri: Autentikacija za upravljanje.

Autentikacija

Endpoint	Metod	Opis
`/api/auth/login`	POST	Prijava
`/api/auth/logout`	POST	Odjava
`/api/settings/require-login`	GET/PUT	Uključi/isključi obaveznu prijavu

Upravljanje provajderima

Endpoint	Metod	Opis
`/api/providers`	GET/POST	Prikaz liste / kreiranje provajdera
`/api/providers/[id]`	GET/PUT/DELETE	Upravljanje provajderom
`/api/providers/[id]/test`	POST	Testiranje konekcije provajdera
`/api/providers/[id]/models`	GET	Prikaz modela provajdera
`/api/providers/validate`	POST	Validacija konfiguracije provajdera
`/api/providers/bulk`	POST	Masovno dodavanje API ključeva za JEDNOG provajdera
`/api/providers/import`	POST	Uvoz heterogene LISTE provajdera iz parsiranog CSV/JSON fajla (#6836); rezultati delimičnog neuspeha po redu
`/api/provider-nodes*`	Različiti	Upravljanje čvorovima provajdera
`/api/provider-models`	GET/POST/PATCH/DELETE	Prilagođeni modeli (dodavanje, ažuriranje, sakrivanje/prikazivanje, brisanje)

OAuth toka

Endpoint	Metod	Opis
`/api/oauth/[provider]/[action]`	Različiti	OAuth specifičan za provajdera

Rutiranje i konfiguracija

Endpoint	Metod	Opis
`/api/models/alias`	GET/POST	Aliasi modela
`/api/models/catalog`	GET	Svi modeli po provajderu i tipu
`/api/combos*`	Različiti	Upravljanje kombinacijama
`/api/keys*`	Različiti	Upravljanje API ključevima
`/api/pricing`	GET	Cene modela

Upotreba i analitika

Endpoint	Metod	Opis
`/api/usage/history`	GET	Istorija upotrebe
`/api/usage/logs`	GET	Logovi upotrebe
`/api/usage/request-logs`	GET	Logovi na nivou zahteva
`/api/usage/[connectionId]`	GET	Upotreba po konekciji
`/api/usage/token-limits`	GET/POST/DELETE	Budžeti ograničenja tokena po API ključu
`/api/usage/model-latency-stats`	GET	Kumulativna agregacija kašnjenja po provajderu/modelu (prosek/p50/p95/p99, stopa uspeha); filteri: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873)
`/api/usage/cache-health`	GET	Sažetak zdravlja keša za prompt preko `call_logs` — odnos pisanja/čitanja, distribucija veličine pisanja p50/p90/p99, koncentracija intenzivnih pisanja, podela po modelu, i ocena `healthy`/`degraded`/`thrash`/`no-data`; query parametri `range` (`1h`\|`24h`\|`7d`\|`30d`, podrazumevano `24h`) i opcioni `model` (#8827)

Podešavanja

Endpoint	Metod	Opis
`/api/settings`	GET/PUT/PATCH	Opšta podešavanja
`/api/settings/proxy`	GET/PUT	Konfiguracija mrežnog proksija
`/api/settings/proxy/test`	POST	Testiranje konekcije proksija
`/api/settings/ip-filter`	GET/PUT	Lista dozvoljenih/blokiranih IP adresa
`/api/settings/thinking-budget`	GET/PUT	Režim prepisivanja zahteva za razmišljanje/rezonovanje (passthrough / auto-strip / custom / adaptive). Nezavisno od kompresije. Pogledajte THINKING_BUDGET.md.
`/api/settings/system-prompt`	GET/PUT	Globalni sistemski prompt
`/api/settings/compression`	GET/PUT	Globalna konfiguracija kompresije
`/api/settings/purge-request-history`	POST	Brisanje redova logova zahteva i lokalnih artefakata call-log

Kontekst i kompresija

Endpoint	Metod	Opis
`/api/compression/preview`	POST	Pregled off/lite/standard/aggressive/ultra/RTK/stacked kompresije
`/api/compression/language-packs`	GET	Prikaz dostupnih Caveman jezičkih paketa
`/api/compression/rules`	GET	Prikaz metapodataka Caveman pravila
`/api/context/caveman/config`	GET/PUT	Alias za Caveman specifična podešavanja
`/api/context/rtk/config`	GET/PUT	RTK specifična podešavanja, uključujući prilagođene filtere i čuvanje sirovog izlaza
`/api/context/rtk/filters`	GET	Katalog RTK filtera i dijagnostika prilagođenih filtera
`/api/context/rtk/test`	POST	Izvršavanje RTK pregleda/testa nad tekstualnim payload-om
`/api/context/rtk/raw-output/[id]`	GET	Čitanje sačuvanog redaktovanog sirovog izlaza po pointer id
`/api/context/combos`	GET/POST	Lista/kreiranje kombinacija kompresije
`/api/context/combos/[id]`	GET/PUT/DELETE	Detalji/ažuriranje/brisanje kombinacije kompresije
`/api/context/combos/[id]/assignments`	GET/PUT	Dodela kombinacija kompresije rutirajućim kombinacijama
`/api/context/analytics`	GET	Alias za analitiku kompresije

Nadzor

Endpoint	Metod	Opis
`/api/sessions`	GET	Praćenje aktivnih sesija
`/api/rate-limits`	GET	Ograničenja stope po nalogu
`/api/monitoring/health`	GET	Provera zdravlja + sažetak provajdera (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`)
`/api/cache/stats`	GET/DELETE	Statistike keša / brisanje
`/api/modality-bridge/stats`	GET	Memorijski `attempts`, uspesi/`bridged`, neuspesi, hits keša, `totalLatencyMs`, `latencySamples`, `averageLatencyMs` izračunat po uzorku, i vreme poslednje upotrebe (resetuje se pri restartu; management autentikacija)
`/api/modality-bridge/video/runtime`	GET	Striktna provera pouzdanog loopback-a pre management autentikacije/provere; sanitizovana dostupnost i verzije FFmpeg/ffprobe (no-store)
`/api/modality-bridge/video/extract`	POST	Interni autentikovani pouzdani loopback bajt-broker; 50 MiB ulaz, ograničen red čekanja/32 MiB izlaz, `503` kapacitet, `499` prekid konekcije, `504` prekoračenje vremena; nije javni API za upload

Rezervna kopija i izvoz/uvoz

Endpoint	Metod	Opis
`/api/db-backups`	GET	Prikaz dostupnih rezervnih kopija
`/api/db-backups`	PUT	Kreiranje ručne rezervne kopije
`/api/db-backups`	POST	Vraćanje iz specifične rezervne kopije
`/api/db-backups/export`	GET	Preuzimanje baze podataka kao .sqlite fajl
`/api/db-backups/import`	POST	Otpremanje .sqlite fajla za zamenu baze podataka
`/api/db-backups/exportAll`	GET	Preuzimanje kompletne rezervne kopije kao .tar.gz arhive

Sinhronizacija u oblaku

Endpoint	Metod	Opis
`/api/sync/cloud`	Različiti	Operacije sinhronizacije u oblaku
`/api/sync/initialize`	POST	Inicijalizacija sinhronizacije
`/api/cloud/*`	Različiti	Upravljanje oblakom

Tuneli

Endpoint	Metod	Opis
`/api/tunnels/cloudflared`	GET	Čitanje statusa instalacije/rada Cloudflare Quick Tunnel za dashboard
`/api/tunnels/cloudflared`	POST	Uključivanje ili isključivanje Cloudflare Quick Tunnel (`action=enable/disable`)
`/api/tunnels/ngrok`	GET	Čitanje statusa rada ngrok Tunnel za dashboard
`/api/tunnels/ngrok`	POST	Uključivanje ili isključivanje ngrok Tunnel (`action=enable/disable`)

CLI alati

Endpoint	Metod	Opis
`/api/cli-tools/claude-settings`	GET	Status Claude CLI-a
`/api/cli-tools/codex-settings`	GET	Status Codex CLI-a
`/api/cli-tools/droid-settings`	GET	Status Droid CLI-a
`/api/cli-tools/openclaw-settings`	GET	Status OpenClaw CLI-a
`/api/cli-tools/runtime/[toolId]`	GET	Generički CLI runtime

CLI odgovori uključuju: installed, runnable, command, commandPath, runtimeMode, reason.

ACP agenti

Endpoint	Metod	Opis
`/api/acp/agents`	GET	Prikaz svih detektovanih agenata (ugrađenih + prilagođenih) sa statusom
`/api/acp/agents`	POST	Dodavanje prilagođenog agenta ili obnavljanje keša detekcije
`/api/acp/agents`	DELETE	Uklanjanje prilagođenog agenta preko `id` query parametra

GET odgovor uključuje agents[] (id, name, binary, version, installed, protocol, isCustom) i summary (total, installed, notFound, builtIn, custom).

Otpornost i ograničenja stope

Endpoint	Metod	Opis
`/api/resilience`	GET/PATCH	Prikaz/ažuriranje reda čekanja zahteva, hlađenja konekcije, provider breaker-a i podešavanja čekanja
`/api/resilience/reset`	POST	Resetovanje circuit breaker-a provajdera
`/api/resilience/model-cooldowns`	GET	Prikaz aktivnih zaključavanja po (provajder, konekcija, model), sortirano po preostalom vremenu
`/api/resilience/model-cooldowns`	DELETE	Brisanje zaključavanja modela — telo `{provider, model}` ili `{all: true}` za brisanje svega
`/api/rate-limits`	GET	Status ograničenja stope po nalogu
`/api/rate-limit`	GET	Globalna konfiguracija ograničenja stope

Sve četiri /api/resilience/* rute zahtevaju management autentikaciju (requireManagementAuth). Pogledajte Otpornost (proširena) za potpuni pregled razlike između provider breaker-a, hlađenja konekcije i zaključavanja modela.

Evaluacije

Endpoint	Metod	Opis
`/api/evals`	GET/POST	Prikaz evaluacionih setova / pokretanje evaluacije

Politike

Endpoint	Metod	Opis
`/api/policies`	GET/POST/DELETE	Upravljanje politikama rutiranja

Usklađenost

Endpoint	Metod	Opis
`/api/compliance/audit-log`	GET	Log revizije usklađenosti (poslednjih N)

v1beta (kompatibilno sa Gemini)

Endpoint	Metod	Opis
`/v1beta/models`	GET	Prikaz modela u Gemini formatu
`/v1beta/models/{...path}`	POST	Gemini `generateContent` endpoint

Ovi endpointi oponašaju format Gemini API-ja za klijente koji zahtevaju nativnu kompatibilnost sa Gemini SDK-om.

Interni / sistemski API-jevi

Endpoint	Metod	Opis
`/api/init`	GET	Provera inicijalizacije aplikacije (koristi se pri prvom pokretanju)
`/api/tags`	GET	Ollama-kompatibilne oznake modela (za Ollama klijente)
`/api/restart`	POST	Pokretanje graciozanog restarta servera
`/api/shutdown`	POST	Pokretanje graciozanog isključivanja servera
`/api/system/env/repair`	POST	Popravka OAuth promenljivih okruženja provajdera

Napomena: Ovi endpointi se koriste interno u sistemu ili za kompatibilnost sa Ollama klijentima. Obično ih ne pozivaju krajnji korisnici.

Popravka OAuth okruženja (v3.6.1+)

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

{
  "provider": "claude-code"
}

Popravlja nedostajuće ili oštećene OAuth promenljive okruženja za određenog provajdera. Vraća:

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

Транскрипција аудио записа

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

Транскрибујте аудио фајлове коришћењем било ког конфигурисаног STT провајдера. Први сегмент путање бира native провајдера (openai/…, deepgram/…). Gateway-и који реекспортују модел другог вендора користе квалификовани id (openrouter/deepgram/nova-3).

Захтев:

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

Одговор:

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

Примери id-ова модела: openai/whisper-1 (захтева OpenAI кључ), openrouter/deepgram/nova-3 (захтева OpenRouter кључ), deepgram/nova-3 (захтева native Deepgram кључ). Обичан deepgram/nova-3 захтев не користи OpenRouter.

Подржани формати: mp3, wav, m4a, flac, ogg, webm.

Ollama компатибилност

За клијенте који користе Ollama-ов API формат:

# Chat endpoint (Ollama формат)
POST /v1/api/chat

# Листа модела (Ollama формат)
GET /api/tags

Захтеви се аутоматски преводе између Ollama и интерних формата.

Tokenized VS Code / Headerless алијаси

Користите ове алијасе када интеграција не може да убаци Authorization заглавље и потребно је да API кључ буде уграђен у base URL.

# OpenAI-style алијас за каталог
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# OpenAI-style chat алијаси
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Ollama-style алијаси
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

Пример:

curl https://your-host.example/api/v1/vscode/YOUR_API_KEY/models
curl -X POST https://your-host.example/api/v1/vscode/YOUR_API_KEY/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}'

Напомене:

Tokenized алијаси користе исте handler-е као /v1/* и /api/tags; облици одговора остају идентични.
Дајте приоритет Authorization: Bearer ... заглављу кад год клијент подржава custom заглавља.
Токени засновани на URL-у могу се појавити у reverse-proxy логовима, историји браузера и телеметрији изван OmniRoute. Третирајте их као опцију компатибилности, а не подразумевани режим аутентикације.

Телеметрија

# Преузми сажетак телеметрије кашњења (p50/p95/p99 по провајдеру)
GET /api/telemetry/summary

Одговор:

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

Буџет

# Преузми статус буџета за све API кључеве
GET /api/usage/budget

# Постави или ажурирај буџет
POST /api/usage/budget
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "dailyLimitUsd": 5.00,
  "weeklyLimitUsd": 30.00,
  "monthlyLimitUsd": 100.00,
  "warningThreshold": 0.8,
  "resetInterval": "monthly"
}

Напомене о схеми (setBudgetSchema): apiKeyId је обавезан; бар једно од dailyLimitUsd, weeklyLimitUsd или monthlyLimitUsd мора бити веће од нуле. Опциона поља: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). Стари облик {keyId, limit, period} враћа 400 Bad Request.

Ограничења токена

Буџети токена по API кључу (различити од USD буџета описаног изнад). Спроводе се директно на путу обраде захтева: када тренутна потрошња у оквиру прозора достигне лимит кључа, захтеви се одбијају уз 429 Too Many Requests. Ограничења могу бити везана за конкретан model, provider, или примењена globalно на цео кључ; када више ограничења одговара захтеву, побеђује најрестриктивније.

# Приказ ограничења токена за кључ (укључује живу потрошњу у прозору)
GET /api/usage/token-limits?apiKeyId=key-123

# Креирање или ажурирање ограничења токена
POST /api/usage/token-limits
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "scopeType": "model",
  "scopeValue": "openai/gpt-4o",
  "tokenLimit": 1000000,
  "resetInterval": "monthly",
  "enabled": true
}

# Брисање ограничења токена по id-у
DELETE /api/usage/token-limits?id=tl-abc

Напомене о шеми (setTokenLimitSchema): apiKeyId и scopeType (model | provider | global) су обавезни. scopeValue је обавезан осим ако је scopeType global (нпр. id модела за model опсег, id провајдера за provider опсег). tokenLimit мора бити позитиван цео број (коерција из стринга). Опционо: id (изостави за креирање, наведи за ажурирање), resetInterval (daily | weekly | monthly, подразумевано monthly), resetTime (HH:MM), enabled (подразумевано true). GET одговори обогаћују свако ограничење пољима tokensUsed, remaining, windowStart, periodStartAt и nextResetAt. Ово је крајња тачка управљачке класе (аутентикација се централно спроводи кроз authz канал).

Обрада захтева

Клијент шаље захтев на /v1/*
Route handler позива handleChat, handleEmbedding, handleAudioTranscription, или handleImageGeneration
Модел се разрешава (директан provider/model или alias/combo)
Креденцијали се бирају из локалне базе уз филтрирање доступности налога
За chat: handleChatCore провера семантички/потписни кеш и разрешава подешавања компресије за combo
Проактивна компресија се извршава пре превода за провајдера када је укључена (lite, Caveman, RTK, или наслагано)
Извршилац провајдера шаље upstream захтев
Одговор се преводи назад у формат клијента (chat) или враћа непромењен (embeddings/images/audio)
Записују се потрошња, аналитика компресије и логови захтева
Fallback се примењује на грешке према правилима combo-а

Потпуна референца архитектуре: ARCHITECTURE.md

Управљање Combo-има

Комбинације рутирања на вишем нивоу (већ сумиране под /api/combos*) могу такође бити мапиране 1:1 из шаблона id-а модела, дозвољавајући транспарентно преусмеравање id-а модела у OpenAI стилу на combo.

Метод	Путања	Опис
GET	`/api/model-combo-mappings`	Приказ свих мапирања модел→combo
POST	`/api/model-combo-mappings`	Креирање мапирања — тело: `{pattern, comboId, priority?, enabled?, description?}`
GET	`/api/model-combo-mappings/[id]`	Преузимање једног мапирања
PUT	`/api/model-combo-mappings/[id]`	Ажурирање поља постојећег мапирања
DELETE	`/api/model-combo-mappings/[id]`	Уклањање мапирања

Аутентикација: управљачка сесија/API кључ (requireManagementAuth).

Webhooks

Odlazne webhook pretplate za OmniRoute događaje (završetak zahteva, potrošnja kvote, rotacija ključeva, itd.).

Metod	Putanja	Opis
GET	`/api/webhooks`	Lista webhook-ova (tajni ključevi su maskirani u `<prefix>...`)
POST	`/api/webhooks`	Kreira webhook — telo: `{url, events?: ["*"], secret?, description?}`
GET	`/api/webhooks/[id]`	Preuzima webhook
PUT	`/api/webhooks/[id]`	Ažurira url/events/secret/description
DELETE	`/api/webhooks/[id]`	Uklanja webhook
POST	`/api/webhooks/[id]/test`	Šalje test payload na webhook URL i vraća status isporuke

Autentikacija: management sesija/API ključ (requireManagementAuth).

Registrovani ključevi (automatsko upravljanje)

Koristi ga podsistem za automatsko upravljanje ključevima za izdavanje i rotaciju API ključeva prema podržavajućem provajderu/nalogu, sa dnevnim/satnim kvotama.

Metod	Putanja	Opis
GET	`/api/v1/registered-keys`	Lista registrovanih ključeva (samo maskirani prefiks)
POST	`/api/v1/registered-keys`	Izdaje novi registrovani ključ — telo: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Vraća sirovi ključ jednom. Vraća `429` u slučaju odbijanja usled kvote.
GET	`/api/v1/registered-keys/[id]`	Preuzima metapodatke registrovanog ključa (bez sirovog materijala)
DELETE	`/api/v1/registered-keys/[id]`	Opoziva registrovani ključ
POST	`/api/v1/registered-keys/[id]/revoke`	Eksplicitna krajnja tačka za opoziv (isti efekat kao DELETE)

Autentikacija: Bearer API ključ (isAuthenticated). Pogledajte i /v1/quotas/check i /v1/issues/report.

Протокол агената

Задаци облак-агента (Claude Code, Codex Cloud, OpenHands, итд.) који се извршавају удаљено у име корисника OmniRoute.

Метод	Путања	Опис
GET	`/api/v1/agents/tasks`	Листа задатака — опционо `?provider=`, `?status=`, `?limit=` (1–500, подразумевано 50)
POST	`/api/v1/agents/tasks`	Креирање задатка — тело валидирано преко `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Враћа `201` са омотом задатка
DELETE	`/api/v1/agents/tasks?id=...`	Брисање задатка
GET	`/api/v1/agents/tasks/[id]`	Читање задатка — синхронизовано освежава статус са надлежног облак-агента када је постављен `external_id`
POST	`/api/v1/agents/tasks/[id]`	Дискриминисана акција: `{action: "approve"}`, `{action: "message", message}`, или `{action: "cancel"}`
DELETE	`/api/v1/agents/tasks/[id]`	Брисање конкретног задатка по id-у

Аутентификација: обавезна управљачка аутентификација на свакој методи (requireCloudAgentManagementAuth). Пре верзије v3.8.0 ови позиви су били неаутентификовани — погледајте commit 588a0333 за прекидну промену.

# Креирање облак-задатка за Claude Code
curl -X POST http://localhost:20128/api/v1/agents/tasks \
  -H "Authorization: Bearer your-management-key" \
  -H "Content-Type: application/json" \
  -d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'

Управљачки проксији

Одлазни HTTP(S)/SOCKS проксији који се могу доделити провајдерима, налозима или глобално.

Метод	Путања	Опис
GET	`/api/v1/management/proxies`	Листа проксија (уз `?id=` враћа један; уз `?id=&where_used=1` враћа граф доделa)
POST	`/api/v1/management/proxies`	Креирање проксија — тело валидирано преко `createProxyRegistrySchema`
PATCH	`/api/v1/management/proxies`	Ажурирање проксија — тело валидирано преко `updateProxyRegistrySchema` (захтева `id`)
DELETE	`/api/v1/management/proxies?id=...&force=1`	Брисање проксија (користите `force=1` за одвајање доделa)
GET	`/api/v1/management/proxies/assignments`	Листа доделa — може се филтрирати по `proxy_id`, `scope`, `scope_id`; проследите `resolve_connection_id=<id>` да разрешите активни проксy за везу
PUT	`/api/v1/management/proxies/assignments`	Додела — тело валидирано преко `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Чисти кеш дистрибутера
PUT	`/api/v1/management/proxies/bulk-assign`	Масовна додела — тело валидирано преко `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`)
GET	`/api/v1/management/proxies/health?hours=24`	Агрегирано здравствено стање проксија (број успеха/неуспеха, латенција) у оквиру временског прозора

Аутентификација: управљачка сесија/API кључ на свакој рути (requireManagementAuth).

Рутe POST /api/v1/management/proxies/[id]/assignments и POST /api/v1/management/proxies/[id]/health из описа задатка опслужују равне (flat) руте /assignments и /health приказане изнад — у кодној бази не постоје подруте по id-у.

Otpornost (proširena)

OmniRoute izlaže tri nezavisna mehanizma za privremene otkaze; upravljački krajnji punkti u nastavku omogućavaju operatorima da čitaju i preklapaju te mehanizme:

Opseg	Skladištenje stanja	Čitanje	Resetovanje / brisanje
Provider breaker	`domain_circuit_breakers` + u memoriji	`/api/monitoring/health`	`POST /api/resilience/reset`
Connection cooldown	`rateLimitedUntil` na provider konekcijama	`/api/rate-limits`, `/api/providers/[id]`	(ponovo se aktivira lenjo; brisanje putem provider PUT)
Model lockout	Registar dostupnosti modela u memoriji	`GET /api/resilience/model-cooldowns`	`DELETE /api/resilience/model-cooldowns`

PATCH /api/resilience prihvata preklapanja provider breaker-a pod providerBreaker.oauth i providerBreaker.apikey. Svaki profil podržava degradationThreshold, failureThreshold i resetTimeoutMs; ista polja su izložena u Dashboard → Settings → Resilience.

# Brisanje jednog model lockout-a
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","model":"gpt-4o-mini"}'

# Brisanje svih lockout-ova
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

Kompletna konceptualna referenca i podrazumevane vrednosti breaker-a: pogledajte CLAUDE.md → "Resilience Runtime State".

Skills (Vештине)

Skill framework za proširivanje OmniRoute-a prilagođenim izvršnim handler-ima, uz integracije sa marketplace-om.

Metod	Putanja	Opis
GET	`/api/skills`	Listanje instaliranih skill-ova — moguće filtriranje preko `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, sa paginacijom
GET	`/api/skills/[id]`	Preuzimanje jednog skill-a
PUT	`/api/skills/[id]`	Ažuriranje skill-a (naziv, opis, mode, schema, handler, tags)
DELETE	`/api/skills/[id]`	Deinstaliranje skill-a
POST	`/api/skills/install`	Instaliranje skill-a iz sirovog manifesta — body: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}`
GET	`/api/skills/executions`	Listanje nedavnih izvršavanja skill-ova (audit trag sa inputima/outputima/trajanjem)
GET	`/api/skills/marketplace?q=...`	Pretraga/popularna lista iz SkillsMP marketplace-a (zahteva podešavanje `skillsmpApiKey`)
POST	`/api/skills/marketplace/install`	Instaliranje skill-a po id-u sa SkillsMP-a
GET	`/api/skills/skillssh?q=&limit=`	Pretraga registra skills.sh
POST	`/api/skills/skillssh/install`	Instaliranje skill-a po id-u sa skills.sh

Autentifikacija: upravljačka sesija/API ključ. Rute za pretragu marketplace-a prihvataju bilo upravljačku autentifikaciju bilo Bearer API ključ (isAuthenticated).

Меморија

Трајна складишна јединица за конверзацијску/чињеничну меморију, ограничена по API кључу / сесији.

Метод	Путања	Опис
GET	`/api/memory`	Листа меморија — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, са `offset/limit` или `page/limit` пагинацијом
POST	`/api/memory`	Креирање меморије — тело валидирано помоћу Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}`
GET	`/api/memory/[id]`	Преузимање једне меморије
DELETE	`/api/memory/[id]`	Брисање меморије
GET	`/api/memory/health`	Здравствено стање подсистема меморије (повезаност са базом података, embeddings backend, статус векторског индекса)

Аутентификација: управљачка сесија/API кључ (requireManagementAuth). Енумерација type: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (види MemoryType у src/lib/memory/types.ts).

MCP сервер

OmniRoute долази са уграђеним Model Context Protocol сервером са 3 транспорта (stdio, SSE, streamable-http) и алаткама ограниченог опсега. Испод наведене крајње тачке контролне табле читају статус/audit податке и посредују (proxy) HTTP транспорте.

Метод	Путања	Опис
GET	`/api/mcp/status`	Heartbeat, транспорт, статус повезаности, последњи позив, најкориснији алати, стопа успешности за 24ч
GET	`/api/mcp/tools`	Листа MCP алата са `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints`
GET	`/api/mcp/sse`	Отвара SSE ток за SSE транспорт (враћа `503` ако је MCP онеспособљен или ако транспорт не одговара)
POST	`/api/mcp/sse`	Слање JSON-RPC оквира преко SSE транспорта
GET	`/api/mcp/stream`	Отвара SSE страну Streamable HTTP транспорта (поруке иницирање од сервера)
POST	`/api/mcp/stream`	Слање JSON-RPC оквира преко Streamable HTTP транспорта
DELETE	`/api/mcp/stream`	Завршава Streamable HTTP сесију
GET	`/api/mcp/audit`	Упит над audit логом — `?limit=`, `?offset=`, `?tool=`, `?success=true	false`,` ?apiKeyId=`
GET	`/api/mcp/audit/stats`	Агрегатне audit статистике (укупни бројеви, стопа успешности, просечно трајање, најкориснији алати)

Аутентификација: транспорти sse/stream поштују MCP-специфичну аутентификациону површину (Bearer API кључ са mcp опсегом); руте status/tools/audit* су читљиве са контролне табле (без потребе за додатном аутентификацијом осим приступа домаћину контролне табле).

Оба HTTP транспорта су контролисана поставкама settings.mcpEnabled и settings.mcpTransport — неусклађеност транспорта враћа 400, а онеспособљено стање MCP-а враћа 503.

A2A сервер

OmniRoute излаже A2A (Agent-to-Agent) JSON-RPC 2.0 крајњу тачку плус REST омотач за инспекцију/употребу на контролној табли.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # опционо осим ако је постављен OMNIROUTE_API_KEY
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "skill": "smart-routing",
    "messages": [{"role": "user", "content": "Route this coding task"}]
  }
}

Подржани методи (сви условљени поставком settings.a2aEnabled):

Метод	Опис
`message/send`	Синхроно извршавање skill-а; враћа `{task, artifacts, metadata}`
`message/stream`	Стриминг SSE извршавање истог скупа skill-ова
`tasks/get`	Преузимање задатка по `taskId`
`tasks/cancel`	Отказивање задатка по `taskId`

Уграђени skill-ови: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.

Agent Card

GET /.well-known/agent.json

Враћа јавну A2A agent картицу (назив, опис, могућности, каталог skill-ова, шему аутентикације) — кеширано јавно на 1h. Аутентикација није потребна.

REST помагала

Метод	Путања	Опис
GET	`/api/a2a/status`	A2A укључено + статистика задатака + кеширани резиме agent картице
GET	`/api/a2a/tasks`	Листа задатака — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=`
POST	`/api/a2a/tasks`	(Није имплементирано као REST помагало — креира се преко JSON-RPC `message/send`)
GET	`/api/a2a/tasks/[id]`	Преузимање једног задатка
POST	`/api/a2a/tasks/[id]/cancel`	Отказивање задатка

Аутентикација: REST помагала се извршавају без управљачке аутентикације (читљиво на контролној табли); JSON-RPC /a2a рута користи Bearer OMNIROUTE_API_KEY ако је конфигурисан.

Cloud, Evals и Assess

Метод	Путања	Опис
POST	`/api/cloud/auth`	Верификује Bearer кључ и враћа маскиране конекције провајдера + алиасе модела за cloud sync клијенте
POST	`/api/cloud/credentials/update`	Ажурира шифроване креденцијале за провајдера синхронизованог путем cloud-а
POST	`/api/cloud/model/resolve`	Резолвује логички id модела у конкретан провајдер/модел користећи локалну табелу рутирања
GET	`/api/cloud/models/alias`	Листа алиасе модела изложене cloud sync-у
GET	`/api/assess`	Читање последњих категоризација процене (по провајдеру/моделу)
POST	`/api/assess`	Покретање процене — тело: `{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	`/api/evals`	Листа уграђених eval suite-ова + најновијих извршавања
POST	`/api/evals`	Покретање eval извршавања
POST	`/api/evals/suites`	Креирање прилагођеног eval suite-а — тело се валидира помоћу `evalSuiteSaveSchema`
GET	`/api/evals/suites/[id]`	Преузимање прилагођеног eval suite-а

Аутентикација: /api/cloud/auth директно валидира Bearer кључ; остале руте /api/cloud/*, /api/evals/* и /api/assess захтевају управљачку сесију/API кључ. /api/assess POST користи validateBody са дискриминисаном унијом scope шеме.

Управљање ACP (Agent Client Protocol)

као подпроцеси. Ови крајњи чворови (endpoints) управљају детекцијом ACP агента и регистрацијом прилагођеног агента.

Метод	Путања	Опис
GET	`/api/acp/agents`	Листа свих познатих CLI агената (уграђени + прилагођени) са статусом инсталације, верзијом, извршном датотеком
POST	`/api/acp/agents`	Регистрација прилагођеног ACP агента или освежавање кеша — тело: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` или `{action: "refresh"}`
DELETE	`/api/acp/agents`	Уклањање прилагођеног ACP агента — упитни параметар: `?id=<agentId>`

Пример одговора (GET /api/acp/agents):

{
  "agents": [
    {
      "id": "claude",
      "name": "Claude Code CLI",
      "binary": "claude",
      "version": "1.0.45",
      "installed": true,
      "protocol": "stdio",
      "providerAlias": "claude",
      "isCustom": false
    },
    {
      "id": "my-custom-cli",
      "name": "My Custom CLI",
      "installed": false,
      "protocol": "stdio",
      "providerAlias": "my-provider",
      "isCustom": true
    }
  ],
  "cacheTtlMs": 60000,
  "cacheAge": 1234
}

Ауторизација: Захтева менаџмент сесију (dashboard auth_token колачић) или API кључ са менаџмент обимом (scope).

Погледајте ACP оквир за све детаље.

Аналитика и осматрање (Observability)

Крајњи чворови за аналитику у реалном времену за праћење рутирања, компресије и разноликости провајдера. Они покрећу странице /dashboard/analytics/*.

Аналитика аутоматског рутирања

Метод	Путања	Опис
GET	`/api/analytics/auto-routing`	Агрегатне статистике аутоматског рутирања: укупан број позива, дистрибуција стратегија, дистрибуција нивоа (tier), топ провајдери
GET	`/api/analytics/auto-routing?days=7`	Статистике у временском прозору (подразумевано 24ч)

Пример одговора:

{
  "window": "24h",
  "totalCalls": 1234,
  "strategyBreakdown": {
    "rules": 800,
    "cost": 200,
    "latency": 150,
    "sla-aware": 50,
    "lkgp": 34
  },
  "tierBreakdown": {
    "ultra": 100,
    "pro": 500,
    "standard": 400,
    "free": 234
  },
  "topProviders": [
    { "provider": "openai", "calls": 500, "avgLatencyMs": 850 },
    { "provider": "anthropic", "calls": 300, "avgLatencyMs": 1200 }
  ]
}

Аналитика компресије

Метод	Путања	Опис
GET	`/api/analytics/compression`	Агрегатне статистике компресије: сачувани токени, проценат уштеде, дистрибуција режима, коришћење енгина

Пример одговора:

{
  "window": "24h",
  "totalOriginalTokens": 5000000,
  "totalCompressedTokens": 3500000,
  "totalSavings": 1500000,
  "savingsPct": 30.0,
  "modeBreakdown": {
    "lite": 400,
    "standard": 600,
    "aggressive": 100,
    "ultra": 50,
    "rtk": 84
  },
  "engineBreakdown": {
    "caveman": 800,
    "rtk": 434
  }
}

Праћење разноликости провајдера

Метод	Путања	Опис
GET	`/api/analytics/diversity`	Праћење разноликости на основу Шенонове ентропије: спречава тачке појединачног квара мерењем распршености провајдера

Пример одговора:

{
  "window": "24h",
  "shannonEntropy": 2.45,
  "maxEntropy": 3.17,
  "diversityRatio": 0.77,
  "providerUsage": {
    "openai": 0.4,
    "anthropic": 0.25,
    "google": 0.2,
    "kiro": 0.15
  },
  "warnings": ["OpenAI accounts for 40% of traffic — consider diversifying"]
}

Ауторизација: Захтева менаџмент сесију или API кључ са менаџмент обимом (scope).

Admin операције

Ендпоинти доступни само администраторима за оперативно управљање.

Method	Path	Description
GET	`/api/admin/concurrency`	Читање тренутних ограничења конкурентности (глобалних + по провајдеру)
POST	`/api/admin/concurrency`	Ажурирање ограничења конкурентности — body: `{global?: number, perProvider?: Record<string, number>}`

Auth: Захтева management сесију са admin scope.

Управљање CLI алатима

Управљајте CLI алатима који се интегришу са OmniRoute (antigravity, chipotle, commandCode, devin-cli, итд.). Погледајте Provider Reference за потпуну листу.

Method	Path	Description
GET	`/api/cli-tools/all-statuses`	Статус свих CLI алата (инсталиран, верзија, последње виђен)
GET	`/api/cli-tools/status`	Детаљан статус за један CLI алат (`?tool=` query)
POST	`/api/cli-tools/apply`	Уписивање генерисане конфигурације алата (`dryRun` приказује преглед; `422` + `containerEphemeralTarget` када је контејнеризовано; `migration` бележи наслеђени Codex YAML)
GET	`/api/cli-tools/backups`	Листа резервних копија конфигурације CLI алата
POST	`/api/cli-tools/backups`	Креирање резервне копије свих конфигурација CLI алата
POST	`/api/cli-tools/backups`	Враћање: исти ендпоинт са `{tool, backupId}` у body-ју враћа ту резервну копију
GET	`/api/cli-tools/antigravity-mitm`	Статус antigravity MITM proxy-ja (CLI алат "antigravity-mitm")
POST	`/api/cli-tools/antigravity-mitm/alias`	Конфигурисање antigravity-mitm алиаса

Auth: Захтева management сесију.

Agent Skills

Управљајте вештинама AI агента (слично OpenAI-јевим custom GPT-овима, али за агенте).

Method	Path	Description
GET	`/api/agent-skills`	Листа свих agent skills (уграђених + прилагођених)
GET	`/api/agent-skills/[id]`	Преузимање конкретне agent skill-a
POST	`/api/agent-skills`	Креирање прилагођене agent skill-a — body: `{name, description, prompt, model?, temperature?}`
PUT	`/api/agent-skills/[id]`	Ажурирање прилагођене agent skill-a
DELETE	`/api/agent-skills/[id]`	Брисање прилагођене agent skill-a
GET	`/api/agent-skills/[id]/raw`	Преузимање sirovog prompt-a + metapodataka (без извршавања)
POST	`/api/agent-skills/generate`	AI генерисање нове skill-a на основу описа на природном језику

Auth: Захтева management сесију или management-scoped API кључ.

Управљање кешом

Управљање семантичким кешом и кешом закључивања.

Метод	Путања	Опис
GET	`/api/cache`	Преглед кеша: укупан број уноса, стопа погодака, величина на диску
GET	`/api/cache/entries`	Листа кешираних уноса (са паginацијом)
DELETE	`/api/cache/entries`	Брисање уноса кеша (филтрирано по параметрима упита)
GET	`/api/cache/stats`	Детаљна статистика кеша (по провајдеру, по моделу)
GET	`/api/cache/reasoning`	Статус кеша закључивања (за реплеј закључивања)
DELETE	`/api/cache/reasoning`	Брисање кеша закључивања — параметри упита: `?toolCallId=<id>` (један) или `?provider=<p>` (без параметара за све)

Ауторизација: Захтева management сесију.

Систем меморије

Управљање перзистентном меморијом (FTS5 + векторски embeddinzi).

Метод	Путања	Опис
GET	`/api/memory`	Листа уноса меморије (филтрирано по опсегу, типу, упиту претраге)
POST	`/api/memory`	Креирање новог уноса меморије — тело захтева: `{scope, type, content, metadata?}`
GET	`/api/memory/[id]`	Преузимање одређеног уноса меморије
PUT	`/api/memory/[id]`	Ажурирање уноса меморије
DELETE	`/api/memory/[id]`	Брисање уноса меморије
GET	`/api/memory?q=`	Претрага меморије (FTS5 + вектор) — статистика је укључена у истом одговору

Ауторизација: Захтева management сесију или management-scoped API кључ.

Webhook-ови

Управљање webhook претплатама за догађаје.

Метод	Путања	Опис
GET	`/api/webhooks`	Листа свих webhook претплата
POST	`/api/webhooks`	Креирање webhook претплате — тело захтева: `{url, events[], secret?, active?}`
GET	`/api/webhooks/[id]`	Преузимање одређене webhook претплате
PUT	`/api/webhooks/[id]`	Ажурирање webhook претплате
DELETE	`/api/webhooks/[id]`	Брисање webhook претплате
GET	`/api/webhooks/[id]/deliveries`	Листа историје достава за webhook (лог успеха/неуспеха)
POST	`/api/webhooks/[id]/test`	Слање тест догађаја на webhook

Ауторизација: Захтева management сесију.

Погледајте Webhooks Framework за све типове догађаја.

Skills Framework (Оквир вештина)

Управљајте вештинама (агентски оквир екстензија).

Метод	Путања	Опис
GET	`/api/skills`	Излистава све инсталиране вештине (уграђене + прилагођене)
POST	`/api/skills/install`	Инсталира вештину са локалне путање или URL адресе
DELETE	`/api/skills/[id]`	Деинсталира вештину
PUT	`/api/skills/[id]`	Омогућава или онемогућава вештину — тело захтева: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}`
POST	`/api/skills/executions`	Извршава вештину — тело захтева: `{skillName, apiKeyId, input?, sessionId?}`
GET	`/api/skills/executions`	Излистава историју извршавања за све вештине (филтрирање помоћу `?apiKeyId=`)

Аутентикација: Захтева менаџмент сесију или API кључ са менаџмент овлашћењима.

Погледајте Skills Framework за све детаље.

Plugins (Додаци)

Управљајте OmniRoute додацима (екстензије трећих страна).

Метод	Путања	Опис
GET	`/api/plugins`	Излистава инсталиране додатке
POST	`/api/plugins/marketplace/install`	Инсталира додатак из marketplace-а
DELETE	`/api/plugins/[name]`	Деинсталира додатак
POST	`/api/plugins/[name]/activate`	Активира додатак
POST	`/api/plugins/[name]/deactivate`	Деактивира додатак
GET	`/api/plugins/[name]/config`	Преузима конфигурацију додатка
PUT	`/api/plugins/[name]/config`	Ажурира конфигурацију додатка

Аутентикација: Захтева менаџмент сесију.

Погледајте Plugins Framework за све детаље.

Shadow Routing (Сенка рутирање)

Сенка / A-B поређење провајдера није самостални REST интерфејс — конфигурише се преко комбо рутирања (погледајте Auto-Combo). Метрике поређења по комбинацији доступне су преко GET /api/combos/metrics.

Guardrails (Заштитне мере)

Прегледајте заштитне мере рантајма (детекција личних података, детекција убризгавања упита, повезивање визуелних података). Заштитне мере се примењују на сваки захтев; одустајање по позиву врши се преко заглавља захтева x-omniroute-disabled-guardrails — не постоји трајни интерфејс за омогућавање/онемогућавање.

Метод	Путања	Опис
GET	`/api/guardrails`	Излистава регистроване заштитне мере и њихов статус (назив / омогућено / приоритет)
POST	`/api/guardrails/test`	Тестира сувим погоном (dry-run) пре-позивни ток обраде над узорком уноса — тело захтева: `{input, disabledGuardrails?}`

Аутентикација: Захтева менаџмент сесију.

Погледајте Security > Guardrails за све детаље.

Аутентикација

Погледајте Management Authentication за четири породице акредитива (dashboard сесија, локални CLI токен, oma_live_… Access Token, manage-scoped API кључ) и по чему се разликују од inference кључева.

Dashboard руте (/dashboard/*) користе auth_token колачић (cookie)
Пријава користи сачувани хеш лозинке; резервно решење је INITIAL_PASSWORD
requireLogin се може укључити/искључити преко /api/settings/require-login
/v1/* руте опционо захтевају Bearer API кључ када је REQUIRE_API_KEY=true
„management token" / „management-scoped API кључ" у овом документу значи једно од породица из тог водича — а не недефинисан додатни тип тајне

Промена која нарушава компатибилност (v3.8.0) — /api/v1/agents/tasks/* и крајње тачке за управљање cooldown-ом сада захтевају management аутентикацију (dashboard auth_token колачић или manage-scoped API кључ). Клијенти који су раније позивали ове руте без аутентикације добиће 401 Unauthorized. Погледајте commit 588a0333 (fix(auth): require management auth for agent and cooldown APIs).

134 KiB Raw Blame History Unescape Escape

API_REFERENCE (Српски)

title: "API Reference" version: 3.8.51 lastUpdated: 2026-08-31

API Reference

Садржај

Chat Completions

Прилагођена заглавља

Ексклузивни закупи управљане сесије

x-omniroute-compression

Embeddings

Генерисање слика

OCR за документе

Ток анкетирања (poll) за Azure Document Intelligence

Vertex AI DeepSeek OCR аутентикација и разрешавање endpoint-а

Листа модела

Префикси ID-а модела (?prefix=)

Варијанте модела без размишљања (no-thinking)

Manifest utičnih modula provajdera (Provider Plugin Manifest)

Kompatibilni endpointi

Namenski ruteri za provajdere

Files API

Batches API

Search API

Web Fetch API

WebSocket Streaming

Responses API preko WebSocket-a (samo codex)

ID modela: koristite goli ChatGPT id (bez codex/ prefiksa)

Konfigurisanje OpenAI Codex CLI-ja

Извештавање о квотама и проблемима

Самостално коришћење (/api/usage/om-usage)

Семантички кеш

Утицај на кашњење

Заобилажење кеша по кључу

Заобилажење по захтеву

Dashboard i upravljanje

Autentikacija

Upravljanje provajderima

OAuth toka

Rutiranje i konfiguracija

Upotreba i analitika

Podešavanja

Kontekst i kompresija

Nadzor

Rezervna kopija i izvoz/uvoz

Sinhronizacija u oblaku

Tuneli

CLI alati

ACP agenti

Otpornost i ograničenja stope

Evaluacije

Politike

Usklađenost

v1beta (kompatibilno sa Gemini)

Interni / sistemski API-jevi

Popravka OAuth okruženja (v3.6.1+)

Транскрипција аудио записа

Ollama компатибилност

Tokenized VS Code / Headerless алијаси

Телеметрија

Буџет

Ограничења токена

Обрада захтева

Управљање Combo-има

Webhooks

Registrovani ključevi (automatsko upravljanje)

Протокол агената

Управљачки проксији

Otpornost (proširena)

Skills (Vештине)

Меморија

MCP сервер

A2A сервер

JSON-RPC

Agent Card

REST помагала

Cloud, Evals и Assess

Управљање ACP (Agent Client Protocol)

Аналитика и осматрање (Observability)

Аналитика аутоматског рутирања

Аналитика компресије

134 KiB

Raw Blame History

`x-omniroute-compression`

Префикси ID-а модела (`?prefix=`)

ID modela: koristite goli ChatGPT id (bez `codex/` prefiksa)

Самостално коришћење (`/api/usage/om-usage`)