# API Reference (Bosanski)

🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [ha](../../../ha/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇦🇲 [hy](../../../hy/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇳🇬 [ig](../../../ig/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇱 [pl](../../../pl/docs/reference/API_REFERENCE.md) · 🇵🇹 [pt](../../../pt/docs/reference/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/API_REFERENCE.md) · 🇷🇴 [ro](../../../ro/docs/reference/API_REFERENCE.md) · 🇷🇺 [ru](../../../ru/docs/reference/API_REFERENCE.md) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)

---

# API Referenca

🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [ha](../../../ha/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇦🇲 [hy](../../../hy/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇳🇬 [ig](../../../ig/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇱 [pl](../../../pl/docs/reference/API_REFERENCE.md) · 🇵🇹 [pt](../../../pt/docs/reference/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/API_REFERENCE.md) · 🇷🇴 [ro](../../../ro/docs/reference/API_REFERENCE.md) · 🇷🇺 [ru](../../../ru/docs/reference/API_REFERENCE.md) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)

Osnovna referenca za OmniRoute API. Obuhvata javni `/v1` interfejs i najčešće korištene endpoint-ove za upravljanje; mašinski čitljivi [`docs/openapi.yaml`](../openapi.yaml) i stablo ruta pod `src/app/api/` predstavljaju iscrpne izvore.

---

## Sadržaj

- [Dovršavanja razgovora](#chat-completions)
- [Ekskluzivni najmovi upravljanih sesija](#exclusive-managed-session-leases)
- [Ugradnje](#embeddings)
- [Generisanje slika](#image-generation)
- [OCR dokumenata](#document-ocr)
- [Lista modela](#list-models)
- [Manifest dodatka pružaoca usluga](#provider-plugin-manifest)
- [Krajnje tačke kompatibilnosti](#compatibility-endpoints)
- [API za datoteke](#files-api)
- [API za pakete](#batches-api)
- [API za pretraživanje](#search-api)
- [WebSocket prijenos](#websocket-streaming)
- [Izvještavanje o kvotama i problemima](#quotas--issues-reporting)
- [Semantička predmemorija](#semantic-cache)
- [Nadzorna ploča i upravljanje](#dashboard--management)
- [Upravljanje kombinacijama](#combo-management)
- [Webhookovi](#webhooks)
- [Registrovani ključevi (automatsko upravljanje)](#registered-keys-auto-management)
- [Protokol agenata](#agents-protocol)
- [Upravljački proxyji](#management-proxies)
- [Otpornost (prošireno)](#resilience-extended)
- [Vještine](#skills)
- [Memorija](#memory)
- [MCP server](#mcp-server)
- [A2A server](#a2a-server)
- [Oblak, evaluacije i procjena](#cloud-evals--assess)
- [Obrada zahtjeva](#request-processing)
- [Autentifikacija](#authentication)

---

## Chat Completions

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

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

### Custom Headers

| Header                   | Smjer    | Opis                                                                                                                                                                                                                         |
| ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-OmniRoute-No-Cache`   | Request  | Postavite na `true` za zaobilaženje keša                                                                                                                                                                                     |
| `x-omniroute-no-memory`  | Request  | Postavite na `true` za preskakanje injekcije memorije + vještina za ovaj zahtjev (ogledalo no-cache; izbjegava overhead tokena/troškova po pozivu)                                                                           |
| `X-OmniRoute-Progress`   | Request  | Postavite na `true` za događaje napretka                                                                                                                                                                                     |
| `X-Session-Id`           | Request  | Sticky session ključ za eksternu afinitet sesije                                                                                                                                                                             |
| `x_session_id`           | Request  | Varijanta s donjom crtom je također prihvaćena (direktan HTTP)                                                                                                                                                               |
| `X-OmniRoute-Session-Id` | Request  | Tag sesije/konverzacije koji dostavlja pozivaoc (također hrani memoriju). Kada je prisutan, zapisuje se doslovno u `call_logs.session_tag` za atribuciju troškova po sesiji (#8249) — nikada se ne sintetizira ako nedostaje |
| `Idempotency-Key`        | Request  | Ključ za deduplikaciju (prozor od 5s)                                                                                                                                                                                        |
| `X-Request-Id`           | Request  | Alternativni ključ za deduplikaciju                                                                                                                                                                                          |
| `X-OmniRoute-Cache`      | Response | `HIT` ili `MISS` (non-streaming)                                                                                                                                                                                             |
| `X-OmniRoute-Idempotent` | Response | `true` ako je deduplicirano                                                                                                                                                                                                  |
| `X-OmniRoute-Progress`   | Response | `enabled` ako je praćenje napretka uključeno                                                                                                                                                                                 |
| `X-OmniRoute-Session-Id` | Response | Efektivni session ID koji koristi OmniRoute                                                                                                                                                                                  |
| `X-OmniRoute-Request-Id` | Response | Korelacioni ID zahtjeva (kada je poznat)                                                                                                                                                                                     |
| `X-OmniRoute-Version`    | Response | Verzija OmniRoute build-a (uvijek prisutna)                                                                                                                                                                                  |
| `X-OmniRoute-Cost-Saved` | Response | USD iznos koji je keš izbjegao pri HIT-u (samo za cache hitove)                                                                                                                                                              |
| `X-OmniRoute-Decision`   | Response | Trag rutiranja: `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` je combo strategija, ili `single` za non-combo zahtjev) — uvijek prisutno u odgovorima na završetak                                            |

> Nginx napomena: ako se oslanjate na headere s donjom crtom (na primjer `x_session_id`), omogućite `underscores_in_headers on;`.

> **Zaglavlja za telemetriju troškova:** uspješni odgovori koji nisu streaming također nose `X-OmniRoute-*` set za telemetriju troškova — `X-OmniRoute-Response-Cost` (USD, fiksno 10 decimala; `0.0000000000` za besplatne/necijenjene), `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), plus `X-OmniRoute-Request-Id` i `X-OmniRoute-Version`. Ovi podaci se emituju kod chat completions, `/v1/responses`, `/v1/messages`, **i media endpointa** — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations`, i `/v1/moderations` (uvijek koštaju `0`). Trošak medija se računa po modalitetu (po slici, po sekundi, po karakteru, po jedinici pretrage) kada je cijena dostupna, u suprotnom je `0` (fail-open).

> **Semantika troškova pri cache-hit-u:** kod semantičkog cache HIT-a (`X-OmniRoute-Cache-Hit: true`) ne vrši se upstream poziv, tako da je `X-OmniRoute-Response-Cost` `0.0000000000` (**inkrementalni** trošak posluživanja hit-a). Originalni trošak (ili trošak koji bi nastao) prijavljuje se odvojeno u `X-OmniRoute-Cost-Saved`. Potrošači za naplatu trebali bi sumirati `X-OmniRoute-Response-Cost` (hit-ovi ne koštaju ništa); cache analitika može agregirati `X-OmniRoute-Cost-Saved`.

## Ekskluzivni zakupi upravljanih sesija

Ekskluzivni zakup upravljanih sesija predstavlja opcionalni ugovor o usmjeravanju, nezavisan od klijenta: jedan aktivni vlasnik
drži jednu odgovarajuću OmniRoute vezu. Njime se ne zakupljuje model, ne zahtijeva OAuth, ne identificira
određeni klijent niti se zahtijeva određeni pružalac usluga.

API ključ koji se koristi za autentifikaciju mora imati opseg `lease:exclusive` i eksplicitnu nepraznu
listu `allowedConnections`. Granica mutacije baze podataka zahtijeva oba polja zajedno prilikom
kreiranja ključa i djelimičnih ažuriranja.

```http
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 preuzimanje, obnavljanje i oslobađanje prikazuju vremenske oznake, `state` i tačnu pozitivnu
vrijednost `generation`, ali nikada odabranu vezu ili vjerodajnice. Za obnavljanje i oslobađanje
vrijednost generacije navodi se u JSON tijelu:

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

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

Aktivni vlasnik zakupa može eksplicitno zatražiti metapodatke za prikaz, sigurne po privatnost, za svoje trenutno povezivanje:

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

```json
{
  "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 opcionalna radnja statusa ograđena je neprozirnim identifikatorom vlasnika, autentificiranim upravljanim API ključem i tačnom
aktivnom generacijom unutar jedne transakcije baze podataka. `displayName` je samo skraćeni konfigurirani
naziv veze; ima vrijednost `null` kada ne postoji siguran konfigurirani naziv. OmniRoute ga nikada ne zamjenjuje
adresom e-pošte ili generiranim identitetom računa. Vrijednost pružaoca usluga predstavlja neosjetljivu oznaku za prikaz i nikada
nije generirani identifikator kompatibilnog pružaoca usluga. Vjerodajnice, tokeni, kolačići, sirovi ID-jevi veza ili API
ključeva, sažeci vlasnika, tajne za ograđivanje i interni podaci usmjeravanja nisu uključeni.

Pretrage s pogrešnim ključem, pogrešnim vlasnikom, zastarjelom generacijom, kao i nedostajuće, istekle, oslobođene i poništene pretrage,
sve vraćaju istu grešku `409 LEASE_FENCE_STALE` bez metapodataka veze. Klijent koji je primio odgovor o čekanju na kapacitet nema aktivno povezivanje koje bi mogao provjeriti. Kada usmjeravanje promijeni aktivni zakup,
ista generacija ostaje važeća, a status atomski vraća novo povezivanje, nikada staro.
Postojeći klijenti ostaju nepromijenjeni jer odgovori za preuzimanje, obnavljanje, oslobađanje i čekanje zadržavaju
svoje prethodne oblike.

Ovaj ugovor servera ne mijenja standardni OpenAI Codex `/status`. Standardni Codex trenutno prijavljuje svog
pružaoca modela i ugrađeno stanje autentifikacije/računa, ali ne prikazuje proizvoljne prilagođene
metapodatke računa pružaoca usluga; buduća integracija klijenta mora pozvati ovu radnju i odlučiti kako
prikazati `connection.displayName`.

Svaki upravljani zahtjev za zaključivanje zatim šalje oba kontrolna zaglavlja:

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

Tačni vlasnik, generacija, aktivna veza i autentificirani API ključ ograđuju se neposredno
prije svakog podržanog pokušaja prema uzvodnom sistemu. Ponovno korištenje vlasnika i generacije s drugim ključem neće uspjeti čak
ni kada taj ključ dozvoljava istu vezu. Sirovi identifikatori vlasnika ne pohranjuju se trajno, ne zapisuju u dnevnike, ne zadržavaju u
snimku zahtjeva niti prosljeđuju uzvodno.

Privremeno zauzeće vraća HTTP `429` sa zaglavljem `Retry-After` i sljedećim sadržajem:

```json
{
  "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 obični skup odgovarajućih veza nije bio prazan i da je svaki slobodni kandidat
bio zauzet stranim aktivnim zakupom. Nepodržani modeli/pružaoci usluga, nepodudaranje pravila, period hlađenja, kvota,
zdravstveno stanje i drugi uobičajeni neuspjesi provjere podobnosti zadržavaju svoje postojeće OmniRoute odgovore.

### `x-omniroute-compression`

Promjena plana kompresije za pojedinačni zahtjev. Ima najviši prioritet — nadjačava
promjenu kombinacije usmjeravanja, aktivni profil, automatsko aktiviranje i opciju Default na panelu. Vrijednosti:

| Vrijednost    | Efekat                                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------------ |
| `off`         | Bez kompresije za ovaj zahtjev.                                                                              |
| `default`     | Profil Default izveden iz panela (ignorira aktivni profil). Motori s gubicima ostaju isključeni.             |
| `safe`        | Samo deduplikacija i sažimanje razmaka.                                                                      |
| `allow-lossy` | Zadržava plan operatera za ovaj zahtjev, uključujući sažetke i preoblikovanje stila.                         |
| `engine:<id>` | Jedan motor kada je omogućen, npr. `engine:rtk`. Opcionalno uključivanje tog motora za pojedinačni zahtjev.  |
| `<combo>`     | Imenovana kombinacija, prvo podudarana prema nazivu (bez obzira na velika i mala slova), a zatim prema ID-u. |

Napomene:

- Nepoznate vrijednosti se ignoriraju (zahtjev se nikada ne odbija); razrješavanje se nastavlja prema uobičajenom prioritetu operatera.
- Ako više kombinacija dijeli isti naziv, navedite **id** kombinacije radi determinističkog podudaranja.
- Kombinacija čiji je naziv `off` ili `default` ne može se odabrati prema nazivu (te ključne riječi tumače se prve); referencirajte takvu kombinaciju pomoću njenog ID-a.
- Glavni prekidač kompresije predstavlja čvrstu granicu: kada je kompresija globalno onemogućena, ovo zaglavlje je ne može omogućiti.

Primijenjeni plan vraća se u zaglavlju odgovora:

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

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

---

## Embeddings

```bash
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.

Kataloški ID-ovi su u formatu `provider/model` (primjer: `jina-ai/jina-embeddings-v5-omni-small`). Također se razrješavaju i obični Jina model ID-ovi koji se pojavljuju u registru (na primjer `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`). Jina embed/rerank/classify/segment prvo koriste dashboard `jina-ai` vjerodajnice; `JINA_AI_API_KEY` služi kao rezervna opcija samo kada dashboard ključ ne postoji. Kartica `jina-reader` je isključivo Reader / `r.jina.ai` (`POST /v1/web/fetch`) i nikada ne služi za embeddings ili rerank.

Modeli u registru koji najavljuju multimodalnu podršku također prihvataju do 32 strukturiranih stavki neutralnih prema provajderu. Tipovi 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 alias porodice `jina-ai/jina-embeddings-v5-omni` → omni-small) također prihvata Jina-ove izvorne EmbeddingsV5Request dokumente i **prosljeđuje ih netaknute** na `https://api.jina.ai/v1/embeddings`:

```json
{
  "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 }` vrijednosti mogu biti javni HTTPS URL, `data:` URI ili raw base64. OmniRoute ne pretvara te objekte u stringove niti preuzima izvorne URL-ove slika — Jina sama preuzima javne medije. Dodatna Jina polja (`task`, `normalized`, `truncate`, `embedding_type`) se prosljeđuju. Jina SKU-ovi koji podržavaju samo tekst i dalje odbijaju netekstualne dokumente.

Sigurnosna i transportna ograničenja:

- Remote medijski URL-ovi moraju biti javni HTTPS. Kanoničke `{type,source:url}` stavke preuzimaju se na strani servera (revalidacija preusmjeravanja, timeout, ograničenja veličine, javni DNS, connection pinning) i ubacuju inline prije poziva provajdera. Jina-izvorne `{image:"https://..."}` stavke prosljeđuju se onako kako jesu nakon iste provjere javnog HTTPS-a; Jina zatim preuzima URL.
- Inline base64 mediji su ograničeni na 8 MiB dekodiranih po stavci i 16 MiB dekodiranih po zahtjevu.

Translacija provajdera (kanoničke stavke se nikada ne prosljeđuju nepromijenjene):

- Jina multimodalni modeli: svaka stavka na vrhovnom nivou 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 vrhovnom nivou.
- Gemini Embedding 2 porodica: jedan niz na vrhovnom nivou postaje jedan izvorni `models/{model}:embedContent` zahtjev sa `content.parts` (`text` ili `inline_data`).
- Nepoznati/dinamički modeli bez eksplicitnih metapodataka o modalitetu odbijaju strukturirani unos sa HTTP 400 greškom.

```json
{
  "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 prilagođavanja stavke. Polja proširenja koja nisu dio inputa u zastarjelim zahtjevima za stringove/tokene nastavljaju prolaziti nepromijenjeno.

```bash
# Listaj sve embedding modele
GET /v1/embeddings
```

---

## Generisanje slika

```bash
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 provajderi: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (lokalno), ComfyUI (lokalno).

```bash
# Izlistaj sve modele za slike
GET /v1/images/generations
```

---

## OCR dokumenata

```bash
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` bira OCR provajdera putem `provider/model` prefiksa; običan model id (npr. `mistral-ocr-latest`) razrješava se na njegov registrovani provajder, a izostavljeni `model` po defaultu koristi Mistral (`mistral-ocr-latest`). Registrovani provajderi (`open-sse/config/ocrRegistry.ts`):

| Provider id                   | Model id             | `model` vrijednost                                             | Napomene                                                                                         |
| ----------------------------- | -------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `mistral`                     | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (ili običan `mistral-ocr-latest`) | Sinhrono — odgovor se vraća direktno iz jednog upstream poziva.                                  |
| `azure-document-intelligence` | `prebuilt-read`      | `azure-document-intelligence/prebuilt-read`                    | Asinhroni upstream (`analyze` + poll) — vidi ispod.                                              |
| `vertex-deepseek-ocr`         | `deepseek-ocr-maas`  | `vertex-deepseek-ocr/deepseek-ocr-maas`                        | Sinhrono, putem Vertex AI `openapi/chat/completions` partner endpointa — vidi ispod za auth/URL. |

Sva tri provajdera odgovaraju u istom Mistral-obliku tijela (body):

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

### Azure Document Intelligence poll tok

Azure Document Intelligence `analyze` API je asinhron: početni zahtjev vraća `Operation-Location` zaglavlje umjesto tijela, i rezultat se mora provjeravati (poll). Handler (`open-sse/handlers/ocr.ts`) provjerava taj URL svake sekunde do 30 pokušaja, brzo prekida (ne nastavlja provjeru) pri non-`ok` odgovoru ili `"failed"` statusu, i vraća `504` ako operacija još uvijek traje nakon što je budžet pokušaja iscrpljen. Finalni Azure odgovor se normalizuje u isti `pages`/`markdown` oblik koji koristi Mistral prije nego što se vrati pozivaocu, tako da klijentski kod ne mora posebno tretirati provajdera.

### Vertex AI DeepSeek OCR auth i razrješavanje endpointa

`vertex-deepseek-ocr` ponovo koristi istu Vertex AI autentifikaciju koju OmniRoute već podržava za chat/image saobraćaj (`open-sse/executors/vertex.ts`): API ključ konekcije je ili Service Account JSON kredencijal (zamijenjen za kratkotrajni OAuth access token putem JWT-bearer toka) ili već generisani OAuth access token koji se koristi direktno. Upstream endpoint URL je generički Vertex `openapi/chat/completions` partner endpoint, izgrađen iz projekta i regije konekcije — eksplicitni `providerSpecificData.project`/`providerSpecificData.region` uvijek imaju prioritet; u suprotnom se projekat izvodi iz `project_id` iz Service Account JSON-a, a regija je po defaultu `us-central1`. Oba razrješavanja se dešavaju u `open-sse/handlers/ocr.ts` (`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`), a konzumira ih `src/app/api/v1/ocr/route.ts` prije slanja na `handleOcr`.

---

## Lista modela

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

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

### Prefiksi model id-a (`?prefix=`)

Većina modela je oglašena pod **prefiksom provajdera**. Koji prefiks dobijate kontroliše
`MODELS_CATALOG_PREFIX_MODE` feature flag, a može se nadjačati **po zahtjevu** pomoću
query parametra — korisno za klijenta koji želi čistu listu bez mijenjanja postavke na nivou cijelog servera za sve ostale:

```bash
GET /v1/models?prefix=alias        # jedan id po modelu — kratki alias prefiks
GET /v1/models?prefix=dual         # oba oblika (server default)
GET /v1/models?prefix=canonical    # samo puni provider-id prefiks
```

| Mode        | Emituje                                                 | Napomene                                                                                                                                                                                  |
| ----------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual`      | `cc/claude-sonnet-4-6` **i** `claude/claude-sonnet-4-6` | **Default.** Oba id-a rutiraju ka istom modelu; zadržano kako bi klijentske konfiguracije koje su hardkodirale bilo koji od oblika nastavile raditi. Otprilike udvostručuje katalog.      |
| `alias`     | `cc/claude-sonnet-4-6`                                  | Jedan unos po modelu. Provajderi bez posebnog aliasa i dalje emituju svoj unos, tako da ništa nije izgubljeno.                                                                            |
| `canonical` | `claude/claude-sonnet-4-6`                              | Jedan unos po modelu pod punim provider-id prefiksom. Provajderi bez posebnog aliasa (npr. `antigravity/…`, `agy/…`) ovdje također emituju svoj jedini id, tako da ništa nije izgubljeno. |

`dual`-mode ogledalo se također može prepoznati bez query parametra: ono nosi `parent`
polje koje pokazuje na primarni id.

Klijenti koji renderuju birač modela trebali bi zahtijevati `?prefix=alias` — to je ono što
[OmniCopilot VS Code ekstenzija](../guides/VSCODE-COPILOT.md) radi.

### No-thinking varijante modela

Za Claude modele sa sposobnošću razmišljanja (thinking), `/v1/models` također oglašava **no-thinking** varijantu čiji je id prefiksiran sa `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 nazad na pravi `<provider>/<model>` sa suzbijenim razmišljanjem — `thinking:{type:"disabled"}` na `/v1/messages` putanji, ili uklonjenim `reasoning`/`reasoning_effort` poljima na `/v1/chat/completions` putanji. Varijanta je navedena samo za modele iz Claude porodice koji podržavaju razmišljanje **i** poštuju `disabled` (tako su npr. isključeni adaptive-only modeli koji odbijaju `disabled`). Operateri mogu prisilno uključiti ili isključiti varijantu po modelu putem `ModelSpec.noThinkingAlias`.

---

## Manifest provider plugin-a

```bash
GET /api/v1/provider-plugin-manifest
```

Vraća JSON-safe manifest provider plugin-a koji koriste Bifrost, CLIProxyAPI i budući sidecar ruteri. Odgovor se generiše iz TypeScript registry-ja providera i namjerno isključuje OAuth tajne klijenta, rezoluciju runtime okruženja, funkcije izvršavaca (executor functions), zaglavlja zahtjeva i podatke o računima.

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

---

## Kompatibilne krajnje tačke

| Metoda | Putanja                                   | Format                             |
| ------ | ----------------------------------------- | ---------------------------------- |
| POST   | `/v1/chat/completions`                    | OpenAI                             |
| POST   | `/v1/messages`                            | Anthropic                          |
| POST   | `/v1/responses`                           | OpenAI Odgovori                    |
| POST   | `/v1/embeddings`                          | OpenAI                             |
| POST   | `/v1/images/generations`                  | OpenAI Slike                       |
| POST   | `/v1/images/edits`                        | OpenAI Slike (uređivanje/inpaint)  |
| POST   | `/v1/videos/generations`                  | Generisanje videa 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 tijelo)    |
| POST   | `/v1/rerank`                              | Cohere/Voyage-stil rerank          |
| POST   | `/v1/classify`                            | Jina classify (`api.jina.ai`)      |
| POST   | `/v1/segment`                             | Jina segmenter (`segment.jina.ai`) |
| POST   | `/v1/moderations`                         | OpenAI Moderacije                  |
| 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 modeli alias                |
| POST   | `/api/v1/vscode/{token}/chat/completions` | OpenAI tokenizovani alias          |
| POST   | `/api/v1/vscode/{token}/responses`        | OpenAI Odgovori tokenizovani alias |
| POST   | `/api/v1/vscode/{token}/api/chat`         | Ollama tokenizovani alias          |
| GET    | `/api/v1/vscode/{token}/api/tags`         | Ollama tagovi tokenizovani alias   |

Sve POST rute prate isti oblik: `Bearer your-api-key` + Zod-validirano JSON tijelo (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema`, itd., pogledajte `src/shared/validation/schemas.ts`). 4xx se vraća u slučaju neuspjeha sheme.

Za klijente koji ne mogu priložiti `Authorization: Bearer ...`, OmniRoute također prihvata API ključeve u URL-u putem kompatibilnosti sa upitnim nizom (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) ili putem namjenskih `/api/v1/vscode/{token}/...` krajnjih tačaka dokumentovanih ispod.

```bash
# Rerank (provajder cloud registra, ili čvor provajdera kompatibilan sa OpenAI kao "<prefix>/<model>")
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Jina classify (akreditivi Foundation API-ja)
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; alias 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) tijelo
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

# Generisanje videa / muzike (ID modela sa prefiksom provajdera)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "kie/suno-v4.0",   "prompt": "..." }
```

> **Čvorovi provajdera za rerank:** `POST /v1/rerank` također rutira na čvorove provajdera kompatibilne sa OpenAI
> (oMLX, vLLM, Infinity, TEI iza gatewaya, …) adresirane kao `<node-prefix>/<model>`. Loopback
> čvorovi (`localhost`, `127.0.0.1`, `172.16.0.0/12`) su uvijek prihvatljivi. Čvorovi na bilo kojem drugom
> hostu — LAN kutija ili Tailscale peer — su prihvatljivi samo kada operater omogući
> `RERANK_REMOTE_PROVIDER_NODES` zastavicu funkcije **i** osnovni URL čvora prođe politiku
> odlaznog URL-a provajdera (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`);
> hostovi sa cloud-metapodacima nikada se ne rutiraju. Korak rerank-a memorijskog mehanizma poziva ovu rutu preko
> loopback-a, tako da isto pravilo upravlja `rerankProviderModel` u postavkama memorije.
>
> **Oblici lokalnog servera:** čvor se poziva na `<base>/v1/rerank` i, na 404, na `<base>/rerank`
> (Infinity, TEI). Uzvodno tijelo nosi i Cohere/OpenAI pravopis (`documents`,
> `return_documents`) i TEI pravopis (`texts`, `return_text`), a uzvodni odgovor je
> normalizovan na Cohere omotnicu: TEI-jev goli `[{index, score, text}]`, `{results: [{index, score}]}`
> iz tankih gatewaya, i Voyage-stil `{data: [...]}` sve se vraća klijentu kao
> `{results: [{index, relevance_score, document?}]}`, sortirano po rezultatu i ograničeno na `top_n`.

> **Otkrivanje čvorova provajdera:** modeli na čvoru provajdera kompatibilnom sa OpenAI pojavljuju se u `GET /v1/models`
> pod prefiksom čvora. Redovi koji ne nose metapodatke krajnje tačke (tipično za lokalne `/v1/models` liste)
> nasljeđuju `apiType` čvora, tako da su modeli `embeddings` čvora `type: "embedding"` i
> modeli `rerank` čvora su `type: "rerank"` umjesto da se podrazumijevaju na chat; eksplicitni
> `supportedEndpoints` na sinhronizovanom ili ručno dodanom redu i dalje ima prednost.

### Namjenske rute provajdera

```bash
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-kompatibilni endpoint za datoteke za batch ulaz/izlaz i upload datoteka s određenom svrhom.

| Metoda | Putanja                  | Opis                                                                                                            |
| ------ | ------------------------ | --------------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/files`              | Upload datoteke (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — max 512 MiB |
| GET    | `/v1/files`              | Lista datoteka za autentifikovani API ključ                                                                     |
| GET    | `/v1/files/[id]`         | Preuzimanje metapodataka datoteke                                                                               |
| DELETE | `/v1/files/[id]`         | Brisanje datoteke                                                                                               |
| GET    | `/v1/files/[id]/content` | Stream sirovog tijela datoteke nazad                                                                            |

**Auth:** Bearer API ključ — datoteke su ograničene po API ključu putem `getApiKeyRequestScope`. Ključ
vidi, preuzima i briše samo svoje datoteke; sesija dashboarda bez ključa čita
cijelu instancu; datoteka bez vlasnika (anonimni upload ili upload putem dashboard sesije) je zabranjena za svakog
pozivaoca koji nije u sesiji. `GET /v1/files` odbija anonimnog pozivaoca — kao i predstavljeni ključ koji
nije validan — sa `401` čak i kada je `REQUIRE_API_KEY=false`, umjesto listanja datoteka svakog tenanta (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

## Batches API

OpenAI-kompatibilna batch obrada.

| Metoda | Putanja                   | Opis                                                                                                             |
| ------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/batches`             | Kreiraj batch — tijelo validirano putem `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) |
| GET    | `/v1/batches`             | Lista batch-eva                                                                                                  |
| GET    | `/v1/batches/[id]`        | Preuzimanje statusa batch-a + `request_counts`                                                                   |
| DELETE | `/v1/batches/[id]`        | Brisanje završenog/neuspjelih batch-a                                                                            |
| POST   | `/v1/batches/[id]/cancel` | Otkazivanje batch-a koji je u toku                                                                               |

**Auth:** Bearer API ključ. Batch-evi su ograničeni po API ključu prema istom trostrukom pravilu kao
i datoteke: samo vlastiti ključ, dashboard sesija na nivou instance, zapisi bez vlasnika zabranjeni za svakog
pozivaoca koji nije u sesiji (preuzimanje, brisanje, otkazivanje i provjera `input_file_id` prilikom kreiranja).
`GET /v1/batches` odbija anonimnog pozivaoca sa `401` čak i kada je `REQUIRE_API_KEY=false`.

---

## Search API

Apstrakcija web/search provajdera (Tavily, Brave, Exa, Serper, itd.).

| Metoda | Putanja                | Opis                                                                                            |
| ------ | ---------------------- | ----------------------------------------------------------------------------------------------- |
| GET    | `/v1/search`           | Lista konfigurisanih search provajdera + mogućnosti                                             |
| POST   | `/v1/search`           | Pokretanje search upita — tijelo validirano putem `v1SearchSchema`, podržava caching/coalescing |
| GET    | `/v1/search/analytics` | Statistika hitova/latencije/cache-a po provajderu                                               |

**Auth:** Bearer API ključ (`extractApiKey` + `isValidApiKey`). Search polisa se primjenjuje putem `enforceApiKeyPolicy`.

---

## Web Fetch API

Ekstrakcija sadržaja sa URL-a putem konfigurisanog web-fetch provajdera (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

| Metoda | Putanja         | Opis                                                            |
| ------ | --------------- | --------------------------------------------------------------- |
| POST   | `/v1/web/fetch` | Fetch/scrape URL-a — tijelo validirano putem `v1WebFetchSchema` |

**Auth:** Bearer API ključ (`extractApiKey` + `isValidApiKey`). Polisa se primjenjuje putem `enforceApiKeyPolicy`.

**Fallback svjestan kvote (#8297):** kada nije naveden eksplicitni `provider`, pool (`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) se prolazi u fiksnom redoslijedu prioriteta (fill-first) — provajder koji je rate-limited ali konfigurisan se preskače umjesto prekida zahtjeva, a retryable/quota upstream greška (uvijek HTTP 429; 402/403 za Firecrawl/Tavily/TinyFish besplatne nivoe kvote — ne za Jina Reader, i nikada za običan 400 bad request) prelazi na sljedećeg neisprobanog provajdera s kredencijalima u trenutku zahtjeva. Kada je svaki provajder u pool-u iscrpljen, endpoint vraća jedan `429` (sa `Retry-After` zaglavljem) umjesto prethodnog generičkog `400`. Kada se zahtijeva eksplicitni `provider`, **nema** tihog fallback-a — rate-limited ili neuspješan eksplicitni provajder prikazuje vlastitu grešku (`429` ako je rate-limited, inače upstream status).

---

## WebSocket Streaming

```bash
GET /v1/ws?handshake=1
```

Validira WebSocket upgrade handshake i vraća primjere poruka wire protokola (`request`, `cancel`). Stvarni WS frame-ovi se obrađuju putem ugrađenog WS servera izvan Next.js tabele ruta.

**Auth:** Bearer API ključ tokom handshake-a.

### Responses API preko WebSocket-a (samo codex)

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

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

Responses-API-preko-WebSocket proxy je povezan **isključivo na `codex`** (ChatGPT backend). Sluša na istom portu kao API/dashboard na putanjama `/v1/responses`, `/responses` i `/api/v1/responses`. Na prvom `response.create` frame-u vrši autentifikaciju + pripremu putem internog `codex-responses-ws` bridge-a, odabire codex OAuth konekciju i tunelira na `wss://chatgpt.com/backend-api/codex/responses` putem `wreq-js` transporta. **Non-codex modeli su odbijeni** (`codex_ws_provider_required`). Za quota-share rutiranje 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`.

**Auth:** Bearer API ključ tokom handshake-a. Ugrađeni HTTP server (`server-ws.mjs`) mora biti aktivna ulazna tačka (što jeste, po defaultu, kada `app/server-ws.mjs` postoji).

#### Model id: koristite čisti ChatGPT id (bez `codex/` prefiksa)

OpenAI **Codex CLI** validira naziv modela na strani klijenta kada je `supports_websockets = true` i **odbija id-ove s prefiksom provajdera** kao što je `codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account`). Pošaljite **čisti** id (npr. `gpt-5.5`). OmniRoute-ov bridge je samo za codex, tako da ponovo razršava čisti id kao codex model (`resolveCodexWsModelInfo`) prije tuneliranja upstream — iako bi čisti `gpt-5.5` inače bio rutiran drugom provajderu preko HTTP-a.

#### Konfigurisanje OpenAI Codex CLI-ja

Usmjerite Codex CLI na OmniRoute dodavanjem custom provajdera s WebSocket podrškom u `~/.codex/config.toml` (koristite zaseban `CODEX_HOME` kako ne biste dirali postojeću konfiguraciju):

```toml
model = "gpt-5.5"                 # čisti id — NE "codex/gpt-5.5"
model_provider = "omniroute"

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

```bash
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, a OmniRoute ga tunelira na odabranu codex OAuth konekciju. Validirano end-to-end protiv lokalnog servera: ChatGPT vraća `codex.rate_limits` + `response.created` i stream-uje dopunu.

---

## Kvote i prijavljivanje problema

| Metoda | Putanja             | Opis                                                                                       |
| ------ | ------------------- | ------------------------------------------------------------------------------------------ |
| GET    | `/v1/quotas/check`  | Pre-validacija kvote za `provider` + `accountId` prije izdavanja registrovanog ključa      |
| POST   | `/v1/issues/report` | Prijavi neuspjeh izdavanja kvote/ključa na GitHub (zahtijeva `GITHUB_ISSUES_REPO` + token) |

**Auth:** Bearer API ključ (`isAuthenticated`).

---

## Samouslužno korištenje (`/api/usage/om-usage`)

Bilo koji API ključ može čitati **sopstveno** korištenje i kvote — bez administratorske autorizacije. Ovo je endpoint koji klijent (CLI, OmniCopilot panel) koristi kako bi vlasniku ključa prikazao potrošnju.

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

# Strukturirani oblik — ono što koristi UI
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"
```

Ključ mora imati omogućenu opciju **`allowUsageCommand`** (isključeno po defaultu — API-key manager u dashboardu je prebacuje po ključu). Bez toga, endpoint odgovara sa `403`.

`?format=json` vraća diskriminiran oblik tako da pozivač nikada ne čita polje podataka iz odbijenog zahtjeva. U slučaju uspjeha:

```jsonc
{
  "allowed": true,
  // prisutno samo kada je ključ odabrao limite korištenja po ključu (dnevni/nedeljni USD):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // snapshot kvote odabranog providera, ili null kada još ništa nije keširano:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // snapshot svake konekcije, tako da UI može renderovati više providera jednovremeno:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}
```

U slučaju odbijanja (`401` neispravan ključ / `403` nije dozvoljeno), ista ruta vraća `{ "allowed": false, "error": { "message": "…" } }` — prisutni ali prazni `personal`/`provider` (ključ je dozvoljen, ali podaci još nisu naučeni) predstavljaju različito stanje od odbijanja, a samo JSON oblik ih razlikuje.

**Auth:** Bearer API ključ samog pozivača, validiran pomoću `isValidApiKey` — ovo _nije_ administratorski interfejs (`/api/keys/…`), koji ostaje zaštićen pomoću `requireManagementAuth`.

---

## Semantički Cache

```bash
# Preuzmi statistiku keša
GET /api/cache/stats

# Obriši sve keševe
DELETE /api/cache/stats
```

Primjer odgovora:

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

### Uticaj na latenciju

Semantički cache HIT služi odgovor iz keša **bez poziva prema upstream serveru**, tako da je prijavljeni `X-OmniRoute-Response-Latency` blizu nule (bez obzira na originalnu upstream latenciju). Klijenti osjetljivi na latenciju (benchmarking, p50/p99 monitoring) trebali bi provjeriti `X-OmniRoute-Cache-Latency` response header:

| Vrijednost  | Značenje                                                          |
| ----------- | ----------------------------------------------------------------- |
| `synthetic` | Odgovor poslužen iz keša; latencija nije stvarno upstream vrijeme |
| _(odsutno)_ | Odgovor iz stvarnog upstream poziva                               |

### Zaobilazak keša po ključu

API ključevi mogu isključiti čitanje iz semantičkog keša putem `cacheDefaultMode`:

| Vrijednost | Ponašanje                                              |
| ---------- | ------------------------------------------------------ |
| `legacy`   | Normalno ponašanje keša (default)                      |
| `bypass`   | Potpuno preskoči pretragu keša; uvijek idi na upstream |

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

```json
{ "cacheDefaultMode": "bypass" }
```

### Zaobilazak po zahtjevu

Bilo koji zahtjev može zaobići keš bez obzira na postavke ključa:

```
X-OmniRoute-No-Cache: true
```

---

## Dashboard i upravljanje

Rute za upravljanje (`/api/*` osim javnog auth/login-a) **nisu** autorizovane putem običnih API ključeva za inferenciju. Porodice kredencijala, opsezi (scopes) i curl primjeri: [Management Authentication](../guides/MANAGEMENT-AUTH.md).

### Autentifikacija

| Endpoint                      | Metoda  | Opis                             |
| ----------------------------- | ------- | -------------------------------- |
| `/api/auth/login`             | POST    | Prijava                          |
| `/api/auth/logout`            | POST    | Odjava                           |
| `/api/settings/require-login` | GET/PUT | Prebacivanje zahtjeva za prijavu |

### Upravljanje provajderima

| Endpoint                     | Metoda                | Opis                                                                                                               |
| ---------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `/api/providers`             | GET/POST              | Lista / kreiranje provajdera                                                                                       |
| `/api/providers/[id]`        | GET/PUT/DELETE        | Upravljanje provajderom                                                                                            |
| `/api/providers/[id]/test`   | POST                  | Testiranje konekcije provajdera                                                                                    |
| `/api/providers/[id]/models` | GET                   | Lista 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                  | Import heterogene LISTE provajdera iz parsirane CSV/JSON datoteke (#6836); rezultati djelimičnog neuspjeha po redu |
| `/api/provider-nodes*`       | Razne                 | Upravljanje čvorovima provajdera                                                                                   |
| `/api/provider-models`       | GET/POST/PATCH/DELETE | Prilagođeni modeli (dodaj, ažuriraj, sakrij/prikaži, obriši)                                                       |

### OAuth tokovi

| Endpoint                         | Metoda | Opis                       |
| -------------------------------- | ------ | -------------------------- |
| `/api/oauth/[provider]/[action]` | Razne  | Provajder-specifični OAuth |

### Rutiranje i konfiguracija

| Endpoint              | Metoda   | Opis                            |
| --------------------- | -------- | ------------------------------- |
| `/api/models/alias`   | GET/POST | Aliasi modela                   |
| `/api/models/catalog` | GET      | Svi modeli po provajderu + tipu |
| `/api/combos*`        | Razne    | Upravljanje kombinacijama       |
| `/api/keys*`          | Razne    | Upravljanje API ključevima      |
| `/api/pricing`        | GET      | Cjenovnik modela                |

### Upotreba i analitika

| Endpoint                         | Method          | Opis                                                                                                                                                                                                                                                                                                                     |
| -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/usage/history`             | GET             | Historija korištenja                                                                                                                                                                                                                                                                                                     |
| `/api/usage/logs`                | GET             | Logovi korištenja                                                                                                                                                                                                                                                                                                        |
| `/api/usage/request-logs`        | GET             | Logovi na nivou zahtjeva                                                                                                                                                                                                                                                                                                 |
| `/api/usage/[connectionId]`      | GET             | Korištenje po konekciji                                                                                                                                                                                                                                                                                                  |
| `/api/usage/token-limits`        | GET/POST/DELETE | Budžeti limita tokena po API-ključu                                                                                                                                                                                                                                                                                      |
| `/api/usage/model-latency-stats` | GET             | Kolozno agregirano kašnjenje po provajderu/modelu (avg/p50/p95/p99, stopa uspjeha); filteri: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873)                                                                                                                                                             |
| `/api/usage/cache-health`        | GET             | Sažetak zdravlja prompt-keša preko `call_logs` — omjer pisanja/čitanja, distribucija veličine pisanja p50/p90/p99, koncentracija intenzivnog pisanja, podjela po modelu i presuda `healthy`/`degraded`/`thrash`/`no-data`; parametri upita `range` (`1h`\|`24h`\|`7d`\|`30d`, zadano `24h`) i opcionalni `model` (#8827) |

### Postavke

| Endpoint                              | Method        | Opis                                                                                                                                                                                                      |
| ------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings`                       | GET/PUT/PATCH | Opšte postavke                                                                                                                                                                                            |
| `/api/settings/proxy`                 | GET/PUT       | Konfiguracija mrežnog proxy-ja                                                                                                                                                                            |
| `/api/settings/proxy/test`            | POST          | Testiraj proxy konekciju                                                                                                                                                                                  |
| `/api/settings/ip-filter`             | GET/PUT       | IP lista dozvoljenih/blokiranih adresa                                                                                                                                                                    |
| `/api/settings/thinking-budget`       | GET/PUT       | Režim ponovnog pisanja **zahtjeva** za razmišljanje/zaključivanje (passthrough / auto-strip / custom / adaptive). Nezavisno od kompresije. Pogledajte [THINKING_BUDGET.md](../guides/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          | Obriši redove logova zahtjeva i lokalne call-log artefakte                                                                                                                                                |

### Kontekst i kompresija

| Endpoint                               | Method         | Opis                                                                                                    |
| -------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------- |
| `/api/compression/preview`             | POST           | Pregled off/lite/standard/aggressive/ultra/RTK/stacked kompresije                                       |
| `/api/compression/language-packs`      | GET            | Lista dostupnih Caveman jezičkih paketa                                                                 |
| `/api/compression/rules`               | GET            | Lista metapodataka Caveman pravila                                                                      |
| `/api/context/caveman/config`          | GET/PUT        | Alias za specifična Caveman podešavanja                                                                 |
| `/api/context/rtk/config`              | GET/PUT        | Specifična RTK podešavanja, uključujući prilagođene filtere i zadržavanje sirovog izlaza (`raw-output`) |
| `/api/context/rtk/filters`             | GET            | RTK katalog filtera i dijagnostika prilagođenih filtera                                                 |
| `/api/context/rtk/test`                | POST           | Pokretanje RTK pregleda/testa na tekstualnom payload-u                                                  |
| `/api/context/rtk/raw-output/[id]`     | GET            | Čitanje zadržanog recenziranog sirovog izlaza putem ID-a pokazivača                                     |
| `/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        | Dodjeljivanje kombinacija kompresije kombinacijama rutiranja                                            |
| `/api/context/analytics`               | GET            | Alias za analitiku kompresije                                                                           |

### Monitoring

| Endpoint                             | Method     | Opis                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions`                      | GET        | Praćenje aktivnih sesija                                                                                                                                                                                                                                                                                                                                                                                        |
| `/api/rate-limits`                   | GET        | Rate limiti po nalogu                                                                                                                                                                                                                                                                                                                                                                                           |
| `/api/monitoring/health`             | GET        | Provjera zdravlja + sažetak provajdera (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). Pogled za upravljanje uključuje `credentialHealth`: skalari probe-cache-a, `failedConnections` kada je `failed>0`, i `staleDbNonOkCount` (SQLite sticky `test_status`, ne gauge). Pogledajte [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). |
| `/api/cache/stats`                   | GET/DELETE | Statistika cache-a / brisanje                                                                                                                                                                                                                                                                                                                                                                                   |
| `/api/modality-bridge/stats`         | GET        | In-memory `attempts`, uspjesi/`bridged`, neuspjesi, cache pogoci, `totalLatencyMs`, `latencySamples`, prosjek `averageLatencyMs` po uzorku, i vrijeme posljednje upotrebe (resetuje se pri ponovnom pokretanju; management auth)                                                                                                                                                                                |
| `/api/modality-bridge/video/runtime` | GET        | Stroga provjera trusted-loopback-a prije management auth/probe; sanitizirana dostupnost i verzije FFmpeg/ffprobe (no-store)                                                                                                                                                                                                                                                                                     |
| `/api/modality-bridge/video/extract` | POST       | Interni autentificirani trusted-loopback byte broker; 50 MiB ulaz, ograničeni red/32 MiB izlaz, `503` kapacitet, `499` diskonekt, `504` deadline; nije javni upload API                                                                                                                                                                                                                                         |

### Backup & Export/Import

| Endpoint                    | Method | Opis                                             |
| --------------------------- | ------ | ------------------------------------------------ |
| `/api/db-backups`           | GET    | Lista dostupnih rezervnih kopija                 |
| `/api/db-backups`           | PUT    | Kreiraj ručnu rezervnu kopiju                    |
| `/api/db-backups`           | POST   | Vrati podatke iz specifične rezervne kopije      |
| `/api/db-backups/export`    | GET    | Preuzmi bazu podataka kao .sqlite datoteku       |
| `/api/db-backups/import`    | POST   | Učitaj .sqlite datoteku za zamjenu baze podataka |
| `/api/db-backups/exportAll` | GET    | Preuzmi punu rezervnu kopiju kao .tar.gz arhivu  |

### Cloud Sync

| Endpoint               | Method  | Opis                           |
| ---------------------- | ------- | ------------------------------ |
| `/api/sync/cloud`      | Various | Operacije cloud sinkronizacije |
| `/api/sync/initialize` | POST    | Inicijalizuj sinkronizaciju    |
| `/api/cloud/*`         | Various | Upravljanje cloudom            |

### Tunnels

| Endpoint                   | Method | Opis                                                                                 |
| -------------------------- | ------ | ------------------------------------------------------------------------------------ |
| `/api/tunnels/cloudflared` | GET    | Pročitaj status instalacije/izvršavanja Cloudflare Quick Tunnel-a za kontrolnu ploču |
| `/api/tunnels/cloudflared` | POST   | Omogući ili onemogući Cloudflare Quick Tunnel (`action=enable/disable`)              |
| `/api/tunnels/ngrok`       | GET    | Pročitaj status izvršavanja ngrok Tunnel-a za kontrolnu ploču                        |
| `/api/tunnels/ngrok`       | POST   | Omogući ili onemogući ngrok Tunnel (`action=enable/disable`)                         |

### CLI Tools

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

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

### ACP Agents

| Endpoint          | Method | Opis                                                                 |
| ----------------- | ------ | -------------------------------------------------------------------- |
| `/api/acp/agents` | GET    | Lista svih detektovanih agenata (ugrađeni + prilagođeni) sa statusom |
| `/api/acp/agents` | POST   | Dodaj prilagođenog agenta ili osvježi cache detekcije                |
| `/api/acp/agents` | DELETE | Ukloni prilagođenog agenta putem `id` query parametra                |

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

### Resilience & Rate Limits

| Endpoint                          | Method    | Opis                                                                                      |
| --------------------------------- | --------- | ----------------------------------------------------------------------------------------- |
| `/api/resilience`                 | GET/PATCH | Preuzmi/ažuriraj red čekanja zahtjeva, hlađenje veze, provider breaker i postavke čekanja |
| `/api/resilience/reset`           | POST      | Resetuj provider circuit breakere                                                         |
| `/api/resilience/model-cooldowns` | GET       | Lista aktivnih blokada po-(provider, connection, model), sortirana po preostalom vremenu  |
| `/api/resilience/model-cooldowns` | DELETE    | Obriši blokadu modela — tijelo `{provider, model}` ili `{all: true}` za brisanje svega    |
| `/api/rate-limits`                | GET       | Status ograničenja brzine (rate limit) po nalogu                                          |
| `/api/rate-limit`                 | GET       | Globalna konfiguracija ograničenja brzine                                                 |

> Sve četiri `/api/resilience/*` rute zahtijevaju **management auth** (`requireManagementAuth`). Pogledajte [Resilience (extended)](#resilience-extended) za detaljan pregled provider breaker-a naspram hlađenja veze i blokade modela.

### Evals

| Endpoint     | Method   | Opis                                      |
| ------------ | -------- | ----------------------------------------- |
| `/api/evals` | GET/POST | Lista eval suite-ova / pokreni evaluaciju |

### Policies

| Endpoint        | Method          | Opis                             |
| --------------- | --------------- | -------------------------------- |
| `/api/policies` | GET/POST/DELETE | Upravljanje politikama rutiranja |

### Compliance

| Endpoint                    | Method | Opis                             |
| --------------------------- | ------ | -------------------------------- |
| `/api/compliance/audit-log` | GET    | Compliance audit log (zadnjih N) |

### v1beta (Gemini-Compatible)

| Endpoint                   | Method | Opis                              |
| -------------------------- | ------ | --------------------------------- |
| `/v1beta/models`           | GET    | Lista modela u Gemini formatu     |
| `/v1beta/models/{...path}` | POST   | Gemini `generateContent` endpoint |

Ovi endpointi preslikavaju Gemini API format za klijente koji očekuju kompatibilnost sa izvornim Gemini SDK-om.

### Internal / System APIs

| Endpoint                 | Method | Opis                                                                  |
| ------------------------ | ------ | --------------------------------------------------------------------- |
| `/api/init`              | GET    | Provjera inicijalizacije aplikacije (koristi se pri prvom pokretanju) |
| `/api/tags`              | GET    | Ollama-kompatibilne oznake modela (za Ollama klijente)                |
| `/api/restart`           | POST   | Pokretanje kontrolisanog ponovnog pokretanja servera                  |
| `/api/shutdown`          | POST   | Pokretanje kontrolisanog gašenja servera                              |
| `/api/system/env/repair` | POST   | Popravka environment varijabli OAuth provajdera                       |

> **Napomena:** Ovi endpointi se koriste interno unutar sistema ili za kompatibilnost sa Ollama klijentima. Krajnji korisnici ih obično ne pozivaju.

### Popravka OAuth okruženja _(v3.6.1+)_

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

{
  "provider": "claude-code"
}
```

Popravlja nedostajuće ili oštećene OAuth environment varijable za specifičnog provajdera. Vraća:

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

---

## Audio Transkripcija

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

Transkribujte audio datoteke koristeći bilo koji konfigurisani STT provajder. Prvi segment putanje bira izvornog provajdera (`openai/…`, `deepgram/…`). Gateway-i koji ponovo izvoze model drugog vendora koriste kvalifikovani ID (`openrouter/deepgram/nova-3`).

**Zahtjev:**

```bash
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:**

```json
{
  "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č). Običan `deepgram/nova-3` zahtjev **ne** koristi OpenRouter.

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

---

## Ollama Kompatibilnost

Za klijente koji koriste Ollama API format:

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

# Lista modela (Ollama format)
GET /api/tags
```

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

## Tokenizovani VS Code / Headerless Aliases

Koristite ove aliase kada integracija ne može ubaciti `Authorization` header i zahtijeva da API ključ bude ugrađen u osnovni URL.

```bash
# OpenAI-style katalog alias
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# OpenAI-style chat aliasi
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Ollama-style aliasi
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```

Primjer:

```bash
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:

- Tokenizovani aliasi koriste iste handlere kao `/v1/*` i `/api/tags`; struktura odgovora ostaje identična.
- Preferirajte `Authorization: Bearer ...` kad god klijent podržava prilagođene headere.
- Tokeni zasnovani na URL-u mogu se pojaviti u reverse-proxy logovima, historiji pretraživača i telemetriji izvan OmniRoute-a. Tretirajte ih kao opciju za kompatibilnost, a ne kao podrazumijevani način autentifikacije.

---

## Telemetrija

```bash
# Preuzmi sažetak telemetrije latencije (p50/p95/p99 po provajderu)
GET /api/telemetry/summary
```

**Odgovor:**

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

---

## Budžet

```bash
# Preuzmi status budžeta za sve API ključeve
GET /api/usage/budget

# Postavi ili ažuriraj budžet
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 šemi** (`setBudgetSchema`): `apiKeyId` je obavezan; barem jedan od `dailyLimitUsd`, `weeklyLimitUsd` ili `monthlyLimitUsd` mora biti veći od nule. Opcionalna polja: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Stari format `{keyId, limit, period}` vraća `400 Bad Request`.

## Limiti tokena

Budžeti **tokena** po API ključu (odvojeno od gore navedenog budžeta zasnovanog na USD). Primjenjuju se direktno na putanji zahtjeva: kada trenutna potrošnja tokena za ključ u određenom prozoru dostigne limit, zahtjevi se odbijaju sa greškom `429 Too Many Requests`. Limiti mogu biti ograničeni na specifični `model`, `provider` ili primijenjeni `global`no na cijeli ključ; kada više limita odgovara zahtjevu, primjenjuje se najstroži od njih.

```bash
# Izlistaj limite tokena za ključ (uključujući trenutnu potrošnju u prozoru)
GET /api/usage/token-limits?apiKeyId=key-123

# Kreiraj ili ažuriraj limit 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 limit tokena putem id-a
DELETE /api/usage/token-limits?id=tl-abc
```

> **Napomene o šemi** (`setTokenLimitSchema`): `apiKeyId` i `scopeType` (`model` | `provider` | `global`) su obavezni. `scopeValue` je obavezan osim ako je `scopeType` postavljen na `global` (npr. id modela za `model` scope, id providera za `provider` scope). `tokenLimit` mora biti pozitivan cijeli broj (konvertovan iz stringa). Opcionalno: `id` (izostavite za kreiranje, navedite za ažuriranje), `resetInterval` (`daily` | `weekly` | `monthly`, zadano `monthly`), `resetTime` (`HH:MM`), `enabled` (zadano `true`). `GET` odgovori obogaćuju svaki limit podacima `tokensUsed`, `remaining`, `windowStart`, `periodStartAt` i `nextResetAt`. Ovo je endpoint za upravljanje (autorizacija se sprovodi centralno putem authz pipeline-a).

## Obrada zahtjeva

1. Klijent šalje zahtjev na `/v1/*`
2. Route handler poziva `handleChat`, `handleEmbedding`, `handleAudioTranscription` ili `handleImageGeneration`
3. Model se razrešava (direktan provider/model ili alias/combo)
4. Akreditivni podaci se biraju iz lokalne baze podataka uz filtriranje dostupnosti računa
5. Za chat: `handleChatCore` provjerava semantički/potpisni cache i razrešava postavke kompresije combo-a
6. Proaktivna kompresija se pokreće prije prevoda providera kada je omogućena (`lite`, Caveman, RTK ili stacked)
7. Provider executor šalje upstream zahtjev
8. Odgovor se prevodi nazad u format klijenta (chat) ili vraća onako kako jeste (embeddings/images/audio)
9. Potrošnja, analitika kompresije i logovi zahtjeva se zapisuju
10. Fallback se primjenjuje pri greškama prema pravilima combo-a

Potpuna referenca arhitekture: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)

---

## Upravljanje Combo-ima

Combo-i rutiranja višeg nivoa (već sumirani pod `/api/combos*`) također se mogu mapirati 1:1 iz obrasca id-a modela, omogućavajući transparentno preusmjeravanje OpenAI-stilskog id-a modela na combo.

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

**Auth:** sesija za upravljanje/API ključ (`requireManagementAuth`).

---

## Webhooks

Pretplatbe na odlazne webhook-ove za OmniRoute događaje (završetak zahtjeva, iscrpljivanje kvote, rotacija ključeva, itd.).

| Metoda | Putanja                   | Opis                                                                     |
| ------ | ------------------------- | ------------------------------------------------------------------------ |
| GET    | `/api/webhooks`           | Lista webhook-ova (tajne su maskirane kao `<prefix>...`)                 |
| POST   | `/api/webhooks`           | Kreiraj webhook — tijelo: `{url, events?: ["*"], secret?, description?}` |
| GET    | `/api/webhooks/[id]`      | Preuzmi 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 webhook URL i vrati status dostave             |

**Auth:** management sesija/API ključ (`requireManagementAuth`).

---

## Registrovani ključevi (Auto-upravljanje)

Koristi ih podsistem za automatsko upravljanje ključevima za izdavanje i rotaciju API ključeva prema osnovnom provajderu/računu, sa dnevnim/satnim kvotama.

| Metoda | Putanja                               | Opis                                                                                                                                                                                               |
| ------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/registered-keys`             | Lista registrovanih ključeva (samo maskirani prefiks)                                                                                                                                              |
| POST   | `/api/v1/registered-keys`             | Izdaj novi registrovani ključ — tijelo: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Vraća sirovi ključ **jednom**. Vraća `429` pri odbijanju kvote. |
| GET    | `/api/v1/registered-keys/[id]`        | Preuzmi metapodatke registrovanog ključa (bez sirovog materijala)                                                                                                                                  |
| DELETE | `/api/v1/registered-keys/[id]`        | Opozovi registrovani ključ                                                                                                                                                                         |
| POST   | `/api/v1/registered-keys/[id]/revoke` | Endpoint za eksplicitno opozivanje (isti efekat kao DELETE)                                                                                                                                        |

**Auth:** Bearer API ključ (`isAuthenticated`). Pogledajte također `/v1/quotas/check` i `/v1/issues/report`.

---

## Agents Protokol

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

| Metoda | Putanja                       | Opis                                                                                                                                                   |
| ------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET    | `/api/v1/agents/tasks`        | Lista zadataka — opcionalno `?provider=`, `?status=`, `?limit=` (1–500, podrazumijevano 50)                                                            |
| POST   | `/api/v1/agents/tasks`        | Kreiraj zadatak — tijelo validirano putem `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Vraća `201` sa omotajem zadatka |
| DELETE | `/api/v1/agents/tasks?id=...` | Obriši zadatak                                                                                                                                         |
| GET    | `/api/v1/agents/tasks/[id]`   | Pročitaj zadatak — sinhrono osvježava status iz upstream cloud agenta kada je `external_id` postavljen                                                 |
| POST   | `/api/v1/agents/tasks/[id]`   | Diskriminirana akcija: `{action: "approve"}`, `{action: "message", message}`, ili `{action: "cancel"}`                                                 |
| DELETE | `/api/v1/agents/tasks/[id]`   | Obriši specifičan zadatak putem id-a                                                                                                                   |

> **Auth:** management auth je potreban za svaku metodu (`requireCloudAgentManagementAuth`). Prije v3.8.0 ove metode nisu zahtjevale autentifikaciju — pogledajte commit `588a0333` za breaking change.

```bash
# Kreiraj Claude Code cloud zadatak
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":"..."}}'
```

---

## Management Proxies

Odlazni HTTP(S)/SOCKS proxiji koji se mogu dodijeliti provajderima, računima ili globalno.

| Metoda | Putanja                                      | Opis                                                                                                                                                    |
| ------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/management/proxies`                 | Lista proxija (sa `?id=` vraća jedan; sa `?id=&where_used=1` vraća graf dodjela)                                                                        |
| POST   | `/api/v1/management/proxies`                 | Kreiraj proxy — tijelo validirano putem `createProxyRegistrySchema`                                                                                     |
| PATCH  | `/api/v1/management/proxies`                 | Ažuriraj proxy — tijelo validirano putem `updateProxyRegistrySchema` (zahtijeva `id`)                                                                   |
| DELETE | `/api/v1/management/proxies?id=...&force=1`  | Obriši proxy (koristite `force=1` za uklanjanje dodjela)                                                                                                |
| GET    | `/api/v1/management/proxies/assignments`     | Lista dodjela — filtrirano putem `proxy_id`, `scope`, `scope_id`; proslijedite `resolve_connection_id=<id>` za rješavanje aktivnog proxija za konekciju |
| PUT    | `/api/v1/management/proxies/assignments`     | Dodijeli — tijelo validirano putem `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Briše dispatcher cache                                      |
| PUT    | `/api/v1/management/proxies/bulk-assign`     | Masovna dodjela — tijelo validirano putem `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`)                                                 |
| GET    | `/api/v1/management/proxies/health?hours=24` | Agregirano zdravlje proxija (broj uspjeha/neuspjeha, latencija) tokom određenog perioda                                                                 |

**Auth:** management session/API ključ na svakoj ruti (`requireManagementAuth`).

> `POST /api/v1/management/proxies/[id]/assignments` i `POST /api/v1/management/proxies/[id]/health` iz opisa zadataka se opslužuju putem ravnih `/assignments` i `/health` ruta prikazanih iznad — u codebase-u ne postoje pod-rute po id-u.

---

## Otpornost (prošireno)

OmniRoute nudi tri nezavisna mehanizma za privremene kvare; donje upravljačke krajnje tačke omogućavaju operatorima da ih čitaju i nadjačaju:

| 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]` | (ponovno omogućava lijeno; briše putem provider PUT-a) |
| Model lockout       | Registar dostupnosti modela u memoriji     | `GET /api/resilience/model-cooldowns`     | `DELETE /api/resilience/model-cooldowns`               |

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

```bash
# Obriši lockout za jedan model
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 sve lockout-e
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'
```

Potpuna konceptualna referenca i zadane vrijednosti breaker-a: pogledajte [`CLAUDE.md`](../../CLAUDE.md) → "Resilience Runtime State".

---

## Vještine (Skills)

Framework vještina za proširivanje OmniRoute-a prilagođenim izvršnim rukovaocima (handlers), uz integracije sa tržištem.

| Metoda | Put                               | Opis                                                                                                                              |
| ------ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/skills`                     | Lista instaliranih vještina — filtriranje putem `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, paginirano     |
| GET    | `/api/skills/[id]`                | Preuzmi jednu vještinu                                                                                                            |
| PUT    | `/api/skills/[id]`                | Ažuriraj vještinu (ime, opis, režim, shema, rukovalac, tagovi)                                                                    |
| DELETE | `/api/skills/[id]`                | Deinstaliraj vještinu                                                                                                             |
| POST   | `/api/skills/install`             | Instaliraj vještinu iz sirovog manifesta — tijelo: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` |
| GET    | `/api/skills/executions`          | Lista nedavnih izvršenja vještina (audit trag sa ulazima/izlazima/trajanjem)                                                      |
| GET    | `/api/skills/marketplace?q=...`   | Pretraga/popularna lista sa SkillsMP tržišta (zahtijeva `skillsmpApiKey` postavku)                                                |
| POST   | `/api/skills/marketplace/install` | Instaliraj vještinu putem id-a sa SkillsMP                                                                                        |
| GET    | `/api/skills/skillssh?q=&limit=`  | Pretraži skills.sh registar                                                                                                       |
| POST   | `/api/skills/skillssh/install`    | Instaliraj vještinu putem id-a sa skills.sh                                                                                       |

**Auth:** upravljačka sesija/API ključ. Rute za pretragu tržišta prihvataju ili upravljačku autentifikaciju ili Bearer API ključ (`isAuthenticated`).

---

## Memorija

Persistentno skladište konverzacijske/činjenične memorije, ograničeno po API ključu / sesiji.

| Metoda | Putanja              | Opis                                                                                                                  |
| ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/memory`        | Lista memorija — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, sa `offset/limit` ili `page/limit` paginacijom         |
| POST   | `/api/memory`        | Kreiraj memoriju — tijelo validirano putem Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
| GET    | `/api/memory/[id]`   | Preuzmi jednu memoriju                                                                                                |
| DELETE | `/api/memory/[id]`   | Obriši memoriju                                                                                                       |
| GET    | `/api/memory/health` | Zdravlje podsistema memorije (povezanost sa DB, embeddings backend, status vektorskog indeksa)                        |

**Auth:** management sesija/API ključ (`requireManagementAuth`). `type` enum: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (vidi `MemoryType` u `src/lib/memory/types.ts`).

---

## MCP Server

OmniRoute dolazi sa ugrađenim Model Context Protocol serverom sa 3 transporta (stdio, SSE, streamable-http) i ograničenim alatima. Dashboard endpointi ispod čitaju status/audit podatke i proxy-uju HTTP transporte.

| Metoda | Putanja | Opis |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | Heartbeat, transport, online stanje, posljednji poziv, top alati, stopa uspjeha za 24h |
| GET | `/api/mcp/tools` | Lista MCP alata sa `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` |
| GET | `/api/mcp/sse` | Otvori SSE stream za SSE transport (vraća `503` ako je MCP onemogućen ili postoji neslaganje transporta) |
| POST | `/api/mcp/sse` | Pošalji JSON-RPC frame preko SSE transporta |
| GET | `/api/mcp/stream` | Otvori SSE stranu Streamable HTTP transporta (poruke inicirane od strane servera) |
| POST | `/api/mcp/stream` | Pošalji JSON-RPC frame preko Streamable HTTP transporta |
| DELETE | `/api/mcp/stream` | Završi Streamable HTTP sesiju |
| GET | `/api/mcp/audit` | Upit audit log-a — `?limit=`, `?offset=`, `?tool=`, `?success=true                                | false`, `?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | Agregirane audit statistike (ukupno, stopa uspjeha, prosječno trajanje, top alati) |

**Auth:** `sse`/`stream` transporti poštuju MCP-specifičnu površinu autentifikacije (Bearer API ključ sa `mcp` scope-om); `status`/`tools`/`audit*` rute su čitljive iz dashboard-a (nije potrebna dodatna autentifikacija osim pristupa dashboard hostu).

> Oba HTTP transporta su ograničena putem `settings.mcpEnabled` i `settings.mcpTransport` — neslaganje transporta vraća `400`, stanje onemogućenog MCP-a vraća `503`.

---

## A2A Server

OmniRoute izlaže A2A (Agent-to-Agent) JSON-RPC 2.0 endpoint i REST wrapper za potrebe inspekcije/dashboard-a.

### JSON-RPC

```bash
POST /a2a
Authorization: Bearer your-api-key   # opcionalno osim ako OMNIROUTE_API_KEY nije postavljen
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 ograničene postavkom `settings.a2aEnabled`):

| Metoda           | Opis                                                             |
| ---------------- | ---------------------------------------------------------------- |
| `message/send`   | Sinhrona egzekucija skill-a; vraća `{task, artifacts, metadata}` |
| `message/stream` | SSE streaming egzekucija istog skupa skill-ova                   |
| `tasks/get`      | Preuzimanje zadatka putem `taskId`                               |
| `tasks/cancel`   | Otkazivanje zadatka putem `taskId`                               |

Ugrađeni skill-ovi: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.

### Agent Card

```bash
GET /.well-known/agent.json
```

Vraća javnu A2A agent karticu (ime, opis, mogućnosti, katalog skill-ova, auth shema) — javno keširano na 1h. Autentifikacija nije potrebna.

### REST helperi

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

**Auth:** REST helperi rade bez management autentifikacije (čitljivo iz dashboard-a); JSON-RPC `/a2a` ruta koristi Bearer `OMNIROUTE_API_KEY` ako je konfigurisan.

---

## Cloud, Evals & Assess

| Metoda | Putanja | Opis |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | Verifikacija Bearer ključa i vraćanje maskiranih provider konekcija + aliasa modela za cloud sync klijente |
| POST | `/api/cloud/credentials/update` | Ažuriranje enkriptovanih kredencijala za cloud-synced provider |
| POST | `/api/cloud/model/resolve` | Resolving logičkog model id-a u konkretan provider/model koristeći lokalnu routing tabelu |
| GET | `/api/cloud/models/alias` | Lista aliasa modela kako su izloženi cloud sync-u |
| GET | `/api/assess` | Čitanje najnovijih assessment kategorizacija (po provideru/modelu) |
| POST | `/api/assess` | Pokretanje assessment-a — body: `{scope: {type:"all"}                                                   | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | Lista ugrađenih eval suite-ova + najnovijih pokretanja |
| POST | `/api/evals` | Pokretanje eval run-a |
| POST | `/api/evals/suites` | Kreiranje custom eval suite-a — body validiran putem `evalSuiteSaveSchema` |
| GET | `/api/evals/suites/[id]` | Preuzimanje custom eval suite-a |

**Auth:** `/api/cloud/auth` direktno validira Bearer ključ; ostale `/api/cloud/*`, `/api/evals/*` i `/api/assess` rute zahtijevaju management sesiju/API ključ. `/api/assess` POST koristi `validateBody` sa discriminated-union scope shemom.

---

## ACP (Agent Client Protocol) upravljanje

kao djetekcije procesa. Ovi endpointi upravljaju detekcijom ACP agenata i registracijom prilagođenih agenata.

| Metoda | Putanja           | Opis                                                                                                                                                           |
| ------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/acp/agents` | Lista svih poznatih CLI agenata (ugrađenih + prilagođenih) sa statusom instalacije, verzijom, binarnom datotekom                                               |
| POST   | `/api/acp/agents` | Registruj prilagođenog ACP agenta ili osvježi keš — tijelo: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` ili `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | Ukloni prilagođenog ACP agenta — query parametar: `?id=<agentId>`                                                                                              |

**Primjer odgovora** (`GET /api/acp/agents`):

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

**Auth:** Zahtijeva sesiju upravljanja (dashboard `auth_token` cookie) ili API ključ sa opsegom za upravljanje (management-scoped).

Pogledajte [ACP Framework](../frameworks/ACP.md) za kompletne detalje.

---

## Analitika i Opservabilnost

Endpointi za analitiku u stvarnom vremenu za praćenje rutiranja, kompresije i raznolikosti provajdera. Ovi endpointi napajaju stranice `/dashboard/analytics/*`.

### Analitika auto-rutiranja

| Metoda | Putanja                              | Opis                                                                                                                   |
| ------ | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/analytics/auto-routing`        | Agregatna statistika auto-rutiranja: ukupni pozivi, distribucija strategija, distribucija nivoa (tier), top provajderi |
| GET    | `/api/analytics/auto-routing?days=7` | Statistika za određeni vremenski prozor (podrazumijevano 24h)                                                          |

**Primjer odgovora**:

```json
{
  "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` | Agregatna statistika kompresije: ušteda tokena, % uštede, distribucija modova, upotreba engine-a |

**Primjer odgovora**:

```json
{
  "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 provajdera

| Metoda | Putanja                    | Opis                                                                                                                       |
| ------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/analytics/diversity` | Praćenje raznolikosti zasnovano na Shannonovoj entropiji: sprečava jedinstvene tačke otkaza mjerenjem rasporeda provajdera |

**Primjer odgovora**:

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

**Auth:** Zahtijeva sesiju upravljanja ili API ključ sa opsegom za upravljanje.

---

## Admin Operacije

Endpointi samo za administratore za operativno upravljanje.

| Metoda | Putanja                  | Opis                                                                                                 |
| ------ | ------------------------ | ---------------------------------------------------------------------------------------------------- |
| GET    | `/api/admin/concurrency` | Čitanje trenutnih limita konkurentnosti (globalni + po provajderu)                                   |
| POST   | `/api/admin/concurrency` | Ažuriranje limita konkurentnosti — tijelo: `{global?: number, perProvider?: Record<string, number>}` |

**Auth:** Zahtijeva management sesiju sa admin scope-om.

---

## Upravljanje CLI alatima

Upravljajte CLI alatima koji se integrišu sa OmniRoute-om (antigravity, commandCode,
devin-cli, itd.). Pogledajte [Provider Reference](./PROVIDER_REFERENCE.md) za kompletnu listu.

| Metoda | Putanja                                 | Opis                                                                                                                                                            |
| ------ | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/cli-tools/all-statuses`           | Status svih CLI alata (instalirani, verzija, zadnji viđeni)                                                                                                     |
| GET    | `/api/cli-tools/status`                 | Detaljan status za jedan CLI alat (`?tool=` upit)                                                                                                               |
| POST   | `/api/cli-tools/apply`                  | Zapisivanje generisane konfiguracije alata (`dryRun` za pregled; `422` + `containerEphemeralTarget` kada je kontejnerizovano; `migration` za legacy Codex YAML) |
| GET    | `/api/cli-tools/backups`                | Lista rezervnih kopija (backups) konfiguracija CLI alata                                                                                                        |
| POST   | `/api/cli-tools/backups`                | Kreiranje rezervne kopije svih konfiguracija CLI alata                                                                                                          |
| POST   | `/api/cli-tools/backups`                | Restauracija: isti endpoint sa `{tool, backupId}` u tijelu restaurira tu rezervnu kopiju                                                                        |
| GET    | `/api/cli-tools/antigravity-mitm`       | Status Antigravity MITM proxy-ja (CLI alat "antigravity-mitm")                                                                                                  |
| POST   | `/api/cli-tools/antigravity-mitm/alias` | Konfiguracija antigravity-mitm aliasa                                                                                                                           |

**Auth:** Zahtijeva management sesiju.

---

## Agent Skills (Vještine agenta)

Upravljajte vještinama AI agenta (slično OpenAI custom GPT-ovima, ali za agente).

| Metoda | Putanja                      | Opis                                                                                                |
| ------ | ---------------------------- | --------------------------------------------------------------------------------------------------- |
| GET    | `/api/agent-skills`          | Lista svih vještina agenta (ugrađene + prilagođene)                                                 |
| GET    | `/api/agent-skills/[id]`     | Preuzimanje specifične 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` | Preuzimanje sirovog prompta + metapodataka (bez izvršavanja)                                        |
| POST   | `/api/agent-skills/generate` | AI generisanje nove vještine iz opisa na prirodnom jeziku                                           |

**Auth:** Zahtijeva management sesiju ili API ključ sa management scope-om.

---

## Upravljanje kešom

Upravljajte semantičkim kešom i kešom zaključivanja (reasoning cache).

| Metoda | Putanja                | Opis                                                                                                                         |
| ------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/cache`           | Pregled keša: ukupni unosi, stopa pogodaka (hit rate), veličina na disku                                                     |
| GET    | `/api/cache/entries`   | Lista keširanih unosa (sa paginacijom)                                                                                       |
| DELETE | `/api/cache/entries`   | Brisanje unosa iz keša (filtriranje putem query parametara)                                                                  |
| GET    | `/api/cache/stats`     | Detaljna statistika keša (po provajderu, po modelu)                                                                          |
| GET    | `/api/cache/reasoning` | Status keša zaključivanja (za ponovnu reprodukciju zaključivanja)                                                            |
| DELETE | `/api/cache/reasoning` | Brisanje keša zaključivanja — query parametri: `?toolCallId=<id>` (pojedinačno) ili `?provider=<p>` ili bez parametara (sve) |

**Auth:** Zahtijeva management sesiju.

---

## Sistem memorije

Upravljajte trajnom memorijom (FTS5 + vektorski embedding-zi).

| Metoda | Putanja            | Opis                                                                           |
| ------ | ------------------ | ------------------------------------------------------------------------------ |
| GET    | `/api/memory`      | Lista unosa u memoriji (filtriranje po opsegu, tipu, upitu za pretragu)        |
| POST   | `/api/memory`      | Kreiranje novog unosa u memoriji — tijelo: `{scope, type, content, metadata?}` |
| GET    | `/api/memory/[id]` | Preuzimanje specifičnog unosa u memoriji                                       |
| PUT    | `/api/memory/[id]` | Ažuriranje unosa u memoriji                                                    |
| DELETE | `/api/memory/[id]` | Brisanje unosa u memoriji                                                      |
| GET    | `/api/memory?q=`   | Pretraga memorije (FTS5 + vektor) — statistika je uključena u isti odgovor     |

**Auth:** Zahtijeva management sesiju ili API ključ sa management opsegom.

---

## Webhook-ovi

Upravljajte pretplatama na webhook-ove za događaje.

| Metoda | Putanja                         | Opis                                                                         |
| ------ | ------------------------------- | ---------------------------------------------------------------------------- |
| GET    | `/api/webhooks`                 | Lista svih pretplata na webhook-ove                                          |
| POST   | `/api/webhooks`                 | Kreiranje pretplate na webhook — tijelo: `{url, events[], secret?, active?}` |
| GET    | `/api/webhooks/[id]`            | Preuzimanje specifične 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` | Lista historije isporuka za webhook (log uspjeha/neuspjeha)                  |
| POST   | `/api/webhooks/[id]/test`       | Slanje testnog događaja na webhook                                           |

**Auth:** Zahtijeva management sesiju.

Pogledajte [Webhooks Framework](../frameworks/WEBHOOKS.md) za kompletne tipove događaja.

---

## Framework vještina (Skills Framework)

Upravljanje vještinama (framework za agentske ekstenzije).

| Metoda | Putanja                  | Opis                                                                                                     |
| ------ | ------------------------ | -------------------------------------------------------------------------------------------------------- |
| GET    | `/api/skills`            | Lista svih instaliranih vještina (ugrađene + prilagođene)                                                |
| POST   | `/api/skills/install`    | Instalacija vještine iz lokalne putanje ili URL-a                                                        |
| DELETE | `/api/skills/[id]`       | Deinstalacija 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` | Lista historije izvršavanja za sve vještine (filtriranje putem `?apiKeyId=`)                             |

**Auth:** Zahtijeva sesiju upravljanja ili API ključ s opsegom za upravljanje (management-scoped).

Pogledajte [Skills Framework](../frameworks/SKILLS.md) za kompletne detalje.

---

## Dodaci (Plugins)

Upravljanje OmniRoute dodacima (ekstenzije trećih strana).

| Metoda | Putanja                            | Opis                                 |
| ------ | ---------------------------------- | ------------------------------------ |
| GET    | `/api/plugins`                     | Lista instaliranih dodataka          |
| POST   | `/api/plugins/marketplace/install` | Instalacija dodatka iz marketplace-a |
| DELETE | `/api/plugins/[name]`              | Deinstalacija dodatka                |
| POST   | `/api/plugins/[name]/activate`     | Aktivacija dodatka                   |
| POST   | `/api/plugins/[name]/deactivate`   | Deaktivacija dodatka                 |
| GET    | `/api/plugins/[name]/config`       | Preuzimanje konfiguracije dodatka    |
| PUT    | `/api/plugins/[name]/config`       | Ažuriranje konfiguracije dodatka     |

**Auth:** Zahtijeva sesiju upravljanja.

Pogledajte [Plugins Framework](../frameworks/PLUGIN_SDK.md) za kompletne detalje.

---

## Shadow Routing

Shadow / A-B poređenje provajdera **nije zaseban REST interfejs** — konfigurira se putem combo rutiranja (pogledajte [Auto-Combo](../routing/AUTO-COMBO.md)). Metrike poređenja po combo-u dostupne su putem `GET /api/combos/metrics`.

---

## Guardrails (Zaštitni mehanizmi)

Pregled runtime zaštitnih mehanizama (detekcija PII-a, detekcija prompt injekcije, vision bridging). Guardrails rade na svakom zahtjevu; isključivanje po pojedinačnom pozivu vrši se putem `x-omniroute-disabled-guardrails` zaglavlja zahtjeva — ne postoji trajno površina za omogućavanje/onemogućavanje.

| Metoda | Putanja                | Opis                                                                                                       |
| ------ | ---------------------- | ---------------------------------------------------------------------------------------------------------- |
| GET    | `/api/guardrails`      | Lista registrovanih guardrails-a i njihovog statusa (ime / omogućeno / prioritet)                          |
| POST   | `/api/guardrails/test` | Probno pokretanje (dry-run) pre-call pipeline-a nad uzorkom ulaza — tijelo: `{input, disabledGuardrails?}` |

**Auth:** Zahtijeva sesiju upravljanja.

Pogledajte [Security > Guardrails](../security/GUARDRAILS.md) za kompletne detalje.

---

---

## Autentifikacija

Pogledajte [Management Authentication](../guides/MANAGEMENT-AUTH.md) za četiri porodice kredencijala (dashboard sesija, lokalni CLI token, `oma_live_…` Access Token, manage-scoped API ključ) i kako se oni razlikuju od ključeva za inferenciju.

- Dashboard rute (`/dashboard/*`) koriste `auth_token` kolačić
- Prijava koristi sačuvani hash lozinke; fallback na `INITIAL_PASSWORD`
- `requireLogin` se može uključiti/isključiti putem `/api/settings/require-login`
- `/v1/*` rute opcionalno zahtijevaju Bearer API ključ kada je `REQUIRE_API_KEY=true`
- "management token" / "management-scoped API key" u ovoj referenci označava jednu od porodica iz navedenog vodiča — a ne neki nedefinisani dodatni tip tajne

> **Breaking change (v3.8.0)** — `/api/v1/agents/tasks/*` i endpointi za upravljanje cooldown-om sada zahtijevaju **management auth** (dashboard `auth_token` kolačić ili management-scoped API ključ). Klijenti koji su prethodno pozivali ove rute bez autentifikacije primit će `401 Unauthorized`. Pogledajte commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).