pjandro/OmniRoute
1
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-09-16 20:02:45 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
17c3a693df2c4e81e286cdc38c1ee20311285af2
OmniRoute/docs/i18n/sr/docs/reference/API_REFERENCE.md
Diego Rodrigues de Sa e Souza 9debec71ec feat(i18n): 9 new locales — all 24 official EU languages (51 locales) (#13044) 
Batch 1 of the locale expansion: Greek, Croatian, Serbian, Lithuanian, Estonian, Latvian, Slovenian, Maltese and Irish across the dashboard catalog, docs mirrors, CLI catalog, README, locale index and the site. 42 → 51 locales.

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

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

1783 lines
134 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# API_REFERENCE (Српски)
🌐 **Languages:** 🇺🇸 [English](../../../../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) · 🇮🇱 [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) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/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) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/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) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/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) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)
---
---
title: "API Reference"
version: 3.8.51
lastUpdated: 2026-08-31
---
# API Reference
🌐 **Languages:** 🇺🇸 [English](../../../../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) · 🇮🇱 [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) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/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) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/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) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/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) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)
Основна референца за OmniRoute API. Обухвата јавну `/v1` површину и најчешће коришћене крајње тачке за управљање; машински читљив [`docs/openapi.yaml`](../openapi.yaml) и стабло рута под `src/app/api/` представљају потпуне изворе.
---
## Садржај
- [Chat Completions](#chat-completions)
- [Exclusive Managed Session Leases](#exclusive-managed-session-leases)
- [Embeddings](#embeddings)
- [Image Generation](#image-generation)
- [Document OCR](#document-ocr)
- [List Models](#list-models)
- [Provider Plugin Manifest](#provider-plugin-manifest)
- [Compatibility Endpoints](#compatibility-endpoints)
- [Files API](#files-api)
- [Batches API](#batches-api)
- [Search API](#search-api)
- [WebSocket Streaming](#websocket-streaming)
- [Quotas & Issues Reporting](#quotas--issues-reporting)
- [Semantic Cache](#semantic-cache)
- [Dashboard & Management](#dashboard--management)
- [Combo Management](#combo-management)
- [Webhooks](#webhooks)
- [Registered Keys (Auto-Management)](#registered-keys-auto-management)
- [Agents Protocol](#agents-protocol)
- [Management Proxies](#management-proxies)
- [Resilience (extended)](#resilience-extended)
- [Skills](#skills)
- [Memory](#memory)
- [MCP Server](#mcp-server)
- [A2A Server](#a2a-server)
- [Cloud, Evals & Assess](#cloud-evals--assess)
- [Request Processing](#request-processing)
- [Authentication](#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
}
```
### Прилагођена заглавља
| Заглавље | Смер | Опис |
| ------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-OmniRoute-No-Cache` | Захтев | Поставите на `true` да заобиђете кеш |
| `x-omniroute-no-memory` | Захтев | Поставите на `true` да прескочите убацивање памћења + вештина за овај захтев (по узору на no-cache; избегава додатни трошак токена/цене по позиву) |
| `X-OmniRoute-Progress` | Захтев | Поставите на `true` за догађаје напредовања |
| `X-Session-Id` | Захтев | Стални кључ сесије за спољашњу афинитет сесије |
| `x_session_id` | Захтев | Прихватљива је и варијанта са доњом цртом (директан HTTP) |
| `X-OmniRoute-Session-Id` | Захтев | Ознака сесије/конверзације коју доставља позивач (такође утиче на памћење). Када је присутна, чува се дословно у `call_logs.session_tag` за атрибуцију трошкова по сесији (#8249) — никада се не генерише самостално када недостаје |
| `Idempotency-Key` | Захтев | Кључ за дедупликацију (прозор од 5с) |
| `X-Request-Id` | Захтев | Алтернативни кључ за дедупликацију |
| `X-OmniRoute-Cache` | Одговор | `HIT` или `MISS` (без стримовања) |
| `X-OmniRoute-Idempotent` | Одговор | `true` ако је дедуплицирано |
| `X-OmniRoute-Progress` | Одговор | `enabled` ако је праћење напредовања укључено |
| `X-OmniRoute-Session-Id` | Одговор | Ефективни ID сесије који користи OmniRoute |
| `X-OmniRoute-Request-Id` | Одговор | ID корелације захтева (када је познат) |
| `X-OmniRoute-Version` | Одговор | Верзија OmniRoute билда (увек присутна) |
| `X-OmniRoute-Cost-Saved` | Одговор | Износ у USD који је кеш избегао приликом HIT-а (само за кеш погодке) |
| `X-OmniRoute-Decision` | Одговор | Траг рутирања: `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` је стратегија комбинације, или `single` за захтев који није комбинован) — увек присутно у одговорима на завршене захтеве |
> Напомена о Nginx-у: ако се ослањате на заглавља са доњом цртом (на пример, `x_session_id`), омогућите `underscores_in_headers on;`.
> **Заглавља за телеметрију трошкова:** одговори са успешним завршетком без стримовања такође носе скуп `X-OmniRoute-*` заглавља за телеметрију трошкова — `X-OmniRoute-Response-Cost` (у USD, фиксно на 10 децимала; `0.0000000000` за бесплатне/непроцењене случајеве), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit`, и `X-OmniRoute-Fallback-Attempts` (само када је > 0), као и `X-OmniRoute-Request-Id` и `X-OmniRoute-Version`. Ова заглавља генеришу chat completions, `/v1/responses`, `/v1/messages`, **и медијски крајњи endpoint-и** — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations`, и `/v1/moderations` (увек трошак `0`). Трошак медија се израчунава по модалитету (по слици, по секунди, по карактеру, по јединици претраге) када је доступна ценовна информација, у супротном `0` (fail-open — не блокира при грешци).
> **Семантика трошка код кеш погодка (cache-hit):** приликом семантичког кеш погодка (`X-OmniRoute-Cache-Hit: true`) не позива се провајдер узводно, тако да је `X-OmniRoute-Response-Cost` `0.0000000000` (**инкрементални** трошак опслуживања погодка). Оригинални/потенцијални трошак се пријављује одвојено у `X-OmniRoute-Cost-Saved`. Потрошачи наплате треба да сабирају `X-OmniRoute-Response-Cost` (погоци не коштају ништа); аналитика кеша може агрегирати `X-OmniRoute-Cost-Saved`.
## Ексклузивни закупи управљане сесије
Ексклузивно закупљивање управљане сесије је опциони, клијентски неутралан рутирајући уговор: један активни власник
држи једну подобну OmniRoute везу. Он не закупљује модел, не захтева OAuth, не идентификује
одређеног клијента, ни не захтева одређеног провајдера.
API кључ који врши аутентикацију мора имати опсег `lease:exclusive` и експлицитну непразну
листу `allowedConnections`. Граница мутације базе података намеће оба поља заједно приликом
креирања кључа и делимичних ажурирања.
```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"}
```
Успешни одговори на acquire, renew и release излажу временске ознаке, `state` и тачну позитивну
вредност `generation`, али никада изабрану везу или креденцијале. Renew и release достављају
generation у JSON телу:
```json
{ "action": "renew", "generation": 1 }
```
```json
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
```
Активни власник закупа може експлицитно затражити приватносно безбедне метаподатке приказа за своје тренутно везивање:
```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"
}
}
```
Ова опциона акција статуса је оивичена непрозирним власником, аутентикованим управљаним API кључем и тачном
активном generation вредношћу у једној трансакцији базе података. `displayName` је само подрезано конфигурисано
име везе; вредност је `null` када не постоји безбедно конфигурисано име. OmniRoute никада не замењује
имејл или генерисан идентитет налога. Вредност provider је ознака приказа без осетљивих података и никада
генерисан идентификатор компатибилног провајдера. Креденцијали, токени, колачићи (cookies), сирови идентификатори везе или API
кључа, хешеви власника, тајне ограђивања и интерни подаци рутирања су искључени.
Претраге са погрешним кључем, погрешним власником, застарелом generation вредношћу, недостајуће, истекле, ослобођене и поништене
све враћају исту грешку `409 LEASE_FENCE_STALE` без метаподатака везе. Клијент који је примио одговор о чекању на капацитет нема активно везивање за преглед. Када рутирање пренесе активни закуп на другу везу,
исти generation остаје важећи и status атомски враћа ново везивање, никада старо.
Постојећи клијенти остају непромењени јер acquire, renew, release и одговори чекања задржавају
своје претходне облике.
Овај серверски уговор не мења стандардни OpenAI Codex `/status`. Стандардни Codex тренутно пријављује свог
провајдера модела и уграђено стање аутентикације/налога, али не приказује произвољне метаподатке налога прилагођеног
провајдера; каснија клијентска интеграција мора позвати ову акцију и одлучити како да
прикаже `connection.displayName`.
Сваки управљани захтев за инференцију тада доставља оба контролна заглавља:
```http
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
```
Тачан власник, generation, активна веза и аутентикован API кључ се ограђују непосредно
пре сваког подржаног покушаја узводно (upstream). Понављање власника и generation вредности са другим кључем не успева и када
тај кључ дозвољава исту везу. Сирови власници се не чувају трајно, не логују, не задржавају у
снимку захтева ни прослеђују узводно.
Привремена контенција враћа HTTP `429` са `Retry-After` и:
```json
{
"state": "WAITING_FOR_CAPACITY",
"error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
"reason": "NO_FREE_ELIGIBLE_CONNECTION",
"retryAfter": 30
}
```
Овај одговор значи само да обичан подобан скуп није био празан и да је сваки слободан кандидат
био заузет туђим активним закупом. Неподржани модели/провајдери, неусклађеност политике, cooldown, квота,
здравствено стање и остале обичне неуспешне провере подобности задржавају своје постојеће OmniRoute одговоре.
### `x-omniroute-compression`
Прекорачење плана компресије по захтеву. Има највиши приоритет — надјачава прекорачење routing-комбинације,
активни профил, аутоматски покретач и подразумевану вредност панела. Вредности:
| Вредност | Ефекат |
| ------------- | ----------------------------------------------------------------------------------------------- |
| `off` | Без компресије за овај захтев. |
| `default` | Подразумевани профил изведен из панела (игнорише активни профил). |
| `engine:<id>` | Појединачни мотор када је омогућен, нпр. `engine:rtk`. |
| `<combo>` | Именована комбинација, поклапа се по имену (без разлике велика/мала слова) прво, затим по id-у. |
Напомене:
- Непознате вредности се игноришу (захтев се никада не одбија); резолуција прелази на нормалан приоритет оператора.
- Ако више комбинација дели исто име, проследите **id** комбинације за детерминистичко поклапање.
- Комбинација чије је име `off` или `default` не може бити изабрана по имену (те кључне речи се тумаче прво); референцирајте такву комбинацију по њеном id-у.
- Главни прекидач компресије је чврста препрека: када је компресија глобално онемогућена, ово заглавље је не може омогућити.
Примењени план се враћа у заглављу одговора:
```
X-OmniRoute-Compression: <mode>; source=<source>
```
где је `<source>` једно од `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default`, или `off`.
---
## Embeddings
```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.
ID-jevi u katalogu su u formatu `provider/model` (primer: `jina-ai/jina-embeddings-v5-omni-small`). Goli Jina ID-jevi modela koji se pojavljuju u registru (na primer `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) se takođe razrešavaju. Jina embed/rerank/classify/segment prvo koriste `jina-ai` kredencijale iz dashboard-a; `JINA_AI_API_KEY` je rezervni izbor samo kada ne postoji ključ u dashboard-u. Kartica `jina-reader` je namenjena samo za Reader / `r.jina.ai` (`POST /v1/web/fetch`) i nikada ne opslužuje embeddings ili rerank.
Modeli iz registra koji podržavaju multimodalnost takođe prihvataju do 32 provajder-neutralne strukturirane
stavke. Tipovi media stavki su `text`, `image`, `audio`, `video` i `document`. Njihov media `source`
je ili `{"type":"url","url":"https://..."}` ili
`{"type":"base64","data":"...","media_type":"..."}`.
Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano`,
i alias familije `jina-ai/jina-embeddings-v5-omni` → omni-small) takođe prihvata Jina-ine izvorne
EmbeddingsV5Request dokumente i **prosleđuje ih neizmenjene** na `https://api.jina.ai/v1/embeddings`:
```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 }` vrednosti mogu biti javni HTTPS URL, `data:` URI, ili sirovi
base64. OmniRoute ne pretvara te objekte u stringove i ne preuzima izvorne image URL-ove — Jina sama
preuzima javne medije. Dodatna Jina polja (`task`, `normalized`, `truncate`, `embedding_type`) se
prosleđuju. Jina SKU-ovi koji rade samo sa tekstom i dalje odbijaju dokumente koji nisu tekstualni.
Bezbednosna i transportna ograničenja:
- URL-ovi udaljenih medija moraju biti javni HTTPS. Kanonske `{type,source:url}` stavke se preuzimaju
na strani servera (revalidacija redirekcija, timeout, ograničenja veličine, javni DNS, connection pinning) i
ugrađuju pre pozivanja provajdera. Jina-izvorne `{image:"https://..."}` stavke se prosleđuju kao takve
nakon istog javnog HTTPS provera; Jina preuzima URL.
- Inline base64 medija je ograničen na 8 MiB dekodovano po stavci i 16 MiB dekodovano ukupno po zahtevu.
Prevod na strani provajdera (kanonske stavke se nikada ne prosleđuju neizmenjene):
- Jina multimodalni modeli: svaka stavka na najvišem nivou postaje jedan objekat obeležen modalitetom
(`text` / `image` / `audio` / `video` / `pdf`) koristeći data URI-jeve za inline medije; jedan vektor po
stavci na najvišem nivou.
- Gemini Embedding 2 familija: jedan niz na najvišem nivou postaje jedan izvorni
`models/{model}:embedContent` zahtev sa `content.parts` (`text` ili `inline_data`).
- Nepoznati/dinamički modeli bez eksplicitnih metapodataka o modalitetu odbijaju strukturirani unos sa HTTP 400.
```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 umesto da prilagođavaju stavku. Polja
proširenja koja se ne odnose na input, u zahtevima sa zastarelim string/token formatom, i dalje se prosleđuju neizmenjena.
```bash
# Prikaz svih embedding modela
GET /v1/embeddings
```
---
## Генерисање слика
```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"
}
```
Доступни провајдери: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (локално), ComfyUI (локално).
```bash
# Приказ свих модела за слике
GET /v1/images/generations
```
---
## OCR за документе
```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` бира OCR провајдера преко префикса `provider/model`; чист идентификатор модела (нпр.
`mistral-ocr-latest`) разрешава се до свог регистрованог провајдера, а ако је `model` изостављен, подразумевано се користи
Mistral (`mistral-ocr-latest`). Регистровани провајдери (`open-sse/config/ocrRegistry.ts`):
| ID провајдера | ID модела | Вредност `model` | Напомене |
| ----------------------------- | -------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (или чисто `mistral-ocr-latest`) | Синхроно — одговор се враћа директно из једног позива upstream-у. |
| `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | Асинхрони upstream (`analyze` + polling) — погледајте испод. |
| `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Синхроно, преко Vertex AI-евог партнерског endpoint-а `openapi/chat/completions` — погледајте испод за аутентикацију/URL. |
Сва три провајдера одговарају у истом облику као Mistral:
```json
{
"pages": [{ "index": 0, "markdown": "# Извучени текст..." }],
"model": "mistral-ocr-latest",
"usage_info": { "pages_processed": 1 }
}
```
### Ток анкетирања (poll) за Azure Document Intelligence
Azure Document Intelligence-ов `analyze` API је асинхрон: почетни захтев враћа заглавље
`Operation-Location` уместо тела одговора, а резултат се мора добавити анкетирањем (polling). Handler
(`open-sse/handlers/ocr.ts`) анкетира тај URL сваке секунде до 30 покушаја, брзо прекида (не наставља
анкетирање) уколико одговор анкетирања није `ok` или је статус `"failed"`, и враћа `504` уколико
операција још траје након што се потроши буџет покушаја. Коначни Azure одговор се
нормализује у исти облик `pages`/`markdown` који користи Mistral пре него што се врати
позиваоцу, тако да клијентски код не мора посебно обрађивати овог провајдера.
### Vertex AI DeepSeek OCR аутентикација и разрешавање endpoint-а
`vertex-deepseek-ocr` користи исту Vertex AI аутентикацију која OmniRoute већ подржава за
chat/image саобраћај (`open-sse/executors/vertex.ts`): API кључ конекције је или Service Account JSON
акредитив (који се размењује за краткотрајан OAuth приступни токен путем JWT-bearer
тока), или већ издат OAuth приступни токен који се користи такав какав је. Upstream endpoint URL је Vertex-ов
генерички партнерски endpoint `openapi/chat/completions`, изграђен на основу пројекта и
региона конекције — експлицитни `providerSpecificData.project`/`providerSpecificData.region` увек има приоритет;
у супротном, пројекат се изводи из `project_id` вредности Service Account JSON-а, а регион
подразумевано постаје `us-central1`. Оба разрешавања се дешавају у `open-sse/handlers/ocr.ts`
(`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`), а користи их
`src/app/api/v1/ocr/route.ts` пре прослеђивања ка `handleOcr`.
---
## Листа модела
```bash
GET /v1/models
Authorization: Bearer your-api-key
→ Returns all chat, embedding, and image models + combos in OpenAI format
```
### Префикси ID-а модела (`?prefix=`)
Већина модела се оглашава под **префиксом провајдера**. Који префикс добијате контролише
фича-застава `MODELS_CATALOG_PREFIX_MODE`, а може се преклопити **по захтеву** помоћу
query параметра — корисно за клијента који жели чисту листу без промене подешавања на нивоу
сервера за све остале:
```bash
GET /v1/models?prefix=alias # one id per model — the short alias prefix
GET /v1/models?prefix=dual # both forms (server default)
GET /v1/models?prefix=canonical # only the full provider-id prefix
```
| Режим | Емитује | Напомене |
| ----------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual` | `cc/claude-sonnet-4-6` **и** `claude/claude-sonnet-4-6` | **Подразумевано.** Оба ID-а рутирају на исти модел; задржано да би конфигурације клијента које су чврсто кодирале било који облик наставиле да раде. Приближно дуплира каталог. |
| `alias` | `cc/claude-sonnet-4-6` | Један запис по моделу. Провајдери без посебног алиаса ипак емитују свој запис, тако да се ништа не губи. |
| `canonical` | `claude/claude-sonnet-4-6` | Један запис по моделу под потпуним префиксом provider-id. Провајдери без посебног алиаса (нпр. `antigravity/…`, `agy/…`) овде такође емитују свој јединствени ID, тако да се ништа не губи. |
`dual`-режим огледала се такође може препознати без query параметра: носи поље `parent`
које показује на примарни ID.
Клијенти који приказују бирач модела треба да захтевају `?prefix=alias` — то је оно што ради
[OmniCopilot VS Code екстензија](../guides/VSCODE-COPILOT.md).
### Варијанте модела без размишљања (no-thinking)
За Claude модele који су способни за размишљање, `/v1/models` такође оглашава **no-thinking** варијанту чији ID има префикс `claude-3-omniroute-no-thinking/`:
```
claude-3-omniroute-no-thinking/<provider>/<model>
```
Одабир овог ID-а (нпр. у конфигурацији Claude Code-а која увек прикачи `thinking` блок) резолвира се назад на стварни `<provider>/<model>` са потиснутим резоновањем — `thinking:{type:"disabled"}` на путу `/v1/messages`, или испуштена поља `reasoning`/`reasoning_effort` на путу `/v1/chat/completions`. Варијанта се наводи само за моделе из Claude породице који подржавају размишљање **и** прихватају `disabled` (тако да су, на пример, само-адаптивни модели који одбијају `disabled` искључени). Оператори могу да форсирају варијанту, укључено или искључено, по моделу преко `ModelSpec.noThinkingAlias`.
---
## Manifest utičnih modula provajdera (Provider Plugin Manifest)
```bash
GET /api/v1/provider-plugin-manifest
```
Vraća JSON-bezbedan manifest utičnih modula provajdera koji koriste Bifrost, CLIProxyAPI i
budući sidecar rutere. Odgovor se generiše iz TypeScript registra provajdera
i namerno isključuje OAuth klijentske tajne, resolveovanje runtime okruženja,
izvršne (executor) funkcije, request zaglavlja i podatke o nalozima.
Koristite ovaj endpoint kada sidecar radi izvan procesa (out-of-process) i ne može direktno da uveze
`open-sse/config/providerPluginManifestRegistry.ts`.
---
## Kompatibilni endpointi
| Metoda | Putanja | Format |
| ------ | ----------------------------------------- | ----------------------------------------- |
| POST | `/v1/chat/completions` | OpenAI |
| POST | `/v1/messages` | Anthropic |
| POST | `/v1/responses` | OpenAI Responses |
| POST | `/v1/embeddings` | OpenAI |
| POST | `/v1/images/generations` | OpenAI Images |
| POST | `/v1/images/edits` | OpenAI Images (izmena/inpaint) |
| POST | `/v1/videos/generations` | Generisanje video sadržaja u OpenAI stilu |
| POST | `/v1/music/generations` | Generisanje muzike u OpenAI stilu |
| POST | `/v1/audio/transcriptions` | OpenAI Audio (STT) |
| POST | `/v1/audio/speech` | OpenAI TTS (vraća audio telo) |
| POST | `/v1/rerank` | Cohere/Voyage-stil rerangiranja |
| POST | `/v1/classify` | Jina klasifikacija (`api.jina.ai`) |
| POST | `/v1/segment` | Jina segmenter (`segment.jina.ai`) |
| POST | `/v1/moderations` | OpenAI Moderations |
| GET | `/v1/models` | OpenAI |
| POST | `/v1/messages/count_tokens` | Anthropic |
| GET | `/v1beta/models` | Gemini |
| POST | `/v1beta/models/{...path}` | Gemini generateContent |
| POST | `/v1/api/chat` | Ollama |
| GET | `/api/v1/vscode/{token}/` | OpenAI alias za katalog |
| GET | `/api/v1/vscode/{token}/models` | OpenAI alias za modele |
| POST | `/api/v1/vscode/{token}/chat/completions` | OpenAI tokenizovani alias |
| POST | `/api/v1/vscode/{token}/responses` | OpenAI Responses tokenizovani alias |
| POST | `/api/v1/vscode/{token}/api/chat` | Ollama tokenizovani alias |
| GET | `/api/v1/vscode/{token}/api/tags` | Ollama tags tokenizovani alias |
Svi POST ruteri prate isti oblik: `Bearer your-api-key` + Zod-validirano JSON telo (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema`, itd., vidi `src/shared/validation/schemas.ts`). Prilikom neuspešne validacije šeme vraća se 4xx.
Za klijente koji ne mogu da dodaju `Authorization: Bearer ...`, OmniRoute takođe prihvata API ključeve u URL-u, bilo putem query-string kompatibilnosti (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) ili putem namenskih `/api/v1/vscode/{token}/...` endpointa dokumentovanih ispod.
```bash
# Rerank
POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }
# Jina klasifikacija (Foundation API akreditivi)
POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }
# Jina segmenter
POST /v1/segment { "content": "...", "return_chunks": true }
# Jina pretraga (s.jina.ai; aliasi provajdera: jina-search, jina-ai, jina)
POST /v1/search { "query": "...", "provider": "jina-search" }
# Moderacije
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }
# TTS — vraća audio/mpeg (ili traženi format) telo
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }
# Izmena slike (multipart)
POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png
# Generisanje video/muzičkog sadržaja (id modela sa prefiksom provajdera)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." }
```
### Namenski ruteri za provajdere
```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-компатибилни endpoint за фајлове за batch input/output и upload фајлова по сврси (purpose).
| Метод | Путања | Описание |
| ------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| POST | `/v1/files` | Отпремање фајла (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — максимум 512 MiB |
| GET | `/v1/files` | Листа фајлова за аутентификован API кључ |
| GET | `/v1/files/[id]` | Преузимање метаподатака фајла |
| DELETE | `/v1/files/[id]` | Брисање фајла |
| GET | `/v1/files/[id]/content` | Стримовање сирових података фајла |
**Аутентификација:** Bearer API кључ — фајлови су ограничени по API кључу преко `getApiKeyRequestScope`.
---
## Batches API
OpenAI-компатибилна batch обрада.
| Метод | Путања | Описание |
| ------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| POST | `/v1/batches` | Креирање batch-а — тело захтева се валидира преко `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) |
| GET | `/v1/batches` | Листа batch-ова |
| GET | `/v1/batches/[id]` | Преузимање статуса batch-а + `request_counts` |
| DELETE | `/v1/batches/[id]` | Брисање завршеног/неуспелог batch-а |
| POST | `/v1/batches/[id]/cancel` | Отказивање batch-а у току |
**Аутентификација:** Bearer API кључ. Batch-ови су ограничени по API кључу.
---
## Search API
Апстракција провајдера за веб претрагу (Tavily, Brave, Exa, Serper, итд.).
| Метод | Путања | Описание |
| ----- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| GET | `/v1/search` | Листа конфигурисаних провајдера претраге + могућности |
| POST | `/v1/search` | Извршавање упита за претрагу — тело захтева се валидира преко `v1SearchSchema`, подржава кеширање/спајање захтева (coalescing) |
| GET | `/v1/search/analytics` | Статистика по провајдеру (број погодака/латенција/кеш) |
**Аутентификација:** Bearer API кључ (`extractApiKey` + `isValidApiKey`). Политика претраге се примењује преко `enforceApiKeyPolicy`.
---
## Web Fetch API
Izvlačenje sadržaja sa URL-a preko konfigurisanog web-fetch provajdera (Firecrawl, Jina
Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).
| Metod | Putanja | Opis |
| ----- | --------------- | --------------------------------------------------------------------- |
| POST | `/v1/web/fetch` | Preuzimanje/scraping URL-a — telo validirano preko `v1WebFetchSchema` |
**Autentifikacija:** Bearer API ključ (`extractApiKey` + `isValidApiKey`). Politika se sprovodi preko `enforceApiKeyPolicy`.
**Fallback svestan kvota (#8297):** kada nije naveden eksplicitan `provider`, skup
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) se
obilazi u fiksnom
prioritetnom redosledu (fill-first) — provajder koji je ograničen brzinom, ali je konfigurisan, se preskače
umesto da se zahtev prekine, a otkazivi/kvota-povezani otpremni neuspeh
(HTTP 429 uvek; 402/403 za besplatne planove Firecrawl/Tavily/TinyFish tipa kvote —
ne za Jina Reader, i nikad za običan 400 loš zahtev) prelazi na
sledećeg neisprobanog provajdera sa akreditivima u trenutku zahteva. Kada su svi provajderi u
skupu iscrpljeni, endpoint vraća jedinstven `429` (sa `Retry-After`
zaglavljem) umesto prethodnog generičkog `400`. Kada je zahtevan eksplicitan `provider`,
**nema** tihog fallback-a — eksplicitni provajder koji je ograničen brzinom ili ne radi
prikazuje svoju sopstvenu grešku (`429` ako je ograničen brzinom, inače status sa strane provajdera).
---
## WebSocket Streaming
```bash
GET /v1/ws?handshake=1
```
Validira WebSocket upgrade handshake i vraća primere poruka žičnog protokola (`request`, `cancel`). Stvarni WS okviri se obrađuju putem ugrađenog WS servera izvan Next.js tabele ruta.
**Autentifikacija:** Bearer API ključ prilikom handshake-a.
### Responses API preko WebSocket-a (samo codex)
```bash
# Isti host:port kao HTTP API (podrazumevano 20128); upgrade-ujte konekciju:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (ili: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")
# Prvi okvir MORA biti response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```
Responses-API-preko-WebSocket-a proxy je povezan **isključivo na `codex`** (ChatGPT
backend). On sluša na istom portu kao API/dashboard na putanjama `/v1/responses`,
`/responses`, i `/api/v1/responses`. Na prvi `response.create` okvir on
autentifikuje + priprema preko internog `codex-responses-ws` bridge-a, bira
codex OAuth konekciju, i tunelira do `wss://chatgpt.com/backend-api/codex/responses`
preko `wreq-js` transporta. **Modeli koji nisu codex se odbijaju** (`codex_ws_provider_required`).
Za rutiranje sa deljenjem kvote koristite `model: "qtSd/<group>/codex/<model>"`. Implementirano u
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`.
**Autentifikacija:** Bearer API ključ prilikom handshake-a. Ugrađeni HTTP server (`server-ws.mjs`)
mora biti aktivna ulazna tačka (jeste, po podrazumevanoj vrednosti, kada `app/server-ws.mjs` postoji).
#### ID modela: koristite goli ChatGPT id (bez `codex/` prefiksa)
OpenAI **Codex CLI** validira naziv modela na strani klijenta kada je
`supports_websockets = true` i **odbija id-ove sa prefiksom provajdera** kao
`codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with
a ChatGPT account`). Pošaljite **goli** id (npr. `gpt-5.5`). OmniRoute-ov bridge je
samo za codex, tako da ponovo razrešava goli id kao codex model
(`resolveCodexWsModelInfo`) prije tuneliranja ka nadređenom serveru — čak i ako bi
goli `gpt-5.5` inače usmerio ka drugom provajderu preko HTTP-a.
#### Konfigurisanje OpenAI Codex CLI-ja
Usmerite Codex CLI ka OmniRoute-u dodavanjem prilagođenog provajdera sa WebSocket
podrškom u `~/.codex/config.toml` (koristite odvojeni `CODEX_HOME` da izbegnete diranje
postojeće konfiguracije):
```toml
model = "gpt-5.5" # goli id — NE "codex/gpt-5.5"
model_provider = "omniroute"
[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1" # bez pratećeg slash-a; WS URL se izvodi (koristite https/wss u produkciji)
wire_api = "responses" # jedina podržana vrednost od februara 2026
supports_websockets = true # omogućava Responses-over-WS transport
env_key = "OMNIROUTE_API_KEY" # sadrži OmniRoute API ključ (Bearer)
```
```bash
export OMNIROUTE_API_KEY=sk-... # OmniRoute API ključ (bilo koji ključ ako je REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
```
CLI podiže `base_url + /responses` na WebSocket i OmniRoute to tunelira
do izabrane codex OAuth konekcije. Validirano end-to-end na lokalnom
serveru: ChatGPT vraća `codex.rate_limits` + `response.created` i strimuje
kompletiranje.
---
## Извештавање о квотама и проблемима
| Метод | Путања | Опис |
| ----- | ------------------- | --------------------------------------------------------------------------------------- |
| GET | `/v1/quotas/check` | Претходна валидација квоте за `provider` + `accountId` пре издавања регистрованог кључа |
| POST | `/v1/issues/report` | Пријава грешке у квоти/издавању кључа на GitHub (захтева `GITHUB_ISSUES_REPO` + токен) |
**Аутентикација:** Bearer API кључ (`isAuthenticated`).
---
## Самостално коришћење (`/api/usage/om-usage`)
Сваки API кључ може да прочита **сопствену** потрошњу и квоте — без потребе за управљачком ауторизацијом. Ово је крајња тачка коју
клијент (CLI, панел OmniCopilot) користи да прикаже власнику кључа његову потрошњу.
```bash
# Текстуални облик (историјски уговор — обичан текст за терминал)
curl -H "Authorization: Bearer <your-api-key>" \
http://localhost:20128/api/usage/om-usage
# Структурирани облик — оно што конзумира UI
curl -H "Authorization: Bearer <your-api-key>" \
"http://localhost:20128/api/usage/om-usage?format=json"
```
Кључ мора имати укључено **`allowUsageCommand`** (подразумевано искључено — менаџер API кључева на контролној табли то укључује по кључу).
Без тога, крајња тачка одговара са `403`.
`?format=json` враћа дискриминовани облик, тако да позивалац никада не чита поље са подацима из одбијеног одговора. У случају успеха:
```jsonc
{
"allowed": true,
// присутно само када је кључ активирао ограничења потрошње по кључу (дневно/недељно у USD):
"personal": {
"dailySpentUsd": 1.25,
"dailyLimitUsd": 5,
"dailyResetAtIso": "…",
"weeklySpentUsd": 8,
"weeklyLimitUsd": 20,
"weeklyResetAtIso": "…" /* … */,
},
// снимак квоте изабраног провајдера, или null ако још ништа није кеширано:
"provider": {
"connectionId": "…",
"provider": "claude",
"plan": "…",
"quotas": {/* … */},
},
// снимак сваке везе, тако да UI може приказати више провајдера један поред другог:
"providers": [
{ "connectionId": "…", "provider": "claude" /* … */ },
{ "provider": "codex" /* … */ },
],
}
```
У случају одбијања (`401` погрешан кључ / `403` није дозвољено), исти route враћа
`{ "allowed": false, "error": { "message": "…" } }` — присутно, али празно `personal`/`provider`
(кључ је дозвољен, али још ништа није научено) представља другачије стање од одбијања, и само JSON облик
разликује ова два случаја.
**Аутентикација:** сопствени Bearer API кључ позиваоца, валидиран помоћу `isValidApiKey` — ово _није_ управљачка
површина (`/api/keys/…`), која остаје иза `requireManagementAuth`.
---
## Семантички кеш
```bash
# Добијање статистике кеша
GET /api/cache/stats
# Брисање свих кешева
DELETE /api/cache/stats
```
Пример одговора:
```json
{
"semanticCache": {
"memorySize": 42,
"memoryMaxSize": 500,
"dbSize": 128,
"hitRate": 0.65
},
"idempotency": {
"activeKeys": 3,
"windowMs": 5000
}
}
```
### Утицај на кашњење
Погодак (HIT) семантичког кеша служи одговор из кеша **без позива ка upstream-у**,
тако да пријављено `X-OmniRoute-Response-Latency` буде близу нуле
(без обзира на стварно upstream кашњење). Клијенти осетљиви на кашњење
(benchmarking, p50/p99 мониторинг) треба да провере
`X-OmniRoute-Cache-Latency` заглавље одговора:
| Вредност | Значење |
| ----------- | ---------------------------------------------------------------- |
| `synthetic` | Одговор је послужен из кеша; кашњење није стварно upstream време |
| _(одсутно)_ | Одговор из стварног upstream позива |
### Заобилажење кеша по кључу
API кључеви могу да искључе читање из семантичког кеша путем `cacheDefaultMode`:
| Вредност | Понашање |
| -------- | -------------------------------------------------------- |
| `legacy` | Нормално понашање кеша (подразумевано) |
| `bypass` | Потпуно прескочи претрагу кеша; увек контактира upstream |
Подешава се приликом креирања кључа (`POST /api/keys`) или ажурирања (`PATCH /api/keys/[id]`):
```json
{ "cacheDefaultMode": "bypass" }
```
### Заобилажење по захтеву
Сваки захтев може заобићи кеш без обзира на подешавања кључа:
```
X-OmniRoute-No-Cache: true
```
---
## Dashboard i upravljanje
Rute za upravljanje (`/api/*` osim javne prijave/autentikacije) **nisu** autorizovane pomoću običnih API ključeva za inferenciju. Porodice akreditiva, opsezi i curl primeri: [Autentikacija za upravljanje](../guides/MANAGEMENT-AUTH.md).
### Autentikacija
| Endpoint | Metod | Opis |
| ----------------------------- | ------- | --------------------------------- |
| `/api/auth/login` | POST | Prijava |
| `/api/auth/logout` | POST | Odjava |
| `/api/settings/require-login` | GET/PUT | Uključi/isključi obaveznu prijavu |
### Upravljanje provajderima
| Endpoint | Metod | Opis |
| ---------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------ |
| `/api/providers` | GET/POST | Prikaz liste / kreiranje provajdera |
| `/api/providers/[id]` | GET/PUT/DELETE | Upravljanje provajderom |
| `/api/providers/[id]/test` | POST | Testiranje konekcije provajdera |
| `/api/providers/[id]/models` | GET | Prikaz modela provajdera |
| `/api/providers/validate` | POST | Validacija konfiguracije provajdera |
| `/api/providers/bulk` | POST | Masovno dodavanje API ključeva za JEDNOG provajdera |
| `/api/providers/import` | POST | Uvoz heterogene LISTE provajdera iz parsiranog CSV/JSON fajla (#6836); rezultati delimičnog neuspeha po redu |
| `/api/provider-nodes*` | Različiti | Upravljanje čvorovima provajdera |
| `/api/provider-models` | GET/POST/PATCH/DELETE | Prilagođeni modeli (dodavanje, ažuriranje, sakrivanje/prikazivanje, brisanje) |
### OAuth toka
| Endpoint | Metod | Opis |
| -------------------------------- | --------- | ------------------------------ |
| `/api/oauth/[provider]/[action]` | Različiti | OAuth specifičan za provajdera |
### Rutiranje i konfiguracija
| Endpoint | Metod | Opis |
| --------------------- | --------- | ------------------------------- |
| `/api/models/alias` | GET/POST | Aliasi modela |
| `/api/models/catalog` | GET | Svi modeli po provajderu i tipu |
| `/api/combos*` | Različiti | Upravljanje kombinacijama |
| `/api/keys*` | Različiti | Upravljanje API ključevima |
| `/api/pricing` | GET | Cene modela |
### Upotreba i analitika
| Endpoint | Metod | Opis |
| -------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history` | GET | Istorija upotrebe |
| `/api/usage/logs` | GET | Logovi upotrebe |
| `/api/usage/request-logs` | GET | Logovi na nivou zahteva |
| `/api/usage/[connectionId]` | GET | Upotreba po konekciji |
| `/api/usage/token-limits` | GET/POST/DELETE | Budžeti ograničenja tokena po API ključu |
| `/api/usage/model-latency-stats` | GET | Kumulativna agregacija kašnjenja po provajderu/modelu (prosek/p50/p95/p99, stopa uspeha); filteri: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) |
| `/api/usage/cache-health` | GET | Sažetak zdravlja keša za prompt preko `call_logs` — odnos pisanja/čitanja, distribucija veličine pisanja p50/p90/p99, koncentracija intenzivnih pisanja, podela po modelu, i ocena `healthy`/`degraded`/`thrash`/`no-data`; query parametri `range` (`1h`\|`24h`\|`7d`\|`30d`, podrazumevano `24h`) i opcioni `model` (#8827) |
### Podešavanja
| Endpoint | Metod | Opis |
| ------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings` | GET/PUT/PATCH | Opšta podešavanja |
| `/api/settings/proxy` | GET/PUT | Konfiguracija mrežnog proksija |
| `/api/settings/proxy/test` | POST | Testiranje konekcije proksija |
| `/api/settings/ip-filter` | GET/PUT | Lista dozvoljenih/blokiranih IP adresa |
| `/api/settings/thinking-budget` | GET/PUT | Režim prepisivanja **zahteva** za razmišljanje/rezonovanje (passthrough / auto-strip / custom / adaptive). Nezavisno od kompresije. Pogledajte [THINKING_BUDGET.md](../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 | Brisanje redova logova zahteva i lokalnih artefakata call-log |
### Kontekst i kompresija
| Endpoint | Metod | Opis |
| -------------------------------------- | -------------- | ------------------------------------------------------------------------------------ |
| `/api/compression/preview` | POST | Pregled off/lite/standard/aggressive/ultra/RTK/stacked kompresije |
| `/api/compression/language-packs` | GET | Prikaz dostupnih Caveman jezičkih paketa |
| `/api/compression/rules` | GET | Prikaz metapodataka Caveman pravila |
| `/api/context/caveman/config` | GET/PUT | Alias za Caveman specifična podešavanja |
| `/api/context/rtk/config` | GET/PUT | RTK specifična podešavanja, uključujući prilagođene filtere i čuvanje sirovog izlaza |
| `/api/context/rtk/filters` | GET | Katalog RTK filtera i dijagnostika prilagođenih filtera |
| `/api/context/rtk/test` | POST | Izvršavanje RTK pregleda/testa nad tekstualnim payload-om |
| `/api/context/rtk/raw-output/[id]` | GET | Čitanje sačuvanog redaktovanog sirovog izlaza po pointer id |
| `/api/context/combos` | GET/POST | Lista/kreiranje kombinacija kompresije |
| `/api/context/combos/[id]` | GET/PUT/DELETE | Detalji/ažuriranje/brisanje kombinacije kompresije |
| `/api/context/combos/[id]/assignments` | GET/PUT | Dodela kombinacija kompresije rutirajućim kombinacijama |
| `/api/context/analytics` | GET | Alias za analitiku kompresije |
### Nadzor
| Endpoint | Metod | Opis |
| ------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions` | GET | Praćenje aktivnih sesija |
| `/api/rate-limits` | GET | Ograničenja stope po nalogu |
| `/api/monitoring/health` | GET | Provera zdravlja + sažetak provajdera (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) |
| `/api/cache/stats` | GET/DELETE | Statistike keša / brisanje |
| `/api/modality-bridge/stats` | GET | Memorijski `attempts`, uspesi/`bridged`, neuspesi, hits keša, `totalLatencyMs`, `latencySamples`, `averageLatencyMs` izračunat po uzorku, i vreme poslednje upotrebe (resetuje se pri restartu; management autentikacija) |
| `/api/modality-bridge/video/runtime` | GET | Striktna provera pouzdanog loopback-a pre management autentikacije/provere; sanitizovana dostupnost i verzije FFmpeg/ffprobe (no-store) |
| `/api/modality-bridge/video/extract` | POST | Interni autentikovani pouzdani loopback bajt-broker; 50 MiB ulaz, ograničen red čekanja/32 MiB izlaz, `503` kapacitet, `499` prekid konekcije, `504` prekoračenje vremena; nije javni API za upload |
### Rezervna kopija i izvoz/uvoz
| Endpoint | Metod | Opis |
| --------------------------- | ----- | -------------------------------------------------------- |
| `/api/db-backups` | GET | Prikaz dostupnih rezervnih kopija |
| `/api/db-backups` | PUT | Kreiranje ručne rezervne kopije |
| `/api/db-backups` | POST | Vraćanje iz specifične rezervne kopije |
| `/api/db-backups/export` | GET | Preuzimanje baze podataka kao .sqlite fajl |
| `/api/db-backups/import` | POST | Otpremanje .sqlite fajla za zamenu baze podataka |
| `/api/db-backups/exportAll` | GET | Preuzimanje kompletne rezervne kopije kao .tar.gz arhive |
### Sinhronizacija u oblaku
| Endpoint | Metod | Opis |
| ---------------------- | --------- | --------------------------------- |
| `/api/sync/cloud` | Različiti | Operacije sinhronizacije u oblaku |
| `/api/sync/initialize` | POST | Inicijalizacija sinhronizacije |
| `/api/cloud/*` | Različiti | Upravljanje oblakom |
### Tuneli
| Endpoint | Metod | Opis |
| -------------------------- | ----- | -------------------------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET | Čitanje statusa instalacije/rada Cloudflare Quick Tunnel za dashboard |
| `/api/tunnels/cloudflared` | POST | Uključivanje ili isključivanje Cloudflare Quick Tunnel (`action=enable/disable`) |
| `/api/tunnels/ngrok` | GET | Čitanje statusa rada ngrok Tunnel za dashboard |
| `/api/tunnels/ngrok` | POST | Uključivanje ili isključivanje ngrok Tunnel (`action=enable/disable`) |
### CLI alati
| Endpoint | Metod | Opis |
| ---------------------------------- | ----- | --------------------- |
| `/api/cli-tools/claude-settings` | GET | Status Claude CLI-a |
| `/api/cli-tools/codex-settings` | GET | Status Codex CLI-a |
| `/api/cli-tools/droid-settings` | GET | Status Droid CLI-a |
| `/api/cli-tools/openclaw-settings` | GET | Status OpenClaw CLI-a |
| `/api/cli-tools/runtime/[toolId]` | GET | Generički CLI runtime |
CLI odgovori uključuju: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
### ACP agenti
| Endpoint | Metod | Opis |
| ----------------- | ------ | ----------------------------------------------------------------------- |
| `/api/acp/agents` | GET | Prikaz svih detektovanih agenata (ugrađenih + prilagođenih) sa statusom |
| `/api/acp/agents` | POST | Dodavanje prilagođenog agenta ili obnavljanje keša detekcije |
| `/api/acp/agents` | DELETE | Uklanjanje prilagođenog agenta preko `id` query parametra |
GET odgovor uključuje `agents[]` (id, name, binary, version, installed, protocol, isCustom) i `summary` (total, installed, notFound, builtIn, custom).
### Otpornost i ograničenja stope
| Endpoint | Metod | Opis |
| --------------------------------- | --------- | ---------------------------------------------------------------------------------------------------- |
| `/api/resilience` | GET/PATCH | Prikaz/ažuriranje reda čekanja zahteva, hlađenja konekcije, provider breaker-a i podešavanja čekanja |
| `/api/resilience/reset` | POST | Resetovanje circuit breaker-a provajdera |
| `/api/resilience/model-cooldowns` | GET | Prikaz aktivnih zaključavanja po (provajder, konekcija, model), sortirano po preostalom vremenu |
| `/api/resilience/model-cooldowns` | DELETE | Brisanje zaključavanja modela — telo `{provider, model}` ili `{all: true}` za brisanje svega |
| `/api/rate-limits` | GET | Status ograničenja stope po nalogu |
| `/api/rate-limit` | GET | Globalna konfiguracija ograničenja stope |
> Sve četiri `/api/resilience/*` rute zahtevaju **management autentikaciju** (`requireManagementAuth`). Pogledajte [Otpornost (proširena)](#resilience-extended) za potpuni pregled razlike između provider breaker-a, hlađenja konekcije i zaključavanja modela.
### Evaluacije
| Endpoint | Metod | Opis |
| ------------ | -------- | -------------------------------------------------- |
| `/api/evals` | GET/POST | Prikaz evaluacionih setova / pokretanje evaluacije |
### Politike
| Endpoint | Metod | Opis |
| --------------- | --------------- | -------------------------------- |
| `/api/policies` | GET/POST/DELETE | Upravljanje politikama rutiranja |
### Usklađenost
| Endpoint | Metod | Opis |
| --------------------------- | ----- | ---------------------------------------- |
| `/api/compliance/audit-log` | GET | Log revizije usklađenosti (poslednjih N) |
### v1beta (kompatibilno sa Gemini)
| Endpoint | Metod | Opis |
| -------------------------- | ----- | --------------------------------- |
| `/v1beta/models` | GET | Prikaz modela u Gemini formatu |
| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint |
Ovi endpointi oponašaju format Gemini API-ja za klijente koji zahtevaju nativnu kompatibilnost sa Gemini SDK-om.
### Interni / sistemski API-jevi
| Endpoint | Metod | Opis |
| ------------------------ | ----- | -------------------------------------------------------------------- |
| `/api/init` | GET | Provera inicijalizacije aplikacije (koristi se pri prvom pokretanju) |
| `/api/tags` | GET | Ollama-kompatibilne oznake modela (za Ollama klijente) |
| `/api/restart` | POST | Pokretanje graciozanog restarta servera |
| `/api/shutdown` | POST | Pokretanje graciozanog isključivanja servera |
| `/api/system/env/repair` | POST | Popravka OAuth promenljivih okruženja provajdera |
> **Napomena:** Ovi endpointi se koriste interno u sistemu ili za kompatibilnost sa Ollama klijentima. Obično ih ne pozivaju krajnji korisnici.
### Popravka OAuth okruženja _(v3.6.1+)_
```bash
POST /api/system/env/repair
Content-Type: application/json
{
"provider": "claude-code"
}
```
Popravlja nedostajuće ili oštećene OAuth promenljive okruženja za određenog provajdera. Vraća:
```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"
}
```
---
## Транскрипција аудио записа
```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
```
Транскрибујте аудио фајлове коришћењем било ког конфигурисаног STT провајдера. Први сегмент путање бира native провајдера (`openai/…`, `deepgram/…`). Gateway-и који реекспортују модел другог вендора користе квалификовани id
(`openrouter/deepgram/nova-3`).
**Захтев:**
```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"
```
**Одговор:**
```json
{
"text": "Hello, this is the transcribed audio content.",
"task": "transcribe",
"language": "en",
"duration": 12.5
}
```
**Примери id-ова модела:** `openai/whisper-1` (захтева OpenAI кључ),
`openrouter/deepgram/nova-3` (захтева OpenRouter кључ),
`deepgram/nova-3` (захтева native Deepgram кључ). Обичан
`deepgram/nova-3` захтев **не** користи OpenRouter.
**Подржани формати:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
---
## Ollama компатибилност
За клијенте који користе Ollama-ов API формат:
```bash
# Chat endpoint (Ollama формат)
POST /v1/api/chat
# Листа модела (Ollama формат)
GET /api/tags
```
Захтеви се аутоматски преводе између Ollama и интерних формата.
## Tokenized VS Code / Headerless алијаси
Користите ове алијасе када интеграција не може да убаци `Authorization` заглавље и потребно је да API кључ буде уграђен у base URL.
```bash
# OpenAI-style алијас за каталог
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models
# OpenAI-style chat алијаси
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses
# Ollama-style алијаси
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```
Пример:
```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"}]}'
```
Напомене:
- Tokenized алијаси користе исте handler-е као `/v1/*` и `/api/tags`; облици одговора остају идентични.
- Дајте приоритет `Authorization: Bearer ...` заглављу кад год клијент подржава custom заглавља.
- Токени засновани на URL-у могу се појавити у reverse-proxy логовима, историји браузера и телеметрији изван OmniRoute. Третирајте их као опцију компатибилности, а не подразумевани режим аутентикације.
---
## Телеметрија
```bash
# Преузми сажетак телеметрије кашњења (p50/p95/p99 по провајдеру)
GET /api/telemetry/summary
```
**Одговор:**
```json
{
"providers": {
"claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
"github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
}
}
```
---
## Буџет
```bash
# Преузми статус буџета за све API кључеве
GET /api/usage/budget
# Постави или ажурирај буџет
POST /api/usage/budget
Content-Type: application/json
{
"apiKeyId": "key-123",
"dailyLimitUsd": 5.00,
"weeklyLimitUsd": 30.00,
"monthlyLimitUsd": 100.00,
"warningThreshold": 0.8,
"resetInterval": "monthly"
}
```
> **Напомене о схеми** (`setBudgetSchema`): `apiKeyId` је обавезан; бар једно од `dailyLimitUsd`, `weeklyLimitUsd` или `monthlyLimitUsd` мора бити веће од нуле. Опциона поља: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Стари облик `{keyId, limit, period}` враћа `400 Bad Request`.
## Ограничења токена
Буџети **токена** по API кључу (различити од USD буџета описаног изнад). Спроводе се директно на путу обраде захтева: када тренутна потрошња у оквиру прозора достигне лимит кључа, захтеви се одбијају уз `429 Too Many Requests`. Ограничења могу бити везана за конкретан `model`, `provider`, или примењена `global`но на цео кључ; када више ограничења одговара захтеву, побеђује најрестриктивније.
```bash
# Приказ ограничења токена за кључ (укључује живу потрошњу у прозору)
GET /api/usage/token-limits?apiKeyId=key-123
# Креирање или ажурирање ограничења токена
POST /api/usage/token-limits
Content-Type: application/json
{
"apiKeyId": "key-123",
"scopeType": "model",
"scopeValue": "openai/gpt-4o",
"tokenLimit": 1000000,
"resetInterval": "monthly",
"enabled": true
}
# Брисање ограничења токена по id-у
DELETE /api/usage/token-limits?id=tl-abc
```
> **Напомене о шеми** (`setTokenLimitSchema`): `apiKeyId` и `scopeType` (`model` | `provider` | `global`) су обавезни. `scopeValue` је обавезан осим ако је `scopeType` `global` (нпр. id модела за `model` опсег, id провајдера за `provider` опсег). `tokenLimit` мора бити позитиван цео број (коерција из стринга). Опционо: `id` (изостави за креирање, наведи за ажурирање), `resetInterval` (`daily` | `weekly` | `monthly`, подразумевано `monthly`), `resetTime` (`HH:MM`), `enabled` (подразумевано `true`). `GET` одговори обогаћују свако ограничење пољима `tokensUsed`, `remaining`, `windowStart`, `periodStartAt` и `nextResetAt`. Ово је крајња тачка управљачке класе (аутентикација се централно спроводи кроз authz канал).
## Обрада захтева
1. Клијент шаље захтев на `/v1/*`
2. Route handler позива `handleChat`, `handleEmbedding`, `handleAudioTranscription`, или `handleImageGeneration`
3. Модел се разрешава (директан provider/model или alias/combo)
4. Креденцијали се бирају из локалне базе уз филтрирање доступности налога
5. За chat: `handleChatCore` провера семантички/потписни кеш и разрешава подешавања компресије за combo
6. Проактивна компресија се извршава пре превода за провајдера када је укључена (`lite`, Caveman, RTK, или наслагано)
7. Извршилац провајдера шаље upstream захтев
8. Одговор се преводи назад у формат клијента (chat) или враћа непромењен (embeddings/images/audio)
9. Записују се потрошња, аналитика компресије и логови захтева
10. Fallback се примењује на грешке према правилима combo-а
Потпуна референца архитектуре: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)
---
## Управљање Combo-има
Комбинације рутирања на вишем нивоу (већ сумиране под `/api/combos*`) могу такође бити мапиране 1:1 из шаблона id-а модела, дозвољавајући транспарентно преусмеравање id-а модела у OpenAI стилу на combo.
| Метод | Путања | Опис |
| ------ | -------------------------------- | --------------------------------------------------------------------------------- |
| GET | `/api/model-combo-mappings` | Приказ свих мапирања модел→combo |
| POST | `/api/model-combo-mappings` | Креирање мапирања — тело: `{pattern, comboId, priority?, enabled?, description?}` |
| GET | `/api/model-combo-mappings/[id]` | Преузимање једног мапирања |
| PUT | `/api/model-combo-mappings/[id]` | Ажурирање поља постојећег мапирања |
| DELETE | `/api/model-combo-mappings/[id]` | Уклањање мапирања |
**Аутентикација:** управљачка сесија/API кључ (`requireManagementAuth`).
---
## Webhooks
Odlazne webhook pretplate za OmniRoute događaje (završetak zahteva, potrošnja kvote, rotacija ključeva, itd.).
| Metod | Putanja | Opis |
| ------ | ------------------------- | --------------------------------------------------------------------- |
| GET | `/api/webhooks` | Lista webhook-ova (tajni ključevi su maskirani u `<prefix>...`) |
| POST | `/api/webhooks` | Kreira webhook — telo: `{url, events?: ["*"], secret?, description?}` |
| GET | `/api/webhooks/[id]` | Preuzima webhook |
| PUT | `/api/webhooks/[id]` | Ažurira url/events/secret/description |
| DELETE | `/api/webhooks/[id]` | Uklanja webhook |
| POST | `/api/webhooks/[id]/test` | Šalje test payload na webhook URL i vraća status isporuke |
**Autentikacija:** management sesija/API ključ (`requireManagementAuth`).
---
## Registrovani ključevi (automatsko upravljanje)
Koristi ga podsistem za automatsko upravljanje ključevima za izdavanje i rotaciju API ključeva prema podržavajućem provajderu/nalogu, sa dnevnim/satnim kvotama.
| Metod | Putanja | Opis |
| ------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/registered-keys` | Lista registrovanih ključeva (samo maskirani prefiks) |
| POST | `/api/v1/registered-keys` | Izdaje novi registrovani ključ — telo: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Vraća sirovi ključ **jednom**. Vraća `429` u slučaju odbijanja usled kvote. |
| GET | `/api/v1/registered-keys/[id]` | Preuzima metapodatke registrovanog ključa (bez sirovog materijala) |
| DELETE | `/api/v1/registered-keys/[id]` | Opoziva registrovani ključ |
| POST | `/api/v1/registered-keys/[id]/revoke` | Eksplicitna krajnja tačka za opoziv (isti efekat kao DELETE) |
**Autentikacija:** Bearer API ključ (`isAuthenticated`). Pogledajte i `/v1/quotas/check` i `/v1/issues/report`.
---
## Протокол агената
Задаци облак-агента (Claude Code, Codex Cloud, OpenHands, итд.) који се извршавају удаљено у име корисника OmniRoute.
| Метод | Путања | Опис |
| ------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/agents/tasks` | Листа задатака — опционо `?provider=`, `?status=`, `?limit=` (1–500, подразумевано 50) |
| POST | `/api/v1/agents/tasks` | Креирање задатка — тело валидирано преко `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Враћа `201` са омотом задатка |
| DELETE | `/api/v1/agents/tasks?id=...` | Брисање задатка |
| GET | `/api/v1/agents/tasks/[id]` | Читање задатка — синхронизовано освежава статус са надлежног облак-агента када је постављен `external_id` |
| POST | `/api/v1/agents/tasks/[id]` | Дискриминисана акција: `{action: "approve"}`, `{action: "message", message}`, или `{action: "cancel"}` |
| DELETE | `/api/v1/agents/tasks/[id]` | Брисање конкретног задатка по id-у |
> **Аутентификација:** обавезна управљачка аутентификација на свакој методи (`requireCloudAgentManagementAuth`). Пре верзије v3.8.0 ови позиви су били неаутентификовани — погледајте commit `588a0333` за прекидну промену.
```bash
# Креирање облак-задатка за Claude Code
curl -X POST http://localhost:20128/api/v1/agents/tasks \
-H "Authorization: Bearer your-management-key" \
-H "Content-Type: application/json" \
-d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'
```
---
## Управљачки проксији
Одлазни HTTP(S)/SOCKS проксији који се могу доделити провајдерима, налозима или глобално.
| Метод | Путања | Опис |
| ------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/management/proxies` | Листа проксија (уз `?id=` враћа један; уз `?id=&where_used=1` враћа граф доделa) |
| POST | `/api/v1/management/proxies` | Креирање проксија — тело валидирано преко `createProxyRegistrySchema` |
| PATCH | `/api/v1/management/proxies` | Ажурирање проксија — тело валидирано преко `updateProxyRegistrySchema` (захтева `id`) |
| DELETE | `/api/v1/management/proxies?id=...&force=1` | Брисање проксија (користите `force=1` за одвајање доделa) |
| GET | `/api/v1/management/proxies/assignments` | Листа доделa — може се филтрирати по `proxy_id`, `scope`, `scope_id`; проследите `resolve_connection_id=<id>` да разрешите активни проксy за везу |
| PUT | `/api/v1/management/proxies/assignments` | Додела — тело валидирано преко `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Чисти кеш дистрибутера |
| PUT | `/api/v1/management/proxies/bulk-assign` | Масовна додела — тело валидирано преко `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) |
| GET | `/api/v1/management/proxies/health?hours=24` | Агрегирано здравствено стање проксија (број успеха/неуспеха, латенција) у оквиру временског прозора |
**Аутентификација:** управљачка сесија/API кључ на свакој рути (`requireManagementAuth`).
> Рутe `POST /api/v1/management/proxies/[id]/assignments` и `POST /api/v1/management/proxies/[id]/health` из описа задатка опслужују равне (flat) руте `/assignments` и `/health` приказане изнад — у кодној бази не постоје подруте по id-у.
---
## Otpornost (proširena)
OmniRoute izlaže tri nezavisna mehanizma za privremene otkaze; upravljački krajnji punkti u nastavku omogućavaju operatorima da čitaju i preklapaju te mehanizme:
| Opseg | Skladištenje stanja | Čitanje | Resetovanje / brisanje |
| ------------------- | ------------------------------------------ | ----------------------------------------- | ------------------------------------------------------- |
| Provider breaker | `domain_circuit_breakers` + u memoriji | `/api/monitoring/health` | `POST /api/resilience/reset` |
| Connection cooldown | `rateLimitedUntil` na provider konekcijama | `/api/rate-limits`, `/api/providers/[id]` | (ponovo se aktivira lenjo; brisanje putem provider PUT) |
| Model lockout | Registar dostupnosti modela u memoriji | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` |
`PATCH /api/resilience` prihvata preklapanja provider breaker-a pod `providerBreaker.oauth` i `providerBreaker.apikey`. Svaki profil podržava `degradationThreshold`, `failureThreshold` i `resetTimeoutMs`; ista polja su izložena u Dashboard → Settings → Resilience.
```bash
# Brisanje jednog model lockout-a
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
-H "Cookie: auth_token=..." \
-H "Content-Type: application/json" \
-d '{"provider":"openai","model":"gpt-4o-mini"}'
# Brisanje svih lockout-ova
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
-H "Cookie: auth_token=..." \
-d '{"all":true}'
```
Kompletna konceptualna referenca i podrazumevane vrednosti breaker-a: pogledajte [`CLAUDE.md`](../../CLAUDE.md) → "Resilience Runtime State".
---
## Skills (Vештине)
Skill framework za proširivanje OmniRoute-a prilagođenim izvršnim handler-ima, uz integracije sa marketplace-om.
| Metod | Putanja | Opis |
| ------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/skills` | Listanje instaliranih skill-ova — moguće filtriranje preko `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, sa paginacijom |
| GET | `/api/skills/[id]` | Preuzimanje jednog skill-a |
| PUT | `/api/skills/[id]` | Ažuriranje skill-a (naziv, opis, mode, schema, handler, tags) |
| DELETE | `/api/skills/[id]` | Deinstaliranje skill-a |
| POST | `/api/skills/install` | Instaliranje skill-a iz sirovog manifesta — body: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` |
| GET | `/api/skills/executions` | Listanje nedavnih izvršavanja skill-ova (audit trag sa inputima/outputima/trajanjem) |
| GET | `/api/skills/marketplace?q=...` | Pretraga/popularna lista iz SkillsMP marketplace-a (zahteva podešavanje `skillsmpApiKey`) |
| POST | `/api/skills/marketplace/install` | Instaliranje skill-a po id-u sa SkillsMP-a |
| GET | `/api/skills/skillssh?q=&limit=` | Pretraga registra skills.sh |
| POST | `/api/skills/skillssh/install` | Instaliranje skill-a po id-u sa skills.sh |
**Autentifikacija:** upravljačka sesija/API ključ. Rute za pretragu marketplace-a prihvataju bilo upravljačku autentifikaciju bilo Bearer API ključ (`isAuthenticated`).
---
## Меморија
Трајна складишна јединица за конверзацијску/чињеничну меморију, ограничена по API кључу / сесији.
| Метод | Путања | Опис |
| ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/memory` | Листа меморија — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, са `offset/limit` или `page/limit` пагинацијом |
| POST | `/api/memory` | Креирање меморије — тело валидирано помоћу Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
| GET | `/api/memory/[id]` | Преузимање једне меморије |
| DELETE | `/api/memory/[id]` | Брисање меморије |
| GET | `/api/memory/health` | Здравствено стање подсистема меморије (повезаност са базом података, embeddings backend, статус векторског индекса) |
**Аутентификација:** управљачка сесија/API кључ (`requireManagementAuth`). Енумерација `type`: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (види `MemoryType` у `src/lib/memory/types.ts`).
---
## MCP сервер
OmniRoute долази са уграђеним Model Context Protocol сервером са 3 транспорта (stdio, SSE, streamable-http) и алаткама ограниченог опсега. Испод наведене крајње тачке контролне табле читају статус/audit податке и посредују (proxy) HTTP транспорте.
| Метод | Путања | Опис |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | Heartbeat, транспорт, статус повезаности, последњи позив, најкориснији алати, стопа успешности за 24ч |
| GET | `/api/mcp/tools` | Листа MCP алата са `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` |
| GET | `/api/mcp/sse` | Отвара SSE ток за SSE транспорт (враћа `503` ако је MCP онеспособљен или ако транспорт не одговара) |
| POST | `/api/mcp/sse` | Слање JSON-RPC оквира преко SSE транспорта |
| GET | `/api/mcp/stream` | Отвара SSE страну Streamable HTTP транспорта (поруке иницирање од сервера) |
| POST | `/api/mcp/stream` | Слање JSON-RPC оквира преко Streamable HTTP транспорта |
| DELETE | `/api/mcp/stream` | Завршава Streamable HTTP сесију |
| GET | `/api/mcp/audit` | Упит над audit логом — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | Агрегатне audit статистике (укупни бројеви, стопа успешности, просечно трајање, најкориснији алати) |
**Аутентификација:** транспорти `sse`/`stream` поштују MCP-специфичну аутентификациону површину (Bearer API кључ са `mcp` опсегом); руте `status`/`tools`/`audit*` су читљиве са контролне табле (без потребе за додатном аутентификацијом осим приступа домаћину контролне табле).
> Оба HTTP транспорта су контролисана поставкама `settings.mcpEnabled` и `settings.mcpTransport` — неусклађеност транспорта враћа `400`, а онеспособљено стање MCP-а враћа `503`.
---
## A2A сервер
OmniRoute излаже A2A (Agent-to-Agent) JSON-RPC 2.0 крајњу тачку плус REST омотач за инспекцију/употребу на контролној табли.
### JSON-RPC
```bash
POST /a2a
Authorization: Bearer your-api-key # опционо осим ако је постављен OMNIROUTE_API_KEY
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 1,
"method": "message/send",
"params": {
"skill": "smart-routing",
"messages": [{"role": "user", "content": "Route this coding task"}]
}
}
```
Подржани методи (сви условљени поставком `settings.a2aEnabled`):
| Метод | Опис |
| ---------------- | ---------------------------------------------------------------- |
| `message/send` | Синхроно извршавање skill-а; враћа `{task, artifacts, metadata}` |
| `message/stream` | Стриминг SSE извршавање истог скупа skill-ова |
| `tasks/get` | Преузимање задатка по `taskId` |
| `tasks/cancel` | Отказивање задатка по `taskId` |
Уграђени skill-ови: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.
### Agent Card
```bash
GET /.well-known/agent.json
```
Враћа јавну A2A agent картицу (назив, опис, могућности, каталог skill-ова, шему аутентикације) — кеширано јавно на 1h. Аутентикација није потребна.
### REST помагала
| Метод | Путања | Опис |
| ----- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/a2a/status` | A2A укључено + статистика задатака + кеширани резиме agent картице |
| GET | `/api/a2a/tasks` | Листа задатака — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
| POST | `/api/a2a/tasks` | (Није имплементирано као REST помагало — креира се преко JSON-RPC `message/send`) |
| GET | `/api/a2a/tasks/[id]` | Преузимање једног задатка |
| POST | `/api/a2a/tasks/[id]/cancel` | Отказивање задатка |
**Аутентикација:** REST помагала се извршавају без управљачке аутентикације (читљиво на контролној табли); JSON-RPC `/a2a` рута користи Bearer `OMNIROUTE_API_KEY` ако је конфигурисан.
---
## Cloud, Evals и Assess
| Метод | Путања | Опис |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | Верификује Bearer кључ и враћа маскиране конекције провајдера + алиасе модела за cloud sync клијенте |
| POST | `/api/cloud/credentials/update` | Ажурира шифроване креденцијале за провајдера синхронизованог путем cloud-а |
| POST | `/api/cloud/model/resolve` | Резолвује логички id модела у конкретан провајдер/модел користећи локалну табелу рутирања |
| GET | `/api/cloud/models/alias` | Листа алиасе модела изложене cloud sync-у |
| GET | `/api/assess` | Читање последњих категоризација процене (по провајдеру/моделу) |
| POST | `/api/assess` | Покретање процене — тело: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | Листа уграђених eval suite-ова + најновијих извршавања |
| POST | `/api/evals` | Покретање eval извршавања |
| POST | `/api/evals/suites` | Креирање прилагођеног eval suite-а — тело се валидира помоћу `evalSuiteSaveSchema` |
| GET | `/api/evals/suites/[id]` | Преузимање прилагођеног eval suite-а |
**Аутентикација:** `/api/cloud/auth` директно валидира Bearer кључ; остале руте `/api/cloud/*`, `/api/evals/*` и `/api/assess` захтевају управљачку сесију/API кључ. `/api/assess` POST користи `validateBody` са дискриминисаном унијом scope шеме.
---
## Управљање ACP (Agent Client Protocol)
као подпроцеси. Ови крајњи чворови (endpoints) управљају детекцијом ACP агента и
регистрацијом прилагођеног агента.
| Метод | Путања | Опис |
| ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/acp/agents` | Листа свих познатих CLI агената (уграђени + прилагођени) са статусом инсталације, верзијом, извршном датотеком |
| POST | `/api/acp/agents` | Регистрација прилагођеног ACP агента или освежавање кеша — тело: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` или `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | Уклањање прилагођеног ACP агента — упитни параметар: `?id=<agentId>` |
**Пример одговора** (`GET /api/acp/agents`):
```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
}
```
**Ауторизација:** Захтева менаџмент сесију (dashboard `auth_token` колачић) или
API кључ са менаџмент обимом (scope).
Погледајте [ACP оквир](../frameworks/ACP.md) за све детаље.
---
## Аналитика и осматрање (Observability)
Крајњи чворови за аналитику у реалном времену за праћење рутирања, компресије и
разноликости провајдера. Они покрећу странице `/dashboard/analytics/*`.
### Аналитика аутоматског рутирања
| Метод | Путања | Опис |
| ----- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/auto-routing` | Агрегатне статистике аутоматског рутирања: укупан број позива, дистрибуција стратегија, дистрибуција нивоа (tier), топ провајдери |
| GET | `/api/analytics/auto-routing?days=7` | Статистике у временском прозору (подразумевано 24ч) |
**Пример одговора**:
```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 }
]
}
```
### Аналитика компресије
| Метод | Путања | Опис |
| ----- | ---------------------------- | -------------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/compression` | Агрегатне статистике компресије: сачувани токени, проценат уштеде, дистрибуција режима, коришћење енгина |
**Пример одговора**:
```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
}
}
```
### Праћење разноликости провајдера
| Метод | Путања | Опис |
| ----- | -------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/diversity` | Праћење разноликости на основу Шенонове ентропије: спречава тачке појединачног квара мерењем распршености провајдера |
**Пример одговора**:
```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"]
}
```
**Ауторизација:** Захтева менаџмент сесију или API кључ са менаџмент обимом (scope).
---
## Admin операције
Ендпоинти доступни само администраторима за оперативно управљање.
| Method | Path | Description |
| ------ | ------------------------ | ----------------------------------------------------------------------------------------------------- |
| GET | `/api/admin/concurrency` | Читање тренутних ограничења конкурентности (глобалних + по провајдеру) |
| POST | `/api/admin/concurrency` | Ажурирање ограничења конкурентности — body: `{global?: number, perProvider?: Record<string, number>}` |
**Auth:** Захтева management сесију са admin scope.
---
## Управљање CLI алатима
Управљајте CLI алатима који се интегришу са OmniRoute (antigravity, chipotle, commandCode,
devin-cli, итд.). Погледајте [Provider Reference](./PROVIDER_REFERENCE.md) за потпуну листу.
| Method | Path | Description |
| ------ | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/cli-tools/all-statuses` | Статус свих CLI алата (инсталиран, верзија, последње виђен) |
| GET | `/api/cli-tools/status` | Детаљан статус за један CLI алат (`?tool=` query) |
| POST | `/api/cli-tools/apply` | Уписивање генерисане конфигурације алата (`dryRun` приказује преглед; `422` + `containerEphemeralTarget` када је контејнеризовано; `migration` бележи наслеђени Codex YAML) |
| GET | `/api/cli-tools/backups` | Листа резервних копија конфигурације CLI алата |
| POST | `/api/cli-tools/backups` | Креирање резервне копије свих конфигурација CLI алата |
| POST | `/api/cli-tools/backups` | Враћање: исти ендпоинт са `{tool, backupId}` у body-ју враћа ту резервну копију |
| GET | `/api/cli-tools/antigravity-mitm` | Статус antigravity MITM proxy-ja (CLI алат "antigravity-mitm") |
| POST | `/api/cli-tools/antigravity-mitm/alias` | Конфигурисање antigravity-mitm алиаса |
**Auth:** Захтева management сесију.
---
## Agent Skills
Управљајте вештинама AI агента (слично OpenAI-јевим custom GPT-овима, али за агенте).
| Method | Path | Description |
| ------ | ---------------------------- | ---------------------------------------------------------------------------------------------- |
| GET | `/api/agent-skills` | Листа свих agent skills (уграђених + прилагођених) |
| GET | `/api/agent-skills/[id]` | Преузимање конкретне agent skill-a |
| POST | `/api/agent-skills` | Креирање прилагођене agent skill-a — body: `{name, description, prompt, model?, temperature?}` |
| PUT | `/api/agent-skills/[id]` | Ажурирање прилагођене agent skill-a |
| DELETE | `/api/agent-skills/[id]` | Брисање прилагођене agent skill-a |
| GET | `/api/agent-skills/[id]/raw` | Преузимање sirovog prompt-a + metapodataka (без извршавања) |
| POST | `/api/agent-skills/generate` | AI генерисање нове skill-a на основу описа на природном језику |
**Auth:** Захтева management сесију или management-scoped API кључ.
---
## Управљање кешом
Управљање семантичким кешом и кешом закључивања.
| Метод | Путања | Опис |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| GET | `/api/cache` | Преглед кеша: укупан број уноса, стопа погодака, величина на диску |
| GET | `/api/cache/entries` | Листа кешираних уноса (са паginацијом) |
| DELETE | `/api/cache/entries` | Брисање уноса кеша (филтрирано по параметрима упита) |
| GET | `/api/cache/stats` | Детаљна статистика кеша (по провајдеру, по моделу) |
| GET | `/api/cache/reasoning` | Статус кеша закључивања (за реплеј закључивања) |
| DELETE | `/api/cache/reasoning` | Брисање кеша закључивања — параметри упита: `?toolCallId=<id>` (један) или `?provider=<p>` (без параметара за све) |
**Ауторизација:** Захтева management сесију.
---
## Систем меморије
Управљање перзистентном меморијом (FTS5 + векторски embeddinzi).
| Метод | Путања | Опис |
| ------ | ------------------ | --------------------------------------------------------------------------------- |
| GET | `/api/memory` | Листа уноса меморије (филтрирано по опсегу, типу, упиту претраге) |
| POST | `/api/memory` | Креирање новог уноса меморије — тело захтева: `{scope, type, content, metadata?}` |
| GET | `/api/memory/[id]` | Преузимање одређеног уноса меморије |
| PUT | `/api/memory/[id]` | Ажурирање уноса меморије |
| DELETE | `/api/memory/[id]` | Брисање уноса меморије |
| GET | `/api/memory?q=` | Претрага меморије (FTS5 + вектор) — статистика је укључена у истом одговору |
**Ауторизација:** Захтева management сесију или management-scoped API кључ.
---
## Webhook-ови
Управљање webhook претплатама за догађаје.
| Метод | Путања | Опис |
| ------ | ------------------------------- | ------------------------------------------------------------------------------ |
| GET | `/api/webhooks` | Листа свих webhook претплата |
| POST | `/api/webhooks` | Креирање webhook претплате — тело захтева: `{url, events[], secret?, active?}` |
| GET | `/api/webhooks/[id]` | Преузимање одређене webhook претплате |
| PUT | `/api/webhooks/[id]` | Ажурирање webhook претплате |
| DELETE | `/api/webhooks/[id]` | Брисање webhook претплате |
| GET | `/api/webhooks/[id]/deliveries` | Листа историје достава за webhook (лог успеха/неуспеха) |
| POST | `/api/webhooks/[id]/test` | Слање тест догађаја на webhook |
**Ауторизација:** Захтева management сесију.
Погледајте [Webhooks Framework](../frameworks/WEBHOOKS.md) за све типове догађаја.
---
## Skills Framework (Оквир вештина)
Управљајте вештинама (агентски оквир екстензија).
| Метод | Путања | Опис |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------- |
| GET | `/api/skills` | Излистава све инсталиране вештине (уграђене + прилагођене) |
| POST | `/api/skills/install` | Инсталира вештину са локалне путање или URL адресе |
| DELETE | `/api/skills/[id]` | Деинсталира вештину |
| PUT | `/api/skills/[id]` | Омогућава или онемогућава вештину — тело захтева: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST | `/api/skills/executions` | Извршава вештину — тело захтева: `{skillName, apiKeyId, input?, sessionId?}` |
| GET | `/api/skills/executions` | Излистава историју извршавања за све вештине (филтрирање помоћу `?apiKeyId=`) |
**Аутентикација:** Захтева менаџмент сесију или API кључ са менаџмент овлашћењима.
Погледајте [Skills Framework](../frameworks/SKILLS.md) за све детаље.
---
## Plugins (Додаци)
Управљајте OmniRoute додацима (екстензије трећих страна).
| Метод | Путања | Опис |
| ------ | ---------------------------------- | ---------------------------------- |
| GET | `/api/plugins` | Излистава инсталиране додатке |
| POST | `/api/plugins/marketplace/install` | Инсталира додатак из marketplace-а |
| DELETE | `/api/plugins/[name]` | Деинсталира додатак |
| POST | `/api/plugins/[name]/activate` | Активира додатак |
| POST | `/api/plugins/[name]/deactivate` | Деактивира додатак |
| GET | `/api/plugins/[name]/config` | Преузима конфигурацију додатка |
| PUT | `/api/plugins/[name]/config` | Ажурира конфигурацију додатка |
**Аутентикација:** Захтева менаџмент сесију.
Погледајте [Plugins Framework](../frameworks/PLUGIN_SDK.md) за све детаље.
---
## Shadow Routing (Сенка рутирање)
Сенка / A-B поређење провајдера **није самостални REST интерфејс** — конфигурише се преко комбо рутирања (погледајте [Auto-Combo](../routing/AUTO-COMBO.md)). Метрике поређења по комбинацији доступне су преко `GET /api/combos/metrics`.
---
## Guardrails (Заштитне мере)
Прегледајте заштитне мере рантајма (детекција личних података, детекција убризгавања упита, повезивање визуелних података). Заштитне мере се примењују на сваки захтев; одустајање по позиву врши се преко заглавља захтева `x-omniroute-disabled-guardrails` — не постоји трајни интерфејс за омогућавање/онемогућавање.
| Метод | Путања | Опис |
| ----- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/guardrails` | Излистава регистроване заштитне мере и њихов статус (назив / омогућено / приоритет) |
| POST | `/api/guardrails/test` | Тестира сувим погоном (dry-run) пре-позивни ток обраде над узорком уноса — тело захтева: `{input, disabledGuardrails?}` |
**Аутентикација:** Захтева менаџмент сесију.
Погледајте [Security > Guardrails](../security/GUARDRAILS.md) за све детаље.
---
---
## Аутентикација
Погледајте [Management Authentication](../guides/MANAGEMENT-AUTH.md) за четири
породице акредитива (dashboard сесија, локални CLI токен, `oma_live_…` Access
Token, manage-scoped API кључ) и по чему се разликују од inference кључева.
- Dashboard руте (`/dashboard/*`) користе `auth_token` колачић (cookie)
- Пријава користи сачувани хеш лозинке; резервно решење је `INITIAL_PASSWORD`
- `requireLogin` се може укључити/искључити преко `/api/settings/require-login`
- `/v1/*` руте опционо захтевају Bearer API кључ када је `REQUIRE_API_KEY=true`
- „management token" / „management-scoped API кључ" у овом документу значи једно од породица из тог водича — а не недефинисан додатни тип тајне
> **Промена која нарушава компатибилност (v3.8.0)** — `/api/v1/agents/tasks/*` и крајње тачке за управљање cooldown-ом сада захтевају **management аутентикацију** (dashboard `auth_token` колачић или manage-scoped API кључ). Клијенти који су раније позивали ове руте без аутентикације добиће `401 Unauthorized`. Погледајте commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).
Reference in New Issue View Git Blame Copy Permalink