OmniRoute/docs/i18n/hr/docs/reference/API_REFERENCE.md

API_REFERENCE (Hrvatski)

🌐 Languages: 🇺🇸 English · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇮🇱 he · 🇮🇳 hi · 🇭🇺 hu · 🇮🇩 id · 🇮🇹 it · 🇯🇵 ja · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇳🇱 nl · 🇳🇴 no · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 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 referenca

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

Osnovna referenca za OmniRoute API. Obuhvaća javnu /v1 površinu i najkorištenije upravljačke krajnje točke (endpointe); iscrpni izvori podataka su strojno čitljiva datoteka docs/openapi.yaml i stablo ruta u src/app/api/.

---

Sadržaj

• Chat Completions
• Ekskluzivni upravljani session lease-ovi
• Embeddings
• Generiranje slika
• OCR dokumenata
• Popis modela
• Manifest provider dodatka
• Kompatibilni endpointi
• Files API
• Batches API
• Search API
• WebSocket streaming
• Kvote i prijava problema
• Semantička predmemorija (Semantic Cache)
• Nadzorna ploča i upravljanje
• Upravljanje kombinacijama (Combo Management)
• Webhookovi
• Registrirani ključevi (automatsko upravljanje)
• Agents Protocol
• Proxyji za upravljanje
• Otpornost (proširena)
• Vještine (Skills)
• Memorija
• MCP Server
• A2A Server
• Cloud, Evals i Assess
• Obrada zahtjeva
• Autentifikacija

---

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
}

Prilagođena zaglavlja

Zaglavlje	Smjer	Opis
X-OmniRoute-No-Cache	Zahtjev	Postavite na true za zaobilaženje predmemorije
x-omniroute-no-memory	Zahtjev	Postavite na true za preskakanje injektiranja memorije i vještina za ovaj zahtjev (funkcionira analogno no-cache; izbjegava dodatni trošak tokena/troška po pozivu)
X-OmniRoute-Progress	Zahtjev	Postavite na true za događaje napretka (progress events)
X-Session-Id	Zahtjev	Trajni (sticky) ključ sesije za vanjsku afinitetnost sesije
x_session_id	Zahtjev	Prihvaća se i varijanta s podvlakom (direktni HTTP)
X-OmniRoute-Session-Id	Zahtjev	Oznaka sesije/razgovora koju dostavlja pozivatelj (također se koristi za memoriju). Kada je prisutna, sprema se bez izmjena u call_logs.session_tag za pripisivanje troška po sesiji (#8249) — nikada se ne generira automatski kada je odsutna
Idempotency-Key	Zahtjev	Ključ za deduplikaciju (prozor od 5 s)
X-Request-Id	Zahtjev	Alternativni ključ za deduplikaciju
X-OmniRoute-Cache	Odgovor	HIT ili MISS (bez streaminga)
X-OmniRoute-Idempotent	Odgovor	true ako je deduplicirano
X-OmniRoute-Progress	Odgovor	enabled ako je praćenje napretka uključeno
X-OmniRoute-Session-Id	Odgovor	Efektivni ID sesije koji koristi OmniRoute
X-OmniRoute-Request-Id	Odgovor	ID korelacije zahtjeva (kada je poznat)
X-OmniRoute-Version	Odgovor	Verzija builda OmniRoute (uvijek prisutno)
X-OmniRoute-Cost-Saved	Odgovor	Iznos u USD koji je predmemorija uštedjela kod HIT-a (samo za pogotke u predmemoriji)
X-OmniRoute-Decision	Odgovor	Trag rutiranja: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> je naziv combo strategije, ili single za zahtjev koji nije combo) — uvijek prisutno na odgovorima o dovršetku (completion)

Napomena za Nginx: ako koristite zaglavlja s podvlakom (npr. x_session_id), omogućite underscores_in_headers on;.

Zaglavlja za telemetriju troškova: uspješni odgovori bez streaminga također sadrže skup X-OmniRoute-* zaglavlja za telemetriju troškova — X-OmniRoute-Response-Cost (u USD, fiksno 10 decimalnih mjesta; 0.0000000000 za besplatno/necjenovano), X-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out, X-OmniRoute-Model, X-OmniRoute-Provider, X-OmniRoute-Latency-Ms, X-OmniRoute-Cache-Hit, i X-OmniRoute-Fallback-Attempts (samo kada je > 0), te X-OmniRoute-Request-Id i X-OmniRoute-Version. Ova zaglavlja emitiraju chat completions, /v1/responses, /v1/messages, te medijski endpointi — /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/rerank, /v1/videos/generations, /v1/music/generations, i /v1/moderations (uvijek trošak 0). Trošak medija se računa po modalitetu (po slici, po sekundi, po znaku, po search-unitu) kada je cijena dostupna, u protivnom 0 (fail-open).

Semantika troška kod pogotka u predmemoriji (cache-hit): kod pogotka u semantičkoj predmemoriji (X-OmniRoute-Cache-Hit: true) ne poziva se uzvodni (upstream) servis, pa je X-OmniRoute-Response-Cost jednak 0.0000000000 (inkrementalni trošak posluživanja pogotka). Izvorni trošak, odnosno trošak koji bi inače bio nastao, prijavljuje se posebno u X-OmniRoute-Cost-Saved. Sustavi za naplatu trebaju zbrajati X-OmniRoute-Response-Cost (pogotci ne stvaraju trošak); analitika predmemorije može agregirati X-OmniRoute-Cost-Saved.

Ekskluzivni upravljani zakupi sesija (Exclusive Managed Session Leases)

Ekskluzivno upravljano zakupljivanje sesija je ugovor za rutiranje koji se aktivira po izboru (opt-in) i neovisan je o klijentu: jedan aktivni vlasnik posjeduje jednu prihvatljivu OmniRoute vezu. On ne zakupljuje model, ne zahtijeva OAuth, ne identificira određenog klijenta niti zahtijeva određenog pružatelja usluge.

API ključ koji se autentificira mora imati opseg lease:exclusive i explicitnu, nepraznu listu allowedConnections. Granica mutacije baze podataka provodi oba polja zajedno prilikom kreiranja ključa i djelomičnih ažuriranja.

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

Uspješni odgovori za akvizicijom (acquire), obnovom (renew) i otpuštanjem (release) izlažu vremenske oznake, state i točnu pozitivnu vrijednost generation, ali nikada odabranu vezu ili vjerodajnice. Obnova i otpuštanje isporučuju generaciju u JSON tijelu:

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

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

Aktivni vlasnik zakupa može explicitno zatražiti privatnosno sigurne metapodatke prikaza za svoje trenutno vezivanje:

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

Ova opt-in radnja statusa je ograđena neprozirnim vlasnikom, autentificiranim upravljanim API ključem i točnom aktivnom generacijom u jednoj transakciji baze podataka. displayName je samo obrezano konfigurirano ime veze; vrijednost je null kada ne postoji sigurno konfigurirano ime. OmniRoute nikada ne zamjenjuje e-poštu ili generirani identitet računa. Vrijednost provider je nesenzitivna oznaka za prikaz i nikada nije generirani identifikator kompatibilnog pružatelja usluge. Vjerodajnice, tokeni, kolačići, sirovi id-ovi veze ili API ključa, hashevi vlasnika, tajni podaci za ograđivanje i interni podaci rutiranja su isključeni.

Pretrage s pogrešnim ključem, pogrešnim vlasnikom, zastarjelom generacijom, nedostajuće, istekle, otpuštene i nevažeće sve vraćaju istu grešku 409 LEASE_FENCE_STALE bez metapodataka veze. Klijent koji je primio odgovor o čekanju kapaciteta nema aktivno vezivanje za pregled. Kada rutiranje prijeđe aktivni zakup, ista generacija ostaje važeća i status atomski vraća novo vezivanje, nikada staro. Postojeći klijenti ostaju nepromijenjeni jer akvizicija, obnova, otpuštanje i odgovori čekanja zadržavaju svoje prethodne oblike.

Ovaj ugovor na razini poslužitelja ne mijenja standardni OpenAI Codex /status. Standardni Codex trenutno prikazuje svog pružatelja modela i ugrađeno stanje autentifikacije/računa, ali ne prikazuje arbitrarne metapodatke računa prilagođenog pružatelja usluge; kasnija integracija klijenta mora pozvati ovu radnju i odlučiti kako prikazati connection.displayName.

Svaki upravljani zahtjev za inferencijom tada isporučuje oba kontrolna zaglavlja:

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

Točan vlasnik, generacija, aktivna veza i autentificirani API ključ ograđeni su neposredno prije svakog podržanog pokušaja s uzvodnim izvorom (upstream). Ponovno slanje (replaying) vlasnika i generacije s drugim ključem ne uspijeva čak i kada taj ključ dopušta istu vezu. Sirovi vlasnici se ne pohranjuju, ne bilježe, ne zadržavaju u snimci zahtjeva niti se prosljeđuju uzvodno.

Privremeno natjecanje za resurse vraća HTTP 429 s Retry-After i:

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

Ovaj odgovor znači samo da je obični prihvatljivi skup bio nepraznog te da je svaki slobodan kandidat bio u posjedu tuđeg aktivnog zakupa. Nepodržani modeli/pružatelji usluga, nepodudaranje politike, razdoblje odgode (cooldown), kvota, zdravstveno stanje i drugi obični neuspjesi prihvatljivosti zadržavaju svoje postojeće OmniRoute odgovore.

x-omniroute-compression

Nadjačavanje plana kompresije po zahtjevu. Ima najveći prioritet — nadjačava nadjačavanje kombinacije rutiranja, aktivni profil, automatsko okidanje i Zadano (Default) na ploči. Vrijednosti:

Vrijednost	Učinak
off	Nema kompresije za ovaj zahtjev.
default	Zadani profil izveden iz ploče (zanemaruje aktivni profil).
engine:<id>	Jedan mehanizam kada je omogućen, npr. engine:rtk.
<combo>	Imenovana kombinacija, podudarana prvo po imenu (bez razlike velikih/malih slova), zatim po id-u.

Napomene:

• Nepoznate vrijednosti se zanemaruju (zahtjev se nikada ne odbija); razrješenje se vraća na normalni prioritet operatora.
• Ako više kombinacija ima isto ime, proslijedite id kombinacije za determinističko podudaranje.
• Kombinacija čije je ime off ili default ne može se odabrati po imenu (te ključne riječi se prvo interpretiraju); na takvu kombinaciju treba se referirati putem njenog id-a.
• Glavna sklopka kompresije predstavlja tvrdu barijeru: kada je kompresija globalno onemogućena, ovo zaglavlje ne može je omogućiti.

Primijenjeni plan se odražava natrag u zaglavlju odgovora:

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

gdje je <source> jedan od request-header, routing-override, active-profile, auto-trigger, default, ili off.

---

Embeddinzi

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

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

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

ID-ovi u katalogu su u formatu provider/model (primjer: jina-ai/jina-embeddings-v5-omni-small). Goli Jina ID-ovi modela koji se pojavljuju u registru (na primjer jina-embeddings-v5-text-small, jina-reranker-v3.5) također se razrješavaju. Jina embed/rerank/classify/segment prvo koriste vjerodajnice jina-ai iz nadzorne ploče; JINA_AI_API_KEY je rezervni izbor samo kada nema ključa u nadzornoj ploči. Kartica jina-reader odnosi se isključivo na Reader / r.jina.ai (POST /v1/web/fetch) i nikada ne poslužuje embeddinge ili rerank.

Modeli u registru koji oglašavaju podršku za multimodalnost također prihvaćaju do 32 provider-neutralne strukturirane stavke. Vrste medijskih stavki su text, image, audio, video i document. Njihov medijski 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 obiteljski alias jina-ai/jina-embeddings-v5-omni → omni-small) također prihvaća Jinine izvorne EmbeddingsV5Request dokumente i prosljeđuje ih neizmijenjene 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 vrijednosti { image | audio | video | pdf } mogu biti javni HTTPS URL, data: URI ili sirovi base64. OmniRoute ne pretvara te objekte u nizove niti dohvaća izvorne URL-ove slika — Jina sama dohvaća javne medije. Dodatna Jina polja (task, normalized, truncate, embedding_type) se prosljeđuju. Jina SKU-ovi samo za tekst i dalje odbijaju dokumente koji nisu tekstualni.

Sigurnosna i transportna ograničenja:

• URL-ovi udaljenih medija moraju biti javni HTTPS. Kanonske {type,source:url} stavke dohvaćaju se na strani servera (revalidacija preusmjeravanja, timeout, ograničenja veličine, javni DNS, pinning veze) i ugrađuju se prije poziva providera. Jina-native {image:"https://..."} stavke prosljeđuju se onakve kakve jesu nakon iste provjere javnog HTTPS-a; Jina dohvaća URL.
• Inline base64 mediji ograničeni su na 8 MiB dekodirano po stavci i 16 MiB dekodirano po cijelom zahtjevu.

Prevođenje na razini providera (kanonske stavke se nikada ne prosljeđuju nepromijenjene):

• Jina multimodalni modeli: svaka stavka na vrhovnoj razini postaje jedan objekt s ključem modaliteta (text / image / audio / video / pdf) koristeći data URI-je za inline medije; jedan vektor po stavci na vrhovnoj razini.
• Obitelj Gemini Embedding 2: jedan niz na vrhovnoj razini postaje jedan izvorni models/{model}:embedContent zahtjev s content.parts (text ili inline_data).
• Nepoznati/dinamički modeli bez izričitih metapodataka o modalitetu odbijaju strukturirani unos s 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 umjesto prisilnog pretvaranja stavke. Polja proširenja koja nisu ulazna, na naslijeđenim string/token zahtjevima, i dalje se prosljeđuju nepromijenjena.

# Ispis svih modela za embeddinge
GET /v1/embeddings

---

Generiranje slika

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

Dostupni pružatelji usluga: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, SD WebUI (lokalno), ComfyUI (lokalno).

# Prikaži sve modele za generiranje slika
GET /v1/images/generations

---

OCR dokumenata

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 odabire OCR pružatelja usluge putem prefiksa provider/model; goli identifikator modela (npr. mistral-ocr-latest) razrješava se do svog registriranog pružatelja, a izostavljeni model zadano se postavlja na Mistral (mistral-ocr-latest). Registrirani pružatelji (open-sse/config/ocrRegistry.ts):

Id pružatelja	Id modela	Vrijednost model	Bilješke
mistral	mistral-ocr-latest	mistral/mistral-ocr-latest (ili goli mistral-ocr-latest)	Sinkrono — odgovor se vraća izravno iz jedinog nadređenog poziva.
azure-document-intelligence	prebuilt-read	azure-document-intelligence/prebuilt-read	Asinkroni nadređeni poziv (analyze + poll) — pogledajte niže.
vertex-deepseek-ocr	deepseek-ocr-maas	vertex-deepseek-ocr/deepseek-ocr-maas	Sinkrono, putem Vertex AI-jevog partnerskog krajnjeg čvora openapi/chat/completions — pogledajte niže za autentifikaciju/URL.

Sva tri pružatelja odgovaraju u istom obliku tijela kao Mistral:

{
  "pages": [{ "index": 0, "markdown": "# Extracted text..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}

Tok anketiranja (poll) za Azure Document Intelligence

Azure Document Intelligence-ov analyze API je asinkron: početni zahtjev vraća zaglavlje Operation-Location umjesto tijela, a rezultat se mora dobiti anketiranjem (poll). Handler (open-sse/handlers/ocr.ts) anketira taj URL svake sekunde tijekom najviše 30 pokušaja, brzo prekida (ne nastavlja s anketiranjem) u slučaju odgovora koji nije ok ili statusa "failed", i vraća 504 ako je operacija još u tijeku nakon što se potroši budžet pokušaja. Konačni Azure odgovor se normalizira u isti oblik pages/markdown koji koristi Mistral prije nego što se vrati pozivatelju, tako da klijentski kod ne treba posebno tretirati ovog pružatelja.

Autentifikacija i razrješavanje krajnjeg čvora za Vertex AI DeepSeek OCR

vertex-deepseek-ocr ponovno koristi istu Vertex AI autentifikaciju koju OmniRoute već podržava za chat/image prijenos podataka (open-sse/executors/vertex.ts): API ključ veze je ili Service Account JSON vjerodajnica (razmijenjena za kratkotrajni OAuth pristupni token putem JWT-bearer protoka) ili već izdan OAuth pristupni token koji se koristi kao takav. URL nadređenog krajnjeg čvora je Vertex-ov generički partnerski krajnji čvor openapi/chat/completions, izgrađen iz projekta i regije veze — eksplicitni providerSpecificData.project/providerSpecificData.region uvijek ima prednost; u protivnom se projekt izvodi iz project_id Service Account JSON-a, a regija se zadano postavlja na us-central1. Oba razrješavanja se odvijaju u open-sse/handlers/ocr.ts (resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl), koje koristi src/app/api/v1/ocr/route.ts prije prosljeđivanja funkciji handleOcr.

---

Popis modela

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

→ Vraća sve chat, embedding i image modele + kombinacije u OpenAI formatu

Prefiksi id-a modela (?prefix=)

Većina modela se oglašava pod prefiksom pružatelja usluge. Koji prefiks ćete dobiti kontrolira oznaka funkcije MODELS_CATALOG_PREFIX_MODE, a može se nadjačati po zahtjevu s query parametrom — korisno za klijenta koji želi čist popis bez mijenjanja postavke na razini poslužitelja za sve ostale korisnike:

GET /v1/models?prefix=alias        # jedan id po modelu — kratki alias prefiks
GET /v1/models?prefix=dual         # oba oblika (zadano na poslužitelju)
GET /v1/models?prefix=canonical    # samo prefiks s cijelim id-om pružatelja usluge

Način	Emitira	Napomene
dual	cc/claude-sonnet-4-6 i claude/claude-sonnet-4-6	Zadano. Oba id-a preusmjeravaju na isti model; zadržano kako bi konfiguracije klijenata koje su tvrdo kodirale bilo koji od oblika i dalje radile. Približno duplira katalog.
alias	cc/claude-sonnet-4-6	Jedan unos po modelu. Pružatelji usluge bez zasebnog aliasa i dalje emitiraju svoj unos, tako da ništa nije izgubljeno.
canonical	claude/claude-sonnet-4-6	Jedan unos po modelu pod prefiksom cijelog id-a pružatelja usluge. Pružatelji usluge bez zasebnog aliasa (npr. antigravity/…, agy/…) ovdje također emitiraju svoj jedini id, tako da ništa nije izgubljeno.

dual-mod zrcalo se također može prepoznati bez query parametra: sadrži polje parent koje pokazuje na primarni id.

Klijenti koji prikazuju birač modela trebaju zatražiti ?prefix=alias — ovo je ono što OmniCopilot VS Code ekstenzija radi.

Varijante modela bez razmišljanja (no-thinking)

Za Claude modele koji su sposobni za razmišljanje, /v1/models također oglašava no-thinking varijantu čiji je id prefiksiran s claude-3-omniroute-no-thinking/:

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

Odabir ovog id-a (npr. u Claude Code konfiguraciji koja uvijek prilaže thinking blok) razrješava se natrag na stvarni <provider>/<model> s ugušenim zaključivanjem (reasoning) — thinking:{type:"disabled"} na /v1/messages putanji, ili se polja reasoning/reasoning_effort izostavljaju na /v1/chat/completions putanji. Varijanta je navedena samo za modele iz Claude obitelji koji podržavaju razmišljanje i poštuju disabled (tako su npr. isključivo adaptivni modeli koji odbijaju disabled izuzeti). Operatori mogu prisilno uključiti ili isključiti varijantu po modelu putem ModelSpec.noThinkingAlias.

---

Provider Plugin Manifest

GET /api/v1/provider-plugin-manifest

Vraća JSON-safe manifest provider plugina koji koriste Bifrost, CLIProxyAPI i budući sidecar ruteri. Odgovor se generira iz TypeScript registra providera i namjerno ne uključuje OAuth client secrets, razrješavanje runtime okruženja, executor funkcije, request headere i podatke o računima.

Koristite ovaj endpoint kada sidecar radi izvan procesa (out-of-process) i ne može direktno importirati 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 (edit/inpaint)
POST	/v1/videos/generations	Generiranje videa u OpenAI stilu
POST	/v1/music/generations	Generiranje glazbe u OpenAI stilu
POST	/v1/audio/transcriptions	OpenAI Audio (STT)
POST	/v1/audio/speech	OpenAI TTS (vraća audio tijelo)
POST	/v1/rerank	Rerank u stilu Cohere/Voyage
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 katalog alias
GET	/api/v1/vscode/{token}/models	OpenAI models alias
POST	/api/v1/vscode/{token}/chat/completions	OpenAI tokenizirani alias
POST	/api/v1/vscode/{token}/responses	OpenAI Responses tokenizirani alias
POST	/api/v1/vscode/{token}/api/chat	Ollama tokenizirani alias
GET	/api/v1/vscode/{token}/api/tags	Ollama tags tokenizirani alias

Svi POST route-ovi slijede isti oblik: Bearer your-api-key + Zod-validirano JSON tijelo (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema, itd., pogledajte src/shared/validation/schemas.ts). Kod neuspjeha validacije sheme vraća se 4xx.

Za klijente koji ne mogu priložiti Authorization: Bearer ..., OmniRoute također prihvaća API ključeve u URL-u putem query-string kompatibilnosti (?token=..., ?apiKey=..., ?api_key=..., ?key=...) ili putem posebnih /api/v1/vscode/{token}/... endpointa opisanih u nastavku.

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

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

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

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

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

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

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

# Generiranje videa / glazbe (ID modela s prefiksom providera)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

Namjenske Provider Rute

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

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

---

Files API

OpenAI-kompatibilan krajnji zahtjev (endpoint) za datoteke za grupni unos/izlaz i prijenose s namjenom datoteke.

Metoda	Putanja	Opis
POST	/v1/files	Prijenos datoteke (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — maksimalno 512 MiB
GET	/v1/files	Prikaz popisa datoteka za autentificirani API ključ
GET	/v1/files/[id]	Dohvat metapodataka datoteke
DELETE	/v1/files/[id]	Brisanje datoteke
GET	/v1/files/[id]/content	Strujanje (streaming) sirovog sadržaja datoteke

Autentikacija: Bearer API ključ — datoteke su ograničene po API ključu putem getApiKeyRequestScope.

---

Batches API

OpenAI-kompatibilna grupna obrada.

Metoda	Putanja	Opis
POST	/v1/batches	Kreiranje grupe (batch) — tijelo zahtjeva validirano putem v1BatchCreateSchema (input_file_id, endpoint, completion_window)
GET	/v1/batches	Prikaz popisa grupa
GET	/v1/batches/[id]	Dohvat statusa grupe + request_counts
DELETE	/v1/batches/[id]	Brisanje završene/neuspjele grupe
POST	/v1/batches/[id]/cancel	Otkazivanje grupe u tijeku obrade

Autentikacija: Bearer API ključ. Grupe su ograničene po API ključu.

---

Search API

Apstrakcija davatelja usluga za pretraživanje weba/pretragu (Tavily, Brave, Exa, Serper, itd.).

Metoda	Putanja	Opis
GET	/v1/search	Prikaz popisa konfiguriranih davatelja usluga pretraživanja + mogućnosti
POST	/v1/search	Izvršavanje upita za pretraživanje — tijelo zahtjeva validirano putem v1SearchSchema, podržava predmemoriranje/spajanje zahtjeva
GET	/v1/search/analytics	Statistika pogodaka/latencije/predmemorije po davatelju usluga

Autentikacija: Bearer API ključ (extractApiKey + isValidApiKey). Politika pretraživanja provodi se putem enforceApiKeyPolicy.

---

Web Fetch API

Ekstrahiraj sadržaj s URL-a putem konfiguriranog web-fetch pružatelja (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

Metoda	Putanja	Opis
POST	/v1/web/fetch	Dohvati/scrape-aj URL — tijelo se validira putem v1WebFetchSchema

Autentikacija: Bearer API ključ (extractApiKey + isValidApiKey). Politika se provodi putem enforceApiKeyPolicy.

Fallback svjestan kvota (#8297): kada nije naveden explicitan provider, pool (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) se prolazi fiksnim prioritetnim redoslijedom (fill-first) — pružatelj koji je ograničen po brzini, ali je konfiguriran, preskoči se umjesto da prekine zahtjev, a kvar koji se može pokušati ponovno/kvota nadređenog sustava (HTTP 429 uvijek; 402/403 za Firecrawl/Tavily/TinyFish besplatne razine tipa kvote — ne za Jina Reader, i nikad za jednostavan 400 loš zahtjev) prelazi na sljedećeg neisprobanog pružatelja s vjerodajnicama u trenutku zahtjeva. Kada je svaki pružatelj u poolu iscrpljen, endpoint vraća jedan 429 (s zaglavljem Retry-After) umjesto prethodnog generičkog 400. Kada je explicitno zatražen provider, nema tihog fallbacka — explicitan pružatelj koji je ograničen po brzini ili ne radi prikazuje svoju vlastitu grešku (429 ako je ograničen po brzini, u suprotnom status nadređenog sustava).

---

WebSocket Streaming

GET /v1/ws?handshake=1

Validira handshake za WebSocket upgrade i vraća primjere poruka za wire protokol (request, cancel). Stvarni WS okviri se obrađuju putem ugrađenog WS servera izvan Next.js tablice ruta.

Autentikacija: Bearer API ključ tijekom handshakea.

Responses API preko WebSocket-a (samo codex)

# Isti host:port kao HTTP API (zadano 20128); upgrade-aj vezu:
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" } ] }

Proxy Responses-API-preko-WebSocket-a povezan je isključivo na codex (ChatGPT backend). Sluša na istom portu kao API/nadzorna ploča na putanjama /v1/responses, /responses, i /api/v1/responses. Na prvom okviru response.create se autentificira + priprema putem internog mosta codex-responses-ws, odabire codex OAuth vezu, i tunelira do wss://chatgpt.com/backend-api/codex/responses putem wreq-js transporta. Modeli koji nisu codex se odbijaju (codex_ws_provider_required). Za usmjeravanje po podjeli kvote koristi 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.

Autentikacija: Bearer API ključ tijekom handshakea. Ugrađeni HTTP server (server-ws.mjs) mora biti aktivna ulazna točka (jest, po zadanim postavkama, kada app/server-ws.mjs postoji).

ID modela: koristi gol ChatGPT ID (bez prefiksa codex/)

OpenAI Codex CLI validira ime modela na klijentskoj strani kada je supports_websockets = true i odbija ID-ove s prefiksom pružatelja poput codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Pošalji goli ID (npr. gpt-5.5). OmniRoute-ov most je samo za codex, tako da ponovno rješava goli ID kao codex model (resolveCodexWsModelInfo) prije tuneliranja prema nadređenom sustavu — čak i unatoč tome što bi goli gpt-5.5 inače usmjerio prema drugom pružatelju preko HTTP-a.

Konfiguriranje OpenAI Codex CLI

Usmjeri Codex CLI prema OmniRoute dodavanjem prilagođenog pružatelja s podrškom za WebSocket u ~/.codex/config.toml (koristi zasebni CODEX_HOME da bi izbjegao mijenjanje 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 zaključne kose crte; WS URL se izvodi (koristi https/wss u produkciji)
wire_api = "responses"                    # jedina podržana vrijednost od veljače 2026
supports_websockets = true                # omogućuje 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 nadograđuje base_url + /responses na WebSocket i OmniRoute ga tunelira prema odabranoj codex OAuth vezi. Validirano end-to-end u odnosu na lokalni server: ChatGPT vraća codex.rate_limits + response.created i strimira dovršenje.

---

Kvote i prijavljivanje problema

Metoda	Putanja	Opis
GET	/v1/quotas/check	Unaprijed provjeri kvotu za provider + accountId prije izdavanja registriranog ključa
POST	/v1/issues/report	Prijavi GitHubu neuspjeh kvote/izdavanja ključa (zahtijeva GITHUB_ISSUES_REPO + token)

Autentifikacija: Bearer API ključ (isAuthenticated).

---

Samoposluživanje korištenja (/api/usage/om-usage)

Svaki API ključ može pročitati svoje vlastito korištenje i kvote — nije potrebna administratorska autentifikacija. Ovo je krajnja točka koju klijent (CLI, OmniCopilot panel) koristi da vlasniku ključa prikaže njegovu potrošnju.

# Tekstualni oblik (povijesni ugovor — čisti tekst za terminal)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Strukturirani oblik — što koristi korisničko sučelje
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

Ključ mora imati omogućen allowUsageCommand (podrazumijevano isključen — upravitelj API ključeva u nadzornoj ploči ga uključuje po ključu). Bez toga krajnja točka odgovara s 403.

?format=json vraća diskriminirani oblik tako da pozivatelj nikad ne čita podatkovno polje iz odbijenog odgovora. Kod uspjeha:

{
  "allowed": true,
  // prisutno samo kad se ključ prijavio za ograničenja korištenja po ključu (dnevno/tjedno u USD):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // snimka odabrane kvote pružatelja usluge, ili null ako još ništa nije predmemorirano:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // snimka svake veze, tako da korisničko sučelje može prikazati više pružatelja usluga jedan uz drugi:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

Kod odbijanja (401 neispravan ključ / 403 nije dozvoljeno) ista ruta vraća { "allowed": false, "error": { "message": "…" } } — prisutan-ali-praznо personal/provider (ključ je dozvoljen, ali ništa još nije saznano) je drugačije stanje od odbijanja, a samo JSON oblik ih razlikuje.

Autentifikacija: vlastiti Bearer API ključ pozivatelja, validiran pomoću isValidApiKey — ovo nije administratorska površina (/api/keys/…), koja ostaje iza requireManagementAuth.

---

Semantička predmemorija

# Dobavi statistiku predmemorije
GET /api/cache/stats

# Očisti sve predmemorije
DELETE /api/cache/stats

Primjer odgovora:

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

Utjecaj na latenciju

HIT semantičke predmemorije poslužuje odgovor iz predmemorije bez pozivanja uzvodnog servisa, tako da je prijavljena vrijednost X-OmniRoute-Response-Latency skoro nulta (bez obzira na izvornu uzvodnu latenciju). Klijenti osjetljivi na latenciju (benchmarking, p50/p99 nadzor) trebaju provjeriti zaglavlje odgovora X-OmniRoute-Cache-Latency:

Vrijednost	Značenje
synthetic	Odgovor poslužen iz predmemorije; latencija nije stvarno uzvodno vrijeme
(nema je)	Odgovor iz stvarnog uzvodnog poziva

Zaobilaženje predmemorije po ključu

API ključevi mogu odbiti čitanje iz semantičke predmemorije putem cacheDefaultMode:

Vrijednost	Ponašanje
legacy	Normalno ponašanje predmemorije (zadano)
bypass	Potpuno preskoči pretraživanje predmemorije; uvijek pozovi uzvodni servis

Postavlja se prilikom stvaranja ključa (POST /api/keys) ili ažuriranja (PATCH /api/keys/[id]):

{ "cacheDefaultMode": "bypass" }

Zaobilaženje po zahtjevu

Svaki zahtjev može zaobići predmemoriju bez obzira na postavke ključa:

X-OmniRoute-No-Cache: true

---

Nadzorna ploča i upravljanje

Rute za upravljanje (/api/* osim javnih ruta za autentifikaciju/prijavu) nisu autorizirane pomoću običnih API ključeva za inferenciju. Obitelji vjerodajnica, opsezi i primjeri curl naredbi: Management Authentication.

Autentifikacija

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

Upravljanje pružateljima usluga

Endpoint	Metoda	Opis
/api/providers	GET/POST	Ispis / stvaranje pružatelja usluga
/api/providers/[id]	GET/PUT/DELETE	Upravljanje pružateljem usluge
/api/providers/[id]/test	POST	Testiranje veze s pružateljem usluge
/api/providers/[id]/models	GET	Ispis modela pružatelja usluge
/api/providers/validate	POST	Provjera konfiguracije pružatelja usluge
/api/providers/bulk	POST	Grupno dodavanje API ključeva za JEDNOG pružatelja usluge
/api/providers/import	POST	Uvoz heterogenog POPISA pružatelja usluga iz obrađene CSV/JSON datoteke (#6836); rezultati djelomičnog neuspjeha po redu
/api/provider-nodes*	Različito	Upravljanje čvorovima pružatelja usluga
/api/provider-models	GET/POST/PATCH/DELETE	Prilagođeni modeli (dodavanje, ažuriranje, sakrivanje/prikazivanje, brisanje)

OAuth tijekovi

Endpoint	Metoda	Opis
/api/oauth/[provider]/[action]	Različito	OAuth specifičan za pružatelja usluge

Usmjeravanje i konfiguracija

Endpoint	Metoda	Opis
/api/models/alias	GET/POST	Aliasi modela
/api/models/catalog	GET	Svi modeli po pružatelju i vrsti
/api/combos*	Različito	Upravljanje kombinacijama
/api/keys*	Različito	Upravljanje API ključevima
/api/pricing	GET	Cijene modela

Korištenje i analitika

Endpoint	Metoda	Opis
/api/usage/history	GET	Povijest korištenja
/api/usage/logs	GET	Zapisi korištenja
/api/usage/request-logs	GET	Zapisi na razini zahtjeva
/api/usage/[connectionId]	GET	Korištenje po pojedinoj vezi
/api/usage/token-limits	GET/POST/DELETE	Proračuni ograničenja tokena po API ključu
/api/usage/model-latency-stats	GET	Klizni agregat latencije po pružatelju/modelu (prosjek/p50/p95/p99, stopa uspjeha); filtri: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health	GET	Sažetak stanja predmemorije upita (prompt-cache) na temelju call_logs — omjer pisanja/čitanja, raspodjela veličine pisanja p50/p90/p99, koncentracija intenzivnog pisanja, podjela po modelu, i procjena healthy/degraded/thrash/no-data; parametri upita range (1h|24h|7d|30d, zadano 24h) i opcionalni model (#8827)

Postavke

Endpoint	Metoda	Opis
/api/settings	GET/PUT/PATCH	Opće postavke
/api/settings/proxy	GET/PUT	Konfiguracija mrežnog proxyja
/api/settings/proxy/test	POST	Testiranje proxy veze
/api/settings/ip-filter	GET/PUT	Popis dopuštenih/blokiranih IP adresa
/api/settings/thinking-budget	GET/PUT	Način prepisivanja zahtjeva za razmišljanje/zaključivanje (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 redaka zapisa zahtjeva i lokalnih artefakata zapisa poziva

Kontekst i kompresija

Endpoint	Metoda	Opis
/api/compression/preview	POST	Pregled kompresije off/lite/standard/aggressive/ultra/RTK/stacked
/api/compression/language-packs	GET	Popis dostupnih Caveman jezičnih paketa
/api/compression/rules	GET	Popis metapodataka Caveman pravila
/api/context/caveman/config	GET/PUT	Alias za Caveman postavke
/api/context/rtk/config	GET/PUT	RTK-specifične postavke, uključujući prilagođene filtre i čuvanje sirovog izlaza
/api/context/rtk/filters	GET	Katalog RTK filtara i dijagnostika prilagođenih filtara
/api/context/rtk/test	POST	Pokretanje RTK pregleda/testa na tekstualnom sadržaju
/api/context/rtk/raw-output/[id]	GET	Čitanje sačuvanog redigiranog sirovog izlaza prema id pokazivača
/api/context/combos	GET/POST	Popis/stvaranje kombinacija kompresije
/api/context/combos/[id]	GET/PUT/DELETE	Detalji/ažuriranje/brisanje kombinacije kompresije
/api/context/combos/[id]/assignments	GET/PUT	Dodjela kombinacija kompresije kombinacijama usmjeravanja
/api/context/analytics	GET	Alias za analitiku kompresije

Nadzor

Endpoint	Metoda	Opis
/api/sessions	GET	Praćenje aktivnih sesija
/api/rate-limits	GET	Ograničenja stope po računu
/api/monitoring/health	GET	Provjera zdravlja + sažetak pružatelja usluga (catalogCount, configuredCount, activeCount, monitoredCount)
/api/cache/stats	GET/DELETE	Statistika predmemorije / brisanje
/api/modality-bridge/stats	GET	Statistike u memoriji: attempts, uspjesi/bridged, neuspjesi, pogoci predmemorije, totalLatencyMs, latencySamples, averageLatencyMs izraženo prema broju uzoraka, i vrijeme posljednje uporabe (resetira se pri ponovnom pokretanju; potrebna autentifikacija za upravljanje)
/api/modality-bridge/video/runtime	GET	Strogа provjera pouzdane loopback veze prije autentifikacije za upravljanje/provjere; sanitizirana dostupnost i verzije FFmpeg/ffprobe (no-store)
/api/modality-bridge/video/extract	POST	Interni autentificirani posrednik podataka putem pouzdane loopback veze; ulaz 50 MiB, ograničen red čekanja/izlaz 32 MiB, 503 kapacitet, 499 prekid veze, 504 rok; nije javni API za prijenos

Sigurnosne kopije i izvoz/uvoz

Endpoint	Metoda	Opis
/api/db-backups	GET	Popis dostupnih sigurnosnih kopija
/api/db-backups	PUT	Stvaranje ručne sigurnosne kopije
/api/db-backups	POST	Obnova iz određene sigurnosne kopije
/api/db-backups/export	GET	Preuzimanje baze podataka kao .sqlite datoteke
/api/db-backups/import	POST	Prijenos .sqlite datoteke za zamjenu baze podataka
/api/db-backups/exportAll	GET	Preuzimanje potpune sigurnosne kopije kao .tar.gz arhive

Sinkronizacija u oblaku

Endpoint	Metoda	Opis
/api/sync/cloud	Različito	Operacije sinkronizacije u oblaku
/api/sync/initialize	POST	Inicijalizacija sinkronizacije
/api/cloud/*	Različito	Upravljanje oblakom

Tuneli

Endpoint	Metoda	Opis
/api/tunnels/cloudflared	GET	Čitanje statusa instalacije/rada Cloudflare Quick Tunnela za nadzornu ploču
/api/tunnels/cloudflared	POST	Uključivanje ili isključivanje Cloudflare Quick Tunnela (action=enable/disable)
/api/tunnels/ngrok	GET	Čitanje statusa rada ngrok Tunnela za nadzornu ploču
/api/tunnels/ngrok	POST	Uključivanje ili isključivanje ngrok Tunnela (action=enable/disable)

CLI alati

Endpoint	Metoda	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	Metoda	Opis
/api/acp/agents	GET	Ispis svih otkrivenih agenata (ugrađenih + prilagođenih) sa statusom
/api/acp/agents	POST	Dodavanje prilagođenog agenta ili obnavljanje predmemorije otkrivanja
/api/acp/agents	DELETE	Uklanjanje prilagođenog agenta prema parametru upita id

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

Otpornost i ograničenja stope

Endpoint	Metoda	Opis
/api/resilience	GET/PATCH	Dohvat/ažuriranje reda čekanja zahtjeva, hlađenja veze, prekidača za pružatelja usluge i postavki čekanja
/api/resilience/reset	POST	Reset prekidača kruga (circuit breakers) pružatelja usluga
/api/resilience/model-cooldowns	GET	Popis aktivnih blokada po (pružatelju, vezi, modelu), sortirano po preostalom vremenu
/api/resilience/model-cooldowns	DELETE	Uklanjanje blokade modela — tijelo {provider, model} ili {all: true} za brisanje svega
/api/rate-limits	GET	Status ograničenja stope po računu
/api/rate-limit	GET	Globalna konfiguracija ograničenja stope

Sve četiri rute /api/resilience/* zahtijevaju autentifikaciju za upravljanje (requireManagementAuth). Pogledajte Resilience (extended) za potpuni pregled razlika između prekidača pružatelja usluge, hlađenja veze i blokade modela.

Evaluacije

Endpoint	Metoda	Opis
/api/evals	GET/POST	Popis paketa evaluacije / pokretanje evaluacije

Politike

Endpoint	Metoda	Opis
/api/policies	GET/POST/DELETE	Upravljanje politikama usmjeravanja

Usklađenost

Endpoint	Metoda	Opis
/api/compliance/audit-log	GET	Zapis revizije usklađenosti (posljednjih N)

v1beta (kompatibilno s Gemini)

Endpoint	Metoda	Opis
/v1beta/models	GET	Popis modela u Gemini formatu
/v1beta/models/{...path}	POST	Gemini generateContent krajnja točka

Ove krajnje točke oponašaju Gemini API format za klijente koji očekuju izvornu kompatibilnost s Gemini SDK-om.

Interni/sistemski API-jevi

Endpoint	Metoda	Opis
/api/init	GET	Provjera inicijalizacije aplikacije (koristi se pri prvom pokretanju)
/api/tags	GET	Oznake modela kompatibilne s Ollama (za Ollama klijente)
/api/restart	POST	Pokretanje kontroliranog ponovnog pokretanja poslužitelja
/api/shutdown	POST	Pokretanje kontroliranog isključivanja poslužitelja
/api/system/env/repair	POST	Popravak varijabli okoline za OAuth pružatelja usluge

Napomena: Ove krajnje točke koristi interno sustav ili se koriste za kompatibilnost s Ollama klijentima. Obično ih ne pozivaju krajnji korisnici.

Popravak OAuth varijabli okoline (v3.6.1+)

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

{
  "provider": "claude-code"
}

Popravlja nedostajuće ili oštećene varijable okoline za OAuth za određenog pružatelja usluge. 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"
}

---

Transkripcija audio zapisa

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

Transkribirajte audio datoteke koristeći bilo kojeg konfiguriranog STT pružatelja usluge. Prvi segment putanje odabire izvornog pružatelja usluge (openai/…, deepgram/…). Gatewayi koji ponovno izvoze model drugog dobavljača koriste kvalificirani id (openrouter/deepgram/nova-3).

Zahtjev:

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

Odgovor:

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

Primjeri id-ova modela: openai/whisper-1 (zahtijeva OpenAI ključ), openrouter/deepgram/nova-3 (zahtijeva OpenRouter ključ), deepgram/nova-3 (zahtijeva izvorni Deepgram ključ). Zahtjev s golim deepgram/nova-3 ne koristi OpenRouter.

Podržani formati: mp3, wav, m4a, flac, ogg, webm.

---

Kompatibilnost s Ollama

Za klijente koji koriste Ollama API format:

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

# Popis modela (Ollama format)
GET /api/tags

Zahtjevi se automatski prevode između Ollama i internih formata.

Tokenizirani VS Code / aliasi bez zaglavlja

Koristite ove aliase kada integracija ne može ubaciti Authorization zaglavlje i treba API ključ ugrađen u osnovni URL.

# Alias kataloga u OpenAI stilu
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# Chat aliasi u OpenAI stilu
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Aliasi u Ollama stilu
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

Primjer:

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

Napomene:

• Tokenizirani aliasi ponovno koriste iste rukovatelje kao /v1/* i /api/tags; oblici odgovora ostaju identični.
• Preferirajte Authorization: Bearer ... kad god klijent podržava prilagođena zaglavlja.
• Tokeni temeljeni na URL-u mogu se pojaviti u zapisima reverse proxyja, povijesti preglednika i telemetriji izvan OmniRoutea. Tretirajte ih kao opciju kompatibilnosti, a ne kao zadani način autentifikacije.

---

Telemetrija

# Dohvat sažetka telemetrije latencije (p50/p95/p99 po pružatelju usluge)
GET /api/telemetry/summary

Odgovor:

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

---

Budžet

# Dohvat statusa budžeta za sve API ključeve
GET /api/usage/budget

# Postavljanje ili ažuriranje budžeta
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"
}

Napomene o shemi (setBudgetSchema): apiKeyId je obavezan; najmanje jedan od dailyLimitUsd, weeklyLimitUsd ili monthlyLimitUsd mora biti veći od nule. Neobavezna polja: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). Zastarjeli oblik {keyId, limit, period} vraća 400 Bad Request.

Ograničenja tokena

Proračuni za token po API ključu (odvojeni od gore navedenog proračuna u USD). Provode se izravno na putu zahtjeva: kada trenutna iskorištenost prozora ključa dosegne svoje ograničenje, zahtjevi se odbijaju s 429 Too Many Requests. Ograničenja mogu biti vezana za određeni model, provider, ili primijenjena globalno na cijeli ključ; kada nekoliko ograničenja odgovara zahtjevu, pobjeđuje najstriktnije.

# Prikaz ograničenja tokena za ključ (uključuje trenutnu iskorištenost prozora)
GET /api/usage/token-limits?apiKeyId=key-123

# Izradi ili ažuriraj ograničenje tokena
POST /api/usage/token-limits
Content-Type: application/json

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

# Obriši ograničenje tokena prema id-u
DELETE /api/usage/token-limits?id=tl-abc

Napomene o shemi (setTokenLimitSchema): apiKeyId i scopeType (model | provider | global) su obavezni. scopeValue je obavezan osim ako je scopeType postavljen na global (npr. id modela za model opseg, id providera za provider opseg). tokenLimit mora biti pozitivan cijeli broj (pretvara se iz stringa). Opcionalno: id (izostavite za izradu, navedite za ažuriranje), resetInterval (daily | weekly | monthly, zadano monthly), resetTime (HH:MM), enabled (zadano true). GET odgovori obogaćuju svako ograničenje s tokensUsed, remaining, windowStart, periodStartAt i nextResetAt. Ovo je krajnja točka klase upravljanja (autorizacija se provodi centralno kroz authz pipeline).

Obrada zahtjeva

1. Klijent šalje zahtjev na /v1/*
2. Route handler poziva handleChat, handleEmbedding, handleAudioTranscription, ili handleImageGeneration
3. Model se razrješuje (direktni provider/model ili alias/combo)
4. Vjerodajnice se odabiru iz lokalne baze podataka uz filtriranje po dostupnosti računa
5. Za chat: handleChatCore provjerava semantičku/potpisnu (signature) predmemoriju i razrješuje postavke kompresije za combo
6. Proaktivna kompresija pokreće se prije prevođenja za providera kada je omogućena (lite, Caveman, RTK, ili slaganje više njih)
7. Executor providera šalje zahtjev prema uzvodnom (upstream) servisu
8. Odgovor se prevodi natrag u format klijenta (chat) ili se vraća nepromijenjen (embeddings/images/audio)
9. Bilježe se podaci o korištenju, analitika kompresije i logovi zahtjeva
10. Fallback se primjenjuje na greške prema pravilima combo-a

Cjelovita referenca arhitekture: ARCHITECTURE.md

---

Upravljanje combo-ima

Combo rute na višoj razini (već sažete pod /api/combos*) mogu se također mapirati 1:1 iz uzorka id-a modela, omogućujući transparentno preusmjeravanje id-a modela u OpenAI stilu na combo.

Metoda	Putanja	Opis
GET	/api/model-combo-mappings	Prikaz svih mapiranja model→combo
POST	/api/model-combo-mappings	Izradi mapiranje — tijelo: {pattern, comboId, priority?, enabled?, description?}
GET	/api/model-combo-mappings/[id]	Dohvati jedno mapiranje
PUT	/api/model-combo-mappings/[id]	Ažuriraj polja postojećeg mapiranja
DELETE	/api/model-combo-mappings/[id]	Ukloni mapiranje

Autorizacija: upravljačka sesija/API ključ (requireManagementAuth).

---

Webhooks

Odlazne pretplate na webhookove za OmniRoute događaje (dovršetak zahtjeva, iscrpljenje kvote, rotacija ključeva itd.).

Metoda	Putanja	Opis
GET	/api/webhooks	Popis webhookova (tajni podaci su maskirani u <prefix>...)
POST	/api/webhooks	Kreiraj webhook — tijelo: {url, events?: ["*"], secret?, description?}
GET	/api/webhooks/[id]	Dohvati webhook
PUT	/api/webhooks/[id]	Ažuriraj url/events/secret/description
DELETE	/api/webhooks/[id]	Ukloni webhook
POST	/api/webhooks/[id]/test	Pošalji testni payload na URL webhooka i vrati status dostave

Autentikacija: upravljačka sesija/API ključ (requireManagementAuth).

---

Registrirani ključevi (Automatsko upravljanje)

Koristi ih podsustav za automatsko upravljanje ključevima za izdavanje i rotaciju API ključeva u odnosu na pozadinskog pružatelja usluge/račun, s dnevnim/satnim kvotama.

Metoda	Putanja	Opis
GET	/api/v1/registered-keys	Popis registriranih ključeva (samo maskirani prefiks)
POST	/api/v1/registered-keys	Izdaj novi registrirani ključ — tijelo: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. Vraća sirovi ključ jednom. Vraća 429 pri odbijanju zbog kvote.
GET	/api/v1/registered-keys/[id]	Dohvati metapodatke registriranog ključa (bez sirovog materijala)
DELETE	/api/v1/registered-keys/[id]	Opozovi registrirani ključ
POST	/api/v1/registered-keys/[id]/revoke	Explicitna krajnja točka za opoziv (isti učinak kao DELETE)

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

---

Protokol agenata

Zadaci cloud agenata (Claude Code, Codex Cloud, OpenHands, itd.) izvršeni na daljinu u ime OmniRoute korisnika.

Metoda	Putanja	Opis
GET	/api/v1/agents/tasks	Popis zadataka — opcionalno ?provider=, ?status=, ?limit= (1–500, zadano 50)
POST	/api/v1/agents/tasks	Stvaranje zadatka — tijelo se validira pomoću CreateCloudAgentTaskSchema (providerId, prompt, source, options?). Vraća 201 s omotnicom zadatka
DELETE	/api/v1/agents/tasks?id=...	Brisanje zadatka
GET	/api/v1/agents/tasks/[id]	Čitanje zadatka — sinkrono osvježava status s uzvodnog cloud agenta kada je postavljen external_id
POST	/api/v1/agents/tasks/[id]	Diskriminirana akcija: {action: "approve"}, {action: "message", message}, ili {action: "cancel"}
DELETE	/api/v1/agents/tasks/[id]	Brisanje određenog zadatka po id-u

Autentifikacija: upravljačka autentifikacija potrebna je za svaku metodu (requireCloudAgentManagementAuth). Prije v3.8.0 ove rute nisu bile autentificirane — pogledajte commit 588a0333 za promjenu koja narušava kompatibilnost.

# Stvaranje cloud zadatka za 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":"..."}}'

---

Upravljački proxyji

Izlazni HTTP(S)/SOCKS proxyji koji se mogu dodijeliti pružateljima usluga, računima ili globalno.

Metoda	Putanja	Opis
GET	/api/v1/management/proxies	Popis proxyja (s ?id= vraća jedan; s ?id=&where_used=1 vraća grafikon dodjela)
POST	/api/v1/management/proxies	Stvaranje proxyja — tijelo se validira pomoću createProxyRegistrySchema
PATCH	/api/v1/management/proxies	Ažuriranje proxyja — tijelo se validira pomoću updateProxyRegistrySchema (potreban id)
DELETE	/api/v1/management/proxies?id=...&force=1	Brisanje proxyja (koristite force=1 za odvajanje dodjela)
GET	/api/v1/management/proxies/assignments	Popis dodjela — moguće filtriranje po proxy_id, scope, scope_id; proslijedite resolve_connection_id=<id> za razrješavanje aktivnog proxyja za vezu
PUT	/api/v1/management/proxies/assignments	Dodjela — tijelo se validira pomoću proxyAssignmentSchema ({scope, scopeId?, proxyId?}). Briše predmemoriju dispečera
PUT	/api/v1/management/proxies/bulk-assign	Skupna dodjela — tijelo se validira pomoću bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?})
GET	/api/v1/management/proxies/health?hours=24	Zbirno zdravlje proxyja (broj uspjeha/neuspjeha, latencija) tijekom određenog razdoblja

Autentifikacija: upravljačka sesija/API ključ potrebni su za svaku rutu (requireManagementAuth).

Rute POST /api/v1/management/proxies/[id]/assignments i POST /api/v1/management/proxies/[id]/health iz opisa zadatka opslužuju ravne rute /assignments i /health prikazane iznad — u kodnoj bazi ne postoje podrute po id-u.

---

Otpornost (proširena)

OmniRoute izlaže tri nezavisna mehanizma za privremene kvarove; upravljački API-jevi ispod omogućuju operatorima da ih čitaju i nadjačavaju:

Opseg	Pohrana stanja	Čitanje	Resetiranje / brisanje
Provider breaker	domain_circuit_breakers + u memoriji	/api/monitoring/health	POST /api/resilience/reset
Cooldown veze	rateLimitedUntil na provider konekcijama	/api/rate-limits, /api/providers/[id]	(ponovo se aktivira lijeno; briše se putem provider PUT-a)
Zaključavanje modela	Registar dostupnosti modela u memoriji	GET /api/resilience/model-cooldowns	DELETE /api/resilience/model-cooldowns

PATCH /api/resilience prihvaća nadjačavanja provider breakera pod providerBreaker.oauth i providerBreaker.apikey. Svaki profil podržava degradationThreshold, failureThreshold i resetTimeoutMs; ista polja su izložena u Dashboard → Settings → Resilience.

# Obriši zaključavanje jednog modela
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"}'

# Obriši sva zaključavanja
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

Cjelovita konceptualna referenca i zadane vrijednosti breakera: pogledajte CLAUDE.md → "Resilience Runtime State".

---

Skillovi (vještine)

Okvir za vještine za proširivanje OmniRoutea prilagođenim izvršnim handlerima, uz integracije s marketplaceima.

Metoda	Putanja	Opis
GET	/api/skills	Prikaz instaliranih vještina — filtriranje putem ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local, s paginacijom
GET	/api/skills/[id]	Dohvat jedne vještine
PUT	/api/skills/[id]	Ažuriranje vještine (naziv, opis, mode, schema, handler, oznake)
DELETE	/api/skills/[id]	Deinstalacija vještine
POST	/api/skills/install	Instalacija vještine iz sirovog manifesta — tijelo: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET	/api/skills/executions	Prikaz nedavnih izvršavanja vještina (revizijski trag s ulazima/izlazima/trajanjem)
GET	/api/skills/marketplace?q=...	Pretraga/popis popularnih iz SkillsMP marketplacea (zahtijeva postavku skillsmpApiKey)
POST	/api/skills/marketplace/install	Instalacija vještine po id-u iz SkillsMP-a
GET	/api/skills/skillssh?q=&limit=	Pretraga skills.sh registra
POST	/api/skills/skillssh/install	Instalacija vještine po id-u iz skills.sh

Autentifikacija: upravljačka sesija/API ključ. Rute za pretragu marketplacea prihvaćaju ili upravljačku autentifikaciju ili Bearer API ključ (isAuthenticated).

---

Memorija

Trajna pohrana konverzacijske/činjenične memorije, s opsegom po API ključu / sesiji.

Metoda	Putanja	Opis
GET	/api/memory	Prikaz popisa memorija — ?apiKeyId=, ?type=, ?sessionId=, ?q=, s offset/limit ili page/limit paginacijom
POST	/api/memory	Izrada memorije — tijelo se validira putem Zod-a: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}
GET	/api/memory/[id]	Dohvat jedne memorije
DELETE	/api/memory/[id]	Brisanje memorije
GET	/api/memory/health	Status ispravnosti podsustava memorije (povezivost s bazom podataka, backend za ugrađivanje (embeddings), status vektorskog indeksa)

Autentifikacija: upravljačka sesija/API ključ (requireManagementAuth). type enum: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (vidi MemoryType u src/lib/memory/types.ts).

---

MCP poslužitelj

OmniRoute dolazi s ugrađenim Model Context Protocol poslužiteljem s 3 transportna mehanizma (stdio, SSE, streamable-http) i alatima s definiranim opsegom. Sljedeće krajnje točke nadzorne ploče čitaju podatke o statusu/revizijama i posreduju HTTP transportne mehanizme.

Metoda	Putanja	Opis
GET	/api/mcp/status	Otkucaj (heartbeat), transportni mehanizam, stanje povezanosti, posljednji poziv, top alati, stopa uspješnosti u posljednja 24 sata
GET	/api/mcp/tools	Popis MCP alata s poljima name, description, scopes, phase, auditLevel, sourceEndpoints
GET	/api/mcp/sse	Otvaranje SSE streama za SSE transportni mehanizam (vraća 503 ako je MCP onemogućen ili postoji nepodudaranje transportnog mehanizma)
POST	/api/mcp/sse	Slanje JSON-RPC okvira putem SSE transportnog mehanizma
GET	/api/mcp/stream	Otvaranje SSE strane Streamable HTTP transportnog mehanizma (poruke koje inicira poslužitelj)
POST	/api/mcp/stream	Slanje JSON-RPC okvira putem Streamable HTTP transportnog mehanizma
DELETE	/api/mcp/stream	Završetak Streamable HTTP sesije
GET	/api/mcp/audit	Upit prema zapisu revizija — ?limit=, ?offset=, ?tool=, `?success=true	false, ?apiKeyId=`
GET	/api/mcp/audit/stats	Agregirana statistika revizija (ukupni brojevi, stopa uspješnosti, prosječno trajanje, top alati)

Autentifikacija: transportni mehanizmi sse/stream poštuju specifičnu MCP autentifikacijsku površinu (Bearer API ključ s opsegom mcp); rute status/tools/audit* moguće je čitati s nadzorne ploče (nije potrebna dodatna autentifikacija osim pristupa hostu nadzorne ploče).

Oba HTTP transportna mehanizma ograničena su postavkama settings.mcpEnabled i settings.mcpTransport — nepodudaranje transportnog mehanizma vraća 400, a onemogućeno stanje MCP-a vraća 503.

---

A2A poslužitelj

OmniRoute izlaže A2A (Agent-to-Agent) JSON-RPC 2.0 krajnju točku plus REST omotač za pregled/upotrebu na nadzornoj ploči.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # opcionalno osim ako je postavljen 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"}]
  }
}

Podržane metode (sve su uvjetovane postavkom settings.a2aEnabled):

Metoda	Opis
message/send	Sinkrono izvršavanje vještine; vraća {task, artifacts, metadata}
message/stream	Streaming SSE izvršavanje istog skupa vještina
tasks/get	Dohvaćanje zadatka putem taskId
tasks/cancel	Otkazivanje zadatka putem taskId

Ugrađene vještine: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.

Agent Card

GET /.well-known/agent.json

Vraća javnu A2A agent karticu (naziv, opis, mogućnosti, katalog vještina, shema autentifikacije) — javno keširana 1h. Autentifikacija nije potrebna.

REST pomoćnici

Metoda	Putanja	Opis
GET	/api/a2a/status	A2A omogućen + statistika zadataka + keširani sažetak agent kartice
GET	/api/a2a/tasks	Popis zadataka — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset=
POST	/api/a2a/tasks	(Nije implementirano kao REST pomoćnik — kreirajte putem JSON-RPC message/send)
GET	/api/a2a/tasks/[id]	Dohvaćanje jednog zadatka
POST	/api/a2a/tasks/[id]/cancel	Otkazivanje zadatka

Autentifikacija: REST pomoćnici rade bez upravljačke autentifikacije (čitljivi putem nadzorne ploče); JSON-RPC ruta /a2a koristi Bearer OMNIROUTE_API_KEY ako je konfiguriran.

---

Cloud, Evals i Assess

Metoda	Putanja	Opis
POST	/api/cloud/auth	Provjerava Bearer ključ i vraća maskirane veze davatelja usluga + aliase modela za klijente cloud sinkronizacije
POST	/api/cloud/credentials/update	Ažuriranje enkriptiranih vjerodajnica za davatelja usluga sinkroniziranog s cloudom
POST	/api/cloud/model/resolve	Razrješavanje logičkog id-a modela u konkretnog davatelja usluga/model koristeći lokalnu tablicu rutiranja
GET	/api/cloud/models/alias	Popis aliasa modela izloženih cloud sinkronizaciji
GET	/api/assess	Čitanje najnovijih kategorizacija procjene (po davatelju usluga/modelu)
POST	/api/assess	Pokretanje procjene — tijelo: `{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	/api/evals	Popis ugrađenih eval paketa + najnovijih pokretanja
POST	/api/evals	Pokretanje eval izvršavanja
POST	/api/evals/suites	Kreiranje prilagođenog eval paketa — tijelo se validira pomoću evalSuiteSaveSchema
GET	/api/evals/suites/[id]	Dohvaćanje prilagođenog eval paketa

Autentifikacija: /api/cloud/auth izravno validira Bearer ključ; ostale rute /api/cloud/*, /api/evals/* i /api/assess zahtijevaju upravljačku sesiju/API ključ. /api/assess POST koristi validateBody s diskriminiranom unijom scope sheme.

---

Upravljanje ACP (Agent Client Protocol) protokolom

kao podprocesi (child processes). Ovi krajnji izvori (endpoints) upravljaju detekcijom ACP agenata i registracijom prilagođenih agenata.

Metoda	Putanja	Opis
GET	/api/acp/agents	Popis svih poznatih CLI agenata (ugrađenih + prilagođenih) sa statusom instalacije, verzijom, binarnom datotekom
POST	/api/acp/agents	Registrira prilagođeni ACP agent ili osvježava predmemoriju (cache) — tijelo zahtjeva: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} ili {action: "refresh"}
DELETE	/api/acp/agents	Uklanja prilagođeni ACP agent — parametar upita: ?id=<agentId>

Primjer odgovora (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
}

Autentifikacija: Zahtijeva upravljačku sesiju (kolačić auth_token iz nadzorne ploče) ili upravljački API ključ.

Pogledajte ACP Framework za sve pojedinosti.

---

Analitika i praćenje (Observability)

Krajnji izvori za analitiku u stvarnom vremenu za praćenje usmjeravanja, kompresije i raznolikosti pružatelja usluga. Oni pokreću stranice /dashboard/analytics/*.

Analitika automatskog usmjeravanja

Metoda	Putanja	Opis
GET	/api/analytics/auto-routing	Skupna statistika automatskog usmjeravanja: ukupan broj poziva, distribucija strategija, distribucija razina, top pružatelji usluga
GET	/api/analytics/auto-routing?days=7	Statistika po vremenskom prozoru (zadano 24h)

Primjer odgovora:

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

Analitika kompresije

Metoda	Putanja	Opis
GET	/api/analytics/compression	Skupna statistika kompresije: ušteđeni tokeni, postotak uštede, distribucija načina rada, korištenje motora

Primjer odgovora:

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

Praćenje raznolikosti pružatelja usluga

Metoda	Putanja	Opis
GET	/api/analytics/diversity	Praćenje raznolikosti temeljeno na Shannonovoj entropiji: sprječava jedinstvenu točku kvara mjerenjem rasprostranjenosti pružatelja usluga

Primjer odgovora:

{
  "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 čini 40% prometa — razmislite o diversifikaciji"]
}

Autentifikacija: Zahtijeva upravljačku sesiju ili upravljački API ključ.

---

Admin operacije

Endpointi dostupni samo administratorima za operativno upravljanje.

Metoda	Putanja	Opis
GET	/api/admin/concurrency	Čitanje trenutnih ograničenja konkurentnosti (globalno + po pružatelju usluge)
POST	/api/admin/concurrency	Ažuriranje ograničenja konkurentnosti — tijelo: {global?: number, perProvider?: Record<string, number>}

Autentikacija: Zahtijeva upravljačku sesiju s administratorskim opsegom.

---

Upravljanje CLI alatima

Upravljanje CLI alatima koji se integriraju s OmniRoute (antigravity, chipotle, commandCode, devin-cli, itd.). Pogledajte Referencu pružatelja usluga za potpuni popis.

Metoda	Putanja	Opis
GET	/api/cli-tools/all-statuses	Status svih CLI alata (instaliranost, verzija, zadnje viđen)
GET	/api/cli-tools/status	Detaljan status za jedan CLI alat (upit ?tool=)
POST	/api/cli-tools/apply	Zapisivanje generirane konfiguracije alata (dryRun prikazuje pregled; 422 + containerEphemeralTarget kada je kontejnerizirano; migration označava zastarjeli Codex YAML)
GET	/api/cli-tools/backups	Popis sigurnosnih kopija konfiguracije CLI alata
POST	/api/cli-tools/backups	Kreiranje sigurnosne kopije svih konfiguracija CLI alata
POST	/api/cli-tools/backups	Vraćanje: isti endpoint s {tool, backupId} u tijelu vraća tu sigurnosnu kopiju
GET	/api/cli-tools/antigravity-mitm	Status Antigravity MITM proxy-a (CLI alat "antigravity-mitm")
POST	/api/cli-tools/antigravity-mitm/alias	Konfiguracija aliasa za antigravity-mitm

Autentikacija: Zahtijeva upravljačku sesiju.

---

Agent Skills (Vještine agenta)

Upravljanje vještinama AI agenta (slično OpenAI-jevim prilagođenim GPT-ovima, ali za agente).

Metoda	Putanja	Opis
GET	/api/agent-skills	Popis svih vještina agenta (ugrađenih + prilagođenih)
GET	/api/agent-skills/[id]	Dohvat određene vještine agenta
POST	/api/agent-skills	Kreiranje prilagođene vještine agenta — tijelo: {name, description, prompt, model?, temperature?}
PUT	/api/agent-skills/[id]	Ažuriranje prilagođene vještine agenta
DELETE	/api/agent-skills/[id]	Brisanje prilagođene vještine agenta
GET	/api/agent-skills/[id]/raw	Dohvat sirovog prompta i metapodataka (bez izvršavanja)
POST	/api/agent-skills/generate	AI generiranje nove vještine na temelju opisa na prirodnom jeziku

Autentikacija: Zahtijeva upravljačku sesiju ili API ključ s upravljačkim opsegom.

---

Upravljanje predmemorijom

Upravljanje semantičkom predmemorijom i predmemorijom zaključivanja.

Metoda	Putanja	Opis
GET	/api/cache	Pregled predmemorije: ukupan broj zapisa, stopa pogodaka, veličina na disku
GET	/api/cache/entries	Popis zapisa u predmemoriji (s paginacijom)
DELETE	/api/cache/entries	Brisanje zapisa iz predmemorije (filtriranje putem query parametara)
GET	/api/cache/stats	Detaljna statistika predmemorije (po pružatelju usluga, po modelu)
GET	/api/cache/reasoning	Status predmemorije zaključivanja (za reprodukciju zaključivanja)
DELETE	/api/cache/reasoning	Brisanje predmemorije zaključivanja — query parametri: ?toolCallId=<id> (jedan) ili ?provider=<p> ili bez parametara (svi)

Autentifikacija: Zahtijeva upravljačku sesiju.

---

Sustav memorije

Upravljanje trajnom memorijom (FTS5 + vektorski embeddinzi).

Metoda	Putanja	Opis
GET	/api/memory	Popis zapisa memorije (filtriranje po opsegu, tipu, pojmu pretrage)
POST	/api/memory	Stvaranje novog zapisa memorije — tijelo: {scope, type, content, metadata?}
GET	/api/memory/[id]	Dohvat određenog zapisa memorije
PUT	/api/memory/[id]	Ažuriranje zapisa memorije
DELETE	/api/memory/[id]	Brisanje zapisa memorije
GET	/api/memory?q=	Pretraživanje memorije (FTS5 + vektorsko) — statistika je uključena u isti odgovor

Autentifikacija: Zahtijeva upravljačku sesiju ili API ključ s opsegom upravljanja.

---

Webhookovi

Upravljanje pretplatama na webhookove za događaje.

Metoda	Putanja	Opis
GET	/api/webhooks	Popis svih pretplata na webhookove
POST	/api/webhooks	Stvaranje pretplate na webhook — tijelo: {url, events[], secret?, active?}
GET	/api/webhooks/[id]	Dohvat određene pretplate na webhook
PUT	/api/webhooks/[id]	Ažuriranje pretplate na webhook
DELETE	/api/webhooks/[id]	Brisanje pretplate na webhook
GET	/api/webhooks/[id]/deliveries	Popis povijesti isporuka za webhook (zapisnik uspjeha/neuspjeha)
POST	/api/webhooks/[id]/test	Slanje testnog događaja na webhook

Autentifikacija: Zahtijeva upravljačku sesiju.

Za sve tipove događaja pogledajte Webhooks Framework.

---

Skills Framework

Upravljanje vještinama (Skills) (okvir za agentska proširenja).

Metoda	Putanja	Opis
GET	/api/skills	Prikaz svih instaliranih vještina (ugrađenih + prilagođenih)
POST	/api/skills/install	Instaliranje vještine iz lokalne putanje ili URL-a
DELETE	/api/skills/[id]	Deinstaliranje vještine
PUT	/api/skills/[id]	Omogućavanje ili onemogućavanje vještine — tijelo: {enabled?: boolean, mode?: "on" | "off" | "auto"}
POST	/api/skills/executions	Izvršavanje vještine — tijelo: {skillName, apiKeyId, input?, sessionId?}
GET	/api/skills/executions	Prikaz povijesti izvršavanja za sve vještine (filtriranje putem ?apiKeyId=)

Autentifikacija: Zahtijeva upravljačku (management) sesiju ili API ključ s upravljačkim opsegom.

Pogledajte Skills Framework za sve pojedinosti.

---

Plugins

Upravljanje OmniRoute dodacima (plugins) (proširenja trećih strana).

Metoda	Putanja	Opis
GET	/api/plugins	Prikaz instaliranih dodataka
POST	/api/plugins/marketplace/install	Instaliranje dodatka iz tržišta (marketplace)
DELETE	/api/plugins/[name]	Deinstaliranje dodatka
POST	/api/plugins/[name]/activate	Aktiviranje dodatka
POST	/api/plugins/[name]/deactivate	Deaktiviranje dodatka
GET	/api/plugins/[name]/config	Dohvat konfiguracije dodatka
PUT	/api/plugins/[name]/config	Ažuriranje konfiguracije dodatka

Autentifikacija: Zahtijeva upravljačku (management) sesiju.

Pogledajte Plugins Framework za sve pojedinosti.

---

Shadow Routing

Shadow / A-B usporedba pružatelja usluga nije samostalno REST sučelje — konfigurira se putem kombinirane rute (combo routing) (pogledajte Auto-Combo). Metrike usporedbe po kombinaciji poslužuje GET /api/combos/metrics.

---

Guardrails

Provjera zaštitnih mehanizama (guardrails) tijekom izvođenja (detekcija osobnih podataka (PII), detekcija ubacivanja upita (prompt injection), povezivanje vizualnog sadržaja). Zaštitni mehanizmi izvršavaju se za svaki zahtjev; odjava po pojedinom pozivu (opt-out) vrši se putem zaglavlja zahtjeva x-omniroute-disabled-guardrails — ne postoji trajno sučelje za omogućavanje/onemogućavanje.

Metoda	Putanja	Opis
GET	/api/guardrails	Prikaz registriranih zaštitnih mehanizama i njihovog statusa (naziv / omogućeno / prioritet)
POST	/api/guardrails/test	Probno pokretanje (dry-run) cjevovoda prije poziva na uzorku unosa — tijelo: {input, disabledGuardrails?}

Autentifikacija: Zahtijeva upravljačku (management) sesiju.

Pogledajte Security > Guardrails za sve pojedinosti.

---

---

Autentifikacija

Pogledajte Autentifikacija za upravljanje za informacije o četiri obitelji vjerodajnica (sesija nadzorne ploče, lokalni CLI token, oma_live_… pristupni token, API ključ s manage opsegom) i po čemu se razlikuju od inference ključeva.

• Rute nadzorne ploče (/dashboard/*) koriste auth_token kolačić
• Prijava koristi spremljeni hash lozinke; u protivnom se koristi INITIAL_PASSWORD
• requireLogin se može uključiti/isključiti putem /api/settings/require-login
• /v1/* rute po potrebi zahtijevaju Bearer API ključ kada je REQUIRE_API_KEY=true
• „management token” / „API ključ s manage opsegom” u ovoj referenci znači jedno od obitelji navedenih u tom vodiču — ne neku nedefiniranu dodatnu vrstu tajne

Promjena koja narušava kompatibilnost (v3.8.0) — /api/v1/agents/tasks/* i krajnje točke za upravljanje razdobljem čekanja (cooldown) sada zahtijevaju autentifikaciju za upravljanje (kolačić auth_token nadzorne ploče ili API ključ s manage opsegom). Klijenti koji su prije pozivali ove rute bez autentifikacije primit će 401 Unauthorized. Pogledajte commit 588a0333 (fix(auth): require management auth for agent and cooldown APIs).