# API Reference (Română) 🌐 **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) · 🇷🇺 [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) --- 🌐 **Limbi:** 🇺🇸 [English](./API_REFERENCE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/reference/API_REFERENCE.md) | 🇸🇦 [العربية](../i18n/ar/docs/reference/API_REFERENCE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/reference/API_REFERENCE.md) | 🇧🇬 [Български](../i18n/bg/docs/reference/API_REFERENCE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/reference/API_REFERENCE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/reference/API_REFERENCE.md) | 🇩🇰 [Dansk](../i18n/da/docs/reference/API_REFERENCE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/reference/API_REFERENCE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/reference/API_REFERENCE.md) | 🇪🇸 [Español](../i18n/es/docs/reference/API_REFERENCE.md) | 🇪🇪 [Eesti](../i18n/et/docs/reference/API_REFERENCE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/reference/API_REFERENCE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/reference/API_REFERENCE.md) | 🇫🇷 [Français](../i18n/fr/docs/reference/API_REFERENCE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/reference/API_REFERENCE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/reference/API_REFERENCE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../i18n/he/docs/reference/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/reference/API_REFERENCE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/reference/API_REFERENCE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/reference/API_REFERENCE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/reference/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/reference/API_REFERENCE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/reference/API_REFERENCE.md) | 🇮🇹 [Italiano](../i18n/it/docs/reference/API_REFERENCE.md) | 🇯🇵 [日本語](../i18n/ja/docs/reference/API_REFERENCE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/reference/API_REFERENCE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/reference/API_REFERENCE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/reference/API_REFERENCE.md) | 🇰🇷 [한국어](../i18n/ko/docs/reference/API_REFERENCE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/reference/API_REFERENCE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/reference/API_REFERENCE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/reference/API_REFERENCE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/reference/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/reference/API_REFERENCE.md) | 🇲🇹 [Malti](../i18n/mt/docs/reference/API_REFERENCE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/reference/API_REFERENCE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/reference/API_REFERENCE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norsk](../i18n/no/docs/reference/API_REFERENCE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/reference/API_REFERENCE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/reference/API_REFERENCE.md) | 🇵🇱 [Polski](../i18n/pl/docs/reference/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/reference/API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/reference/API_REFERENCE.md) | 🇷🇴 [Română](../i18n/ro/docs/reference/API_REFERENCE.md) | 🇷🇺 [Русский](../i18n/ru/docs/reference/API_REFERENCE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/reference/API_REFERENCE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/reference/API_REFERENCE.md) | 🇷🇸 [Српски](../i18n/sr/docs/reference/API_REFERENCE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/reference/API_REFERENCE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/reference/API_REFERENCE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/reference/API_REFERENCE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/reference/API_REFERENCE.md) | 🇹🇭 [ไทย](../i18n/th/docs/reference/API_REFERENCE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/reference/API_REFERENCE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/reference/API_REFERENCE.md) | 🇵🇰 [اردو](../i18n/ur/docs/reference/API_REFERENCE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/reference/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/reference/API_REFERENCE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/reference/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/reference/API_REFERENCE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/reference/API_REFERENCE.md) Referința principală pentru API-ul OmniRoute. Aceasta acoperă interfața publică `/v1` și cele mai utilizate puncte finale de administrare; fișierul [`docs/openapi.yaml`](../openapi.yaml), care poate fi citit automat, și arborele de rute din `src/app/api/` reprezintă sursele exhaustive. --- ## Cuprins - [Completări de chat](#chat-completions) - [Contracte de închiriere exclusive pentru sesiuni gestionate](#exclusive-managed-session-leases) - [Încorporări](#embeddings) - [Generarea imaginilor](#image-generation) - [OCR pentru documente](#document-ocr) - [Listarea modelelor](#list-models) - [Manifestul pluginului furnizorului](#provider-plugin-manifest) - [Endpointuri de compatibilitate](#compatibility-endpoints) - [API pentru fișiere](#files-api) - [API pentru loturi](#batches-api) - [API de căutare](#search-api) - [Streaming prin WebSocket](#websocket-streaming) - [Cote și raportarea problemelor](#quotas--issues-reporting) - [Cache semantic](#semantic-cache) - [Panou de control și administrare](#dashboard--management) - [Administrarea combinațiilor](#combo-management) - [Webhookuri](#webhooks) - [Chei înregistrate (administrare automată)](#registered-keys-auto-management) - [Protocolul agenților](#agents-protocol) - [Proxy-uri de administrare](#management-proxies) - [Reziliență (extinsă)](#resilience-extended) - [Abilități](#skills) - [Memorie](#memory) - [Server MCP](#mcp-server) - [Server A2A](#a2a-server) - [Cloud, evaluări și analiză](#cloud-evals--assess) - [Procesarea cererilor](#request-processing) - [Autentificare](#authentication) --- ## Completări de chat ```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 } ``` ### Anteturi personalizate | Antet | Direcție | Descriere | | ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `X-OmniRoute-No-Cache` | Cerere | Setați la `true` pentru a ocoli cache-ul | | `x-omniroute-no-memory` | Cerere | Setați la `true` pentru a omite injectarea memoriei și a abilităților pentru această cerere (reflectă comportamentul fără cache; evită costul suplimentar per apel aferent tokenurilor și costurilor) | | `X-OmniRoute-Progress` | Cerere | Setați la `true` pentru evenimente de progres | | `X-Session-Id` | Cerere | Cheie de sesiune persistentă pentru afinitatea externă a sesiunii | | `x_session_id` | Cerere | Este acceptată și varianta cu caractere de subliniere (HTTP direct) | | `X-OmniRoute-Session-Id` | Cerere | Etichetă de sesiune/conversație furnizată de apelant (utilizată și de memorie). Când este prezentă, este stocată textual în `call_logs.session_tag` pentru atribuirea costurilor per sesiune (#8249) — nu este generată niciodată dacă lipsește | | `Idempotency-Key` | Cerere | Cheie de deduplicare (interval de 5 s) | | `X-Request-Id` | Cerere | Cheie alternativă de deduplicare | | `X-OmniRoute-Cache` | Răspuns | `HIT` sau `MISS` (fără streaming) | | `X-OmniRoute-Idempotent` | Răspuns | `true` dacă a fost deduplicată | | `X-OmniRoute-Progress` | Răspuns | `enabled` dacă urmărirea progresului este activată | | `X-OmniRoute-Session-Id` | Răspuns | ID-ul efectiv al sesiunii utilizat de OmniRoute | | `X-OmniRoute-Request-Id` | Răspuns | ID-ul de corelare al cererii (când este cunoscut) | | `X-OmniRoute-Version` | Răspuns | Versiunea compilării OmniRoute (prezentă întotdeauna) | | `X-OmniRoute-Cost-Saved` | Răspuns | Suma în USD economisită de cache la un `HIT` (numai pentru accesările reușite ale cache-ului) | | `X-OmniRoute-Decision` | Răspuns | Traseul rutării: `strategy=; provider=; latency_ms=` (`` este strategia combinației sau `single` pentru o cerere fără combinație) — prezent întotdeauna în răspunsurile finale | > Notă pentru Nginx: dacă vă bazați pe anteturi cu caractere de subliniere (de exemplu, `x_session_id`), activați `underscores_in_headers on;`. > **Antete de telemetrie a costurilor:** răspunsurile reușite fără streaming includ și setul de telemetrie a costurilor `X-OmniRoute-*` — `X-OmniRoute-Response-Cost` (USD, fix 10 zecimale; `0.0000000000` pentru servicii gratuite/fără preț), `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` (doar când > 0), plus `X-OmniRoute-Request-Id` și `X-OmniRoute-Version`. Acestea sunt emise de completările de chat, `/v1/responses`, `/v1/messages`, **precum și de endpointurile media** — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations` și `/v1/moderations` (cost întotdeauna `0`). Costul media este calculat în funcție de fiecare modalitate (per imagine, per secundă, per caracter, per unitate de căutare) atunci când sunt disponibile informații despre prețuri; în caz contrar, este `0` (fail-open). > **Semantica costurilor pentru accesările cache-ului:** la un HIT în cache-ul semantic (`X-OmniRoute-Cache-Hit: true`) nu este efectuat niciun apel către furnizorul upstream, astfel încât `X-OmniRoute-Response-Cost` este `0.0000000000` (costul **incremental** al furnizării rezultatului din cache). Costul inițial/care ar fi fost suportat este raportat separat în `X-OmniRoute-Cost-Saved`. Consumatorii datelor de facturare trebuie să însumeze `X-OmniRoute-Response-Cost` (accesările cache-ului nu costă nimic); analizele cache-ului pot agrega `X-OmniRoute-Cost-Saved`. ## Închirieri exclusive de sesiuni gestionate Închirierea exclusivă a sesiunilor gestionate este un contract de rutare opțional și independent de client: un proprietar activ deține o conexiune OmniRoute eligibilă. Aceasta nu închiriază un model, nu necesită OAuth, nu identifică un anumit client și nu necesită un anumit furnizor. Cheia API utilizată pentru autentificare trebuie să aibă domeniul de aplicare `lease:exclusive` și o listă `allowedConnections` explicită și nevidă. Limita de mutație a bazei de date impune împreună ambele câmpuri la crearea cheii și la actualizările parțiale. ```http POST /api/v1/session-leases Authorization: Bearer Content-Type: application/json X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters> {"action":"acquire","model":"glm/glm-4.6"} ``` Răspunsurile reușite pentru obținere, reînnoire și eliberare expun marcajele temporale, `state` și valoarea pozitivă exactă `generation`, dar niciodată conexiunea selectată sau datele de autentificare. Reînnoirea și eliberarea furnizează generația în corpul JSON: ```json { "action": "renew", "generation": 1 } ``` ```json { "action": "release", "generation": 1, "reason": "OWNER_EXIT" } ``` Proprietarul unei închirieri active poate solicita în mod explicit metadate de afișare care protejează confidențialitatea pentru asocierea sa curentă: ```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" } } ``` Această acțiune opțională de stare este protejată de proprietarul opac, cheia API gestionată și autentificată și generația activă exactă, în cadrul unei singure tranzacții în baza de date. `displayName` este doar numele configurat al conexiunii, fără spații la extremități; valoarea sa este `null` atunci când nu există un nume configurat sigur. OmniRoute nu înlocuiește niciodată acest nume cu o adresă de e-mail sau cu o identitate de cont generată. Valoarea furnizorului este o etichetă de afișare nesensibilă și niciodată un identificator generat al unui furnizor compatibil. Datele de autentificare, tokenurile, cookie-urile, ID-urile brute ale conexiunilor sau ale cheilor API, hash-urile proprietarilor, secretele de delimitare și datele interne de rutare sunt excluse. Căutările cu o cheie greșită, un proprietar greșit, o generație învechită, o închiriere lipsă, expirată, eliberată sau invalidată returnează toate aceeași eroare `409 LEASE_FENCE_STALE`, fără metadatele conexiunii. Un client care a primit răspunsul de așteptare a capacității nu are nicio asociere activă pe care să o poată inspecta. Atunci când rutarea mută o închiriere activă, aceeași generație rămâne validă, iar starea returnează atomic noua asociere, niciodată pe cea veche. Clienții existenți rămân neschimbați, deoarece răspunsurile pentru obținere, reînnoire, eliberare și așteptare își păstrează formatele anterioare. Acest contract al serverului nu modifică ruta `/status` din OpenAI Codex standard. În prezent, Codex standard raportează furnizorul modelului și starea încorporată de autentificare/cont, dar nu afișează metadate arbitrare personalizate despre contul furnizorului; o integrare ulterioară a clientului trebuie să apeleze această acțiune și să decidă cum să afișeze `connection.displayName`. Apoi, fiecare solicitare de inferență gestionată furnizează ambele antete de control: ```http X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters> X-OmniRoute-Lease-Generation: 1 ``` Proprietarul exact, generația, conexiunea activă și cheia API autentificată sunt verificate imediat înaintea fiecărei încercări acceptate către serviciul din amonte. Reutilizarea proprietarului și a generației cu altă cheie eșuează chiar și atunci când cheia respectivă permite aceeași conexiune. Proprietarii în formă brută nu sunt persistați, înregistrați în jurnale, păstrați în instantaneul solicitării sau redirecționați către serviciul din amonte. Disputarea temporară a resurselor returnează HTTP `429` cu `Retry-After` și: ```json { "state": "WAITING_FOR_CAPACITY", "error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" }, "reason": "NO_FREE_ELIGIBLE_CONNECTION", "retryAfter": 30 } ``` Acest răspuns înseamnă doar că setul obișnuit eligibil nu era gol și că fiecare candidat liber era deținut de o închiriere activă străină. Modelele/furnizorii neacceptați, neconcordanțele cu politica, perioadele de așteptare, cotele, starea de funcționare și alte erori obișnuite de eligibilitate își păstrează răspunsurile OmniRoute existente. ### `x-omniroute-compression` Suprascriere la nivel de solicitare a planului de compresie. Are cea mai mare prioritate — prevalează asupra suprascrierii combinației de rutare, profilului activ, declanșării automate și valorii implicite din panou. Valori: | Valoare | Efect | | ------------- | --------------------------------------------------------------------------------------------------------- | | `off` | Fără compresie pentru această solicitare. | | `default` | Profilul implicit derivat din panou (ignoră profilul activ). | | `engine:` | Un singur motor, atunci când este activat, de exemplu `engine:rtk`. | | `` | O combinație denumită, asociată mai întâi după nume (fără a ține cont de litere mari/mici), apoi după ID. | Note: - Valorile necunoscute sunt ignorate (solicitarea nu este niciodată respinsă); rezoluția continuă conform ordinii normale de prioritate a operatorilor. - Dacă mai multe combinații au același nume, transmiteți **id**-ul combinației pentru o asociere deterministă. - O combinație al cărei nume este `off` sau `default` nu poate fi selectată după nume (aceste cuvinte-cheie sunt interpretate primele); referiți o astfel de combinație prin ID-ul său. - Comutatorul principal pentru compresie este o barieră strictă: atunci când compresia este dezactivată global, acest antet nu o poate activa. Planul aplicat este returnat în antetul răspunsului: ``` X-OmniRoute-Compression: ; source= ``` unde `` este una dintre valorile `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default` sau `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" } ``` Furnizori disponibili: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI. ID-urile din catalog au forma `provider/model` (exemplu: `jina-ai/jina-embeddings-v5-omni-small`). ID-urile simple ale modelelor Jina care apar în registru (de exemplu, `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) sunt, de asemenea, rezolvate. Operațiile Jina embed/rerank/classify/segment utilizează mai întâi acreditările `jina-ai` din dashboard; `JINA_AI_API_KEY` este utilizată ca variantă de rezervă numai atunci când nu există nicio cheie în dashboard. Cardul `jina-reader` este destinat exclusiv pentru Reader / `r.jina.ai` (`POST /v1/web/fetch`) și nu furnizează niciodată embeddings sau rerank. Modelele din registru care declară suport multimodal acceptă, de asemenea, până la 32 de elemente structurate independente de furnizor. Tipurile de elemente media sunt `text`, `image`, `audio`, `video` și `document`. Câmpul media `source` al acestora este fie `{"type":"url","url":"https://..."}`, fie `{"type":"base64","data":"...","media_type":"..."}`. Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano` și aliasul familiei `jina-ai/jina-embeddings-v5-omni` → omni-small) acceptă, de asemenea, documentele native EmbeddingsV5Request ale Jina și **le redirecționează intacte** către `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,..." }] } ] } ``` Valorile native `{ image | audio | video | pdf }` pot fi un URL HTTPS public, un URI `data:` sau date base64 brute. OmniRoute nu convertește aceste obiecte în șiruri și nu preia URL-urile native ale imaginilor — Jina preia direct conținutul media public. Câmpurile Jina suplimentare (`task`, `normalized`, `truncate`, `embedding_type`) sunt redirecționate. SKU-urile Jina care acceptă numai text continuă să respingă documentele care nu conțin text. Limite de securitate și transport: - URL-urile media de la distanță trebuie să fie URL-uri HTTPS publice. Elementele canonice `{type,source:url}` sunt preluate pe server (revalidarea redirecționărilor, timeout, limite de dimensiune, DNS public, fixarea conexiunii) și incluse inline înaintea apelului către furnizor. Elementele native Jina `{image:"https://..."}` sunt redirecționate ca atare după aceeași verificare pentru HTTPS public; Jina preia URL-ul. - Conținutul media base64 inline este limitat la 8 MiB decodificați per element și la 16 MiB decodificați pentru întreaga solicitare. Conversia pentru furnizor (elementele canonice nu sunt redirecționate niciodată fără modificări): - Modele multimodale Jina: fiecare element de nivel superior devine un obiect bazat pe cheia modalității (`text` / `image` / `audio` / `video` / `pdf`), utilizând URI-uri de date pentru conținutul media inline; un vector pentru fiecare element de nivel superior. - Familia Gemini Embedding 2: un singur tablou de nivel superior devine o singură solicitare nativă `models/{model}:embedContent` cu `content.parts` (`text` sau `inline_data`). - Modelele necunoscute/dinamice fără metadate explicite privind modalitatea resping datele de intrare structurate cu 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" } ``` Combinațiile model/modalitate neacceptate returnează HTTP 400 în loc să convertească forțat elementul. Câmpurile de extensie care nu țin de datele de intrare din solicitările vechi bazate pe șiruri/tokenuri continuă să fie transmise fără modificări. ```bash # Listează toate modelele de embeddings GET /v1/embeddings ``` --- ## Generarea imaginilor ```bash POST /v1/images/generations Authorization: Bearer your-api-key Content-Type: application/json { "model": "openai/gpt-image-2", "prompt": "Un apus superb deasupra munților", "size": "1024x1024" } ``` Furnizori disponibili: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (local), ComfyUI (local). ```bash # Listează toate modelele de imagini GET /v1/images/generations ``` --- ## OCR pentru documente ```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` selectează furnizorul OCR prin intermediul unui prefix `provider/model`; un id de model simplu (de ex. `mistral-ocr-latest`) este asociat furnizorului său înregistrat, iar dacă `model` este omis, valoarea implicită este Mistral (`mistral-ocr-latest`). Furnizori înregistrați (`open-sse/config/ocrRegistry.ts`): | Id furnizor | Id model | Valoarea `model` | Note | | ----------------------------- | -------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (sau simplu `mistral-ocr-latest`) | Sincron — răspunsul este returnat direct din singurul apel upstream. | | `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | Upstream asincron (`analyze` + interogare) — vezi mai jos. | | `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Sincron, prin endpointul partener `openapi/chat/completions` al Vertex AI — vezi mai jos pentru autentificare/URL. | Toți cei trei furnizori răspund folosind același corp în format Mistral: ```json { "pages": [{ "index": 0, "markdown": "# Text extras..." }], "model": "mistral-ocr-latest", "usage_info": { "pages_processed": 1 } } ``` ### Fluxul de interogare Azure Document Intelligence API-ul `analyze` al Azure Document Intelligence este asincron: solicitarea inițială returnează un antet `Operation-Location` în locul unui corp, iar rezultatul trebuie interogat periodic. Handlerul (`open-sse/handlers/ocr.ts`) interoghează acel URL în fiecare secundă, timp de maximum 30 de încercări, eșuează imediat (nu continuă interogarea) în cazul unui răspuns de interogare care nu este `ok` sau al unei stări `"failed"` și returnează `504` dacă operațiunea încă rulează după epuizarea numărului de încercări. Răspunsul Azure final este normalizat în aceeași structură `pages`/`markdown` utilizată de Mistral înainte de a fi returnat apelantului, astfel încât codul clientului nu trebuie să trateze furnizorul ca pe un caz special. ### Autentificarea și rezolvarea endpointului pentru Vertex AI DeepSeek OCR `vertex-deepseek-ocr` reutilizează aceeași autentificare Vertex AI pe care OmniRoute o acceptă deja pentru traficul de chat/imagini (`open-sse/executors/vertex.ts`): cheia API a conexiunii este fie o credențială JSON pentru Service Account (schimbată cu un token de acces OAuth cu durată scurtă prin fluxul JWT-bearer), fie un token de acces OAuth deja emis, utilizat ca atare. URL-ul endpointului upstream este endpointul partener generic `openapi/chat/completions` al Vertex, construit pe baza proiectului și regiunii conexiunii — valorile explicite `providerSpecificData.project`/`providerSpecificData.region` au întotdeauna prioritate; în caz contrar, proiectul este derivat din `project_id` din JSON-ul Service Account, iar regiunea are ca valoare implicită `us-central1`. Ambele rezolvări au loc în `open-sse/handlers/ocr.ts` (`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`) și sunt utilizate de `src/app/api/v1/ocr/route.ts` înainte de trimiterea către `handleOcr`. --- ## Listarea modelelor ```bash GET /v1/models Authorization: Bearer your-api-key → Returnează toate modelele de chat, embeddings și imagini + combinațiile, în format OpenAI ``` ### Prefixele id-urilor modelelor (`?prefix=`) Majoritatea modelelor sunt prezentate sub un **prefix al furnizorului**. Prefixul pe care îl primiți este controlat de indicatorul de funcționalitate `MODELS_CATALOG_PREFIX_MODE` și poate fi suprascris **pentru fiecare cerere** cu un parametru de interogare — util pentru un client care dorește o listă simplificată fără a modifica setarea valabilă la nivelul întregului server pentru toți ceilalți: ```bash GET /v1/models?prefix=alias # un id per model — prefixul scurt de alias GET /v1/models?prefix=dual # ambele forme (valoarea implicită a serverului) GET /v1/models?prefix=canonical # doar prefixul complet al id-ului furnizorului ``` | Mod | Emite | Note | | ----------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `dual` | `cc/claude-sonnet-4-6` **și** `claude/claude-sonnet-4-6` | **Implicit.** Ambele id-uri sunt direcționate către același model; sunt păstrate astfel încât configurațiile clienților care au codificat fix oricare dintre forme să funcționeze în continuare. Aproximativ dublează catalogul. | | `alias` | `cc/claude-sonnet-4-6` | O intrare per model. Furnizorii fără un alias distinct își emit în continuare intrarea, astfel încât nu se pierde nimic. | | `canonical` | `claude/claude-sonnet-4-6` | O intrare per model sub prefixul complet al id-ului furnizorului. Furnizorii fără un alias distinct (de ex. `antigravity/…`, `agy/…`) își emit și aici unicul id, astfel încât nu se pierde nimic. | O oglindă în modul `dual` poate fi recunoscută și fără parametrul de interogare: conține un câmp `parent` care indică id-ul principal. Clienții care afișează un selector de modele ar trebui să solicite `?prefix=alias` — aceasta este abordarea folosită de [extensia OmniCopilot pentru VS Code](../guides/VSCODE-COPILOT.md). ### Variante de modele fără raționament Pentru modelele Claude capabile de raționament, `/v1/models` prezintă și o variantă **fără raționament**, al cărei id are prefixul `claude-3-omniroute-no-thinking/`: ``` claude-3-omniroute-no-thinking// ``` Selectarea acestui id (de ex. într-o configurație Claude Code care atașează întotdeauna un bloc `thinking`) se rezolvă înapoi la modelul real `/`, cu raționamentul suprimat — `thinking:{type:"disabled"}` pe ruta `/v1/messages` sau cu câmpurile `reasoning`/`reasoning_effort` eliminate pe ruta `/v1/chat/completions`. Varianta este listată numai pentru modelele din familia Claude care acceptă raționamentul **și** respectă `disabled` (astfel, de ex., modelele exclusiv adaptive care resping `disabled` sunt excluse). Operatorii pot activa sau dezactiva forțat varianta pentru fiecare model prin `ModelSpec.noThinkingAlias`. --- ## Manifestul pluginurilor furnizorilor ```bash GET /api/v1/provider-plugin-manifest ``` Returnează manifestul JSON-safe al pluginurilor furnizorilor utilizat de Bifrost, CLIProxyAPI și de viitoarele rutere sidecar. Răspunsul este generat din registrul furnizorilor TypeScript și exclude în mod intenționat secretele clienților OAuth, rezolvarea mediului la rulare, funcțiile de execuție, antetele cererilor și datele conturilor. Utilizați acest endpoint atunci când un sidecar rulează în afara procesului și nu poate importa direct `open-sse/config/providerPluginManifestRegistry.ts`. --- ## Endpointuri de compatibilitate | Metodă | Cale | Format | | ------ | ----------------------------------------- | --------------------------------------- | | POST | `/v1/chat/completions` | OpenAI | | POST | `/v1/messages` | Anthropic | | POST | `/v1/responses` | Răspunsuri OpenAI | | POST | `/v1/embeddings` | OpenAI | | POST | `/v1/images/generations` | Imagini OpenAI | | POST | `/v1/images/edits` | Imagini OpenAI (editare/inpainting) | | POST | `/v1/videos/generations` | Generare video în stil OpenAI | | POST | `/v1/music/generations` | Generare muzicală în stil OpenAI | | POST | `/v1/audio/transcriptions` | Audio OpenAI (STT) | | POST | `/v1/audio/speech` | OpenAI TTS (returnează corpul audio) | | POST | `/v1/rerank` | Reclasificare în stil Cohere/Voyage | | POST | `/v1/classify` | Clasificare Jina (`api.jina.ai`) | | POST | `/v1/segment` | Segmentator Jina (`segment.jina.ai`) | | POST | `/v1/moderations` | Moderări OpenAI | | GET | `/v1/models` | OpenAI | | POST | `/v1/messages/count_tokens` | Anthropic | | GET | `/v1beta/models` | Gemini | | POST | `/v1beta/models/{...path}` | Gemini generateContent | | POST | `/v1/api/chat` | Ollama | | GET | `/api/v1/vscode/{token}/` | Alias pentru catalogul OpenAI | | GET | `/api/v1/vscode/{token}/models` | Alias pentru modelele OpenAI | | POST | `/api/v1/vscode/{token}/chat/completions` | Alias OpenAI cu token | | POST | `/api/v1/vscode/{token}/responses` | Alias OpenAI Responses cu token | | POST | `/api/v1/vscode/{token}/api/chat` | Alias Ollama cu token | | GET | `/api/v1/vscode/{token}/api/tags` | Alias pentru etichetele Ollama cu token | Toate rutele POST urmează aceeași structură: `Bearer your-api-key` + corp JSON validat prin Zod (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema` etc.; consultați `src/shared/validation/schemas.ts`). În cazul eșuării validării schemei, este returnat un răspuns 4xx. Pentru clienții care nu pot atașa `Authorization: Bearer ...`, OmniRoute acceptă și chei API în URL, fie prin compatibilitatea cu șirul de interogare (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`), fie prin endpointurile dedicate `/api/v1/vscode/{token}/...` documentate mai jos. ```bash # Reclasificare POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] } # Clasificare Jina (date de autentificare Foundation API) POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] } # Segmentator Jina POST /v1/segment { "content": "...", "return_chunks": true } # Căutare Jina (s.jina.ai; aliasuri de furnizor: jina-search, jina-ai, jina) POST /v1/search { "query": "...", "provider": "jina-search" } # Moderări POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." } # TTS — returnează un corp audio/mpeg (sau în formatul solicitat) POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" } # Editare imagine (multipart) POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png # Generare video/muzicală (ID de model prefixat cu furnizorul) POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." } POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." } ``` ### Rute dedicate furnizorilor ```bash POST /v1/providers/{provider}/chat/completions POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` Prefixul furnizorului este adăugat automat dacă lipsește. Modelele incompatibile returnează `400`. --- ## API pentru fișiere Endpoint compatibil cu OpenAI pentru fișiere utilizate la intrarea/ieșirea procesării în lot și pentru încărcări cu scop specificat. | Metodă | Cale | Descriere | | ------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------- | | POST | `/v1/files` | Încarcă un fișier (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — maximum 512 MiB | | GET | `/v1/files` | Listează fișierele pentru cheia API autentificată | | GET | `/v1/files/[id]` | Preia metadatele unui fișier | | DELETE | `/v1/files/[id]` | Șterge un fișier | | GET | `/v1/files/[id]/content` | Transmite în flux conținutul brut al fișierului | **Autentificare:** Cheie API Bearer — fișierele sunt delimitate per cheie API prin `getApiKeyRequestScope`. O cheie poate vedea, descărca și șterge numai propriile fișiere; o sesiune de panou de control fără cheie poate citi întreaga instanță; un fișier fără proprietar (încărcare anonimă sau printr-o sesiune a panoului de control) este inaccesibil oricărui apelant fără sesiune. `GET /v1/files` respinge un apelant anonim — precum și o cheie furnizată care nu poate fi identificată — cu `401`, chiar și atunci când `REQUIRE_API_KEY=false`, în loc să listeze fișierele tuturor entităților găzduite (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523). --- ## API pentru loturi Procesare în lot compatibilă cu OpenAI. | Metodă | Cale | Descriere | | ------ | ------------------------- | --------------------------------------------------------------------------------------------------------- | | POST | `/v1/batches` | Creează un lot — corp validat de `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) | | GET | `/v1/batches` | Listează loturile | | GET | `/v1/batches/[id]` | Preia starea lotului + `request_counts` | | DELETE | `/v1/batches/[id]` | Șterge un lot finalizat/eșuat | | POST | `/v1/batches/[id]/cancel` | Anulează un lot aflat în curs | **Autentificare:** Cheie API Bearer. Loturile sunt delimitate per cheie API conform aceleiași reguli cu trei cazuri ca în cazul fișierelor: acces numai pentru cheia proprietară, acces la nivelul întregii instanțe pentru sesiunea panoului de control, iar înregistrările fără proprietar sunt inaccesibile oricărui apelant fără sesiune (preluare, ștergere, anulare și verificarea `input_file_id` la creare). `GET /v1/batches` respinge un apelant anonim cu `401`, chiar și atunci când `REQUIRE_API_KEY=false`. --- ## API de căutare Abstractizare pentru furnizori web/de căutare (Tavily, Brave, Exa, Serper etc.). | Metodă | Cale | Descriere | | ------ | ---------------------- | -------------------------------------------------------------------------------------------------------- | | GET | `/v1/search` | Listează furnizorii de căutare configurați și capabilitățile acestora | | POST | `/v1/search` | Execută o interogare de căutare — corp validat de `v1SearchSchema`, acceptă memorarea în cache/comasarea | | GET | `/v1/search/analytics` | Statistici per furnizor privind rezultatele/ latența/cache-ul | **Autentificare:** cheie API Bearer (`extractApiKey` + `isValidApiKey`). Politica de căutare este aplicată prin `enforceApiKeyPolicy`. --- ## API de preluare web Extrage conținut dintr-un URL prin intermediul unui furnizor de preluare web configurat (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract). | Metodă | Cale | Descriere | | ------ | --------------- | -------------------------------------------------------------------- | | POST | `/v1/web/fetch` | Preia/extrage date dintr-un URL — corp validat de `v1WebFetchSchema` | **Autentificare:** cheie API Bearer (`extractApiKey` + `isValidApiKey`). Politica este aplicată prin `enforceApiKeyPolicy`. **Fallback care ține cont de cotă (#8297):** când nu este specificat niciun `provider` explicit, grupul (`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) este parcurs într-o ordine fixă a priorității (primul este utilizat până la epuizare) — un furnizor configurat, dar cu limitare de rată, este omis în loc ca solicitarea să fie întreruptă imediat, iar o eroare temporară/de cotă din amonte (HTTP 429 întotdeauna; 402/403 pentru nivelurile gratuite de tip cotă Firecrawl/Tavily/TinyFish — nu pentru Jina Reader și niciodată pentru o simplă solicitare incorectă 400) determină trecerea la următorul furnizor neîncercat care are credențiale, în timpul solicitării. Când toți furnizorii din grup sunt epuizați, endpointul returnează un singur `429` (cu un antet `Retry-After`) în locul răspunsului generic `400` anterior. Când este solicitat un `provider` explicit, **nu** există un fallback silențios — un furnizor explicit cu limitare de rată sau care eșuează își expune propria eroare (`429` dacă este limitat în funcție de rată, în caz contrar starea din amonte). --- ## Streaming WebSocket ```bash GET /v1/ws?handshake=1 ``` Validează un handshake de upgrade WebSocket și returnează mesajele exemplificative ale protocolului de comunicație (`request`, `cancel`). Cadrele WS efective sunt gestionate de serverul WS inclus, în afara tabelului de rute Next.js. **Autentificare:** cheie API Bearer în timpul handshake-ului. ### API-ul Responses prin WebSocket (doar codex) ```bash # Aceeași gazdă și același port ca API-ul HTTP (implicit 20128); efectuați upgrade-ul conexiunii: wscat -c "ws://localhost:20128/v1/responses?api_key=" # (sau: -H "Authorization: Bearer ") # Primul cadru TREBUIE să fie response.create: { "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] } ``` Un proxy pentru Responses-API-over-WebSocket este conectat **exclusiv la `codex`** (backendul ChatGPT). Acesta ascultă pe același port ca API-ul/panoul de control, la căile `/v1/responses`, `/responses` și `/api/v1/responses`. La primul cadru `response.create`, acesta autentifică și pregătește conexiunea prin puntea internă `codex-responses-ws`, selectează o conexiune OAuth codex și creează un tunel către `wss://chatgpt.com/backend-api/codex/responses` prin transportul `wreq-js`. **Modelele non-codex sunt respinse** (`codex_ws_provider_required`). Pentru rutarea cu partajarea cotei, utilizați `model: "qtSd//codex/"`. Implementat în `app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`. **Autentificare:** cheie API Bearer în timpul handshake-ului. Serverul HTTP inclus (`server-ws.mjs`) trebuie să fie punctul de intrare activ (și este, în mod implicit, atunci când există `app/server-ws.mjs`). #### ID-ul modelului: utilizați ID-ul ChatGPT simplu (fără prefixul `codex/`) **Codex CLI** de la OpenAI validează numele modelului pe partea clientului atunci când `supports_websockets = true` și **respinge ID-urile cu prefix de furnizor**, precum `codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account`). Trimiteți ID-ul **simplu** (de exemplu, `gpt-5.5`). Puntea OmniRoute este destinată exclusiv codex, așadar aceasta re-rezolvă un ID simplu ca model codex (`resolveCodexWsModelInfo`) înainte de a crea tunelul către serviciul din amonte — chiar dacă un ID simplu `gpt-5.5` ar fi rutat în mod normal către alt furnizor prin HTTP. #### Configurarea OpenAI Codex CLI Direcționați Codex CLI către OmniRoute adăugând un furnizor personalizat cu suport WebSocket în `~/.codex/config.toml` (utilizați un `CODEX_HOME` separat pentru a evita modificarea unei configurații existente): ```toml model = "gpt-5.5" # ID simplu — NU "codex/gpt-5.5" model_provider = "omniroute" [model_providers.omniroute] name = "OmniRoute (WS)" base_url = "http://localhost:20128/v1" # fără bară oblică finală; URL-ul WS este derivat (utilizați https/wss în producție) wire_api = "responses" # singura valoare acceptată din februarie 2026 supports_websockets = true # activează transportul Responses-over-WS env_key = "OMNIROUTE_API_KEY" # conține cheia API OmniRoute (Bearer) ``` ```bash export OMNIROUTE_API_KEY=sk-... # o cheie API OmniRoute (orice cheie dacă REQUIRE_API_KEY=false) codex exec "Responda apenas: PONG" ``` CLI-ul efectuează upgrade pentru `base_url + /responses` la un WebSocket, iar OmniRoute creează un tunel către conexiunea OAuth codex selectată. Validat integral pe serverul local: ChatGPT returnează `codex.rate_limits` + `response.created` și transmite în flux rezultatul. --- ## Raportarea cotelor și a problemelor | Metodă | Cale | Descriere | | ------ | ------------------- | ---------------------------------------------------------------------------------------------------- | | GET | `/v1/quotas/check` | Prevalidează cota pentru un `provider` + `accountId` înainte de emiterea unei chei înregistrate | | POST | `/v1/issues/report` | Raportează către GitHub o eroare privind cota/emiterea cheii (necesită `GITHUB_ISSUES_REPO` + token) | **Autentificare:** cheie API Bearer (`isAuthenticated`). --- ## Utilizare în regim self-service (`/api/usage/om-usage`) Orice cheie API își poate citi **propriile** date de utilizare și cote — fără autentificare de administrare. Acesta este endpoint-ul pe care un client (CLI, panoul OmniCopilot) îl folosește pentru a-i afișa deținătorului unei chei consumul său. ```bash # Format text (contractul istoric — text simplu pentru un terminal) curl -H "Authorization: Bearer " \ http://localhost:20128/api/usage/om-usage # Format structurat — ceea ce utilizează o interfață curl -H "Authorization: Bearer " \ "http://localhost:20128/api/usage/om-usage?format=json" ``` Cheia trebuie să aibă activată opțiunea **`allowUsageCommand`** (dezactivată implicit — managerul de chei API al panoului de control o comută pentru fiecare cheie). Fără aceasta, endpoint-ul răspunde cu `403`. `?format=json` returnează o structură discriminată, astfel încât apelantul să nu citească niciodată un câmp de date dintr-un refuz. La succes: ```jsonc { "allowed": true, // prezent numai când cheia a activat limite de utilizare per cheie (USD zilnic/săptămânal): "personal": { "dailySpentUsd": 1.25, "dailyLimitUsd": 5, "dailyResetAtIso": "…", "weeklySpentUsd": 8, "weeklyLimitUsd": 20, "weeklyResetAtIso": "…" /* … */, }, // instantaneul cotei furnizorului selectat sau null când nimic nu este încă în cache: "provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */}, }, // instantaneul fiecărei conexiuni, astfel încât o interfață să poată afișa alăturat mai mulți furnizori: "providers": [ { "connectionId": "…", "provider": "claude" /* … */ }, { "provider": "codex" /* … */ }, ], } ``` În caz de refuz (`401` cheie incorectă / `403` nepermis), aceeași rută returnează `{ "allowed": false, "error": { "message": "…" } }` — un `personal`/`provider` prezent, dar gol (cheie permisă, încă nu s-a obținut nimic) reprezintă o stare diferită de un refuz și numai formatul JSON face distincția între acestea. **Autentificare:** propria cheie API Bearer a apelantului, validată cu `isValidApiKey` — aceasta _nu_ este interfața de administrare (`/api/keys/…`), care rămâne protejată de `requireManagementAuth`. --- ## Cache semantic ```bash # Obține statisticile cache-ului GET /api/cache/stats # Golește toate cache-urile DELETE /api/cache/stats ``` Exemplu de răspuns: ```json { "semanticCache": { "memorySize": 42, "memoryMaxSize": 500, "dbSize": 128, "hitRate": 0.65 }, "idempotency": { "activeKeys": 3, "windowMs": 5000 } } ``` ### Impactul asupra latenței O găsire în cache-ul semantic (HIT) furnizează răspunsul din cache **fără un apel către serviciul upstream**, astfel încât valoarea raportată pentru `X-OmniRoute-Response-Latency` este aproape de zero (indiferent de latența upstream inițială). Clienții sensibili la latență (benchmarking, monitorizare p50/p99) ar trebui să verifice antetul de răspuns `X-OmniRoute-Cache-Latency`: | Valoare | Semnificație | | ----------- | ---------------------------------------------------------------------- | | `synthetic` | Răspuns furnizat din cache; latența nu reprezintă timpul upstream real | | _(absent)_ | Răspuns provenit dintr-un apel upstream real | ### Ocolirea cache-ului per cheie Cheile API pot renunța la citirile din cache-ul semantic prin `cacheDefaultMode`: | Valoare | Comportament | | -------- | ----------------------------------------------------------------- | | `legacy` | Comportament normal al cache-ului (implicit) | | `bypass` | Omite complet căutarea în cache; apelează întotdeauna upstream-ul | Se setează la crearea cheii (`POST /api/keys`) sau la actualizare (`PATCH /api/keys/[id]`): ```json { "cacheDefaultMode": "bypass" } ``` ### Ocolirea per solicitare Orice solicitare poate ocoli cache-ul, indiferent de setările cheii: ``` X-OmniRoute-No-Cache: true ``` --- ## Panou de control și administrare Rutele de administrare (`/api/*`, cu excepția autentificării/conectării publice) **nu** sunt autorizate prin chei API obișnuite pentru inferență. Familii de credențiale, domenii de acces și exemple curl: [Autentificarea pentru administrare](../guides/MANAGEMENT-AUTH.md). ### Autentificare | Endpoint | Metodă | Descriere | | ----------------------------- | ------- | --------------------------------------------- | | `/api/auth/login` | POST | Conectare | | `/api/auth/logout` | POST | Deconectare | | `/api/settings/require-login` | GET/PUT | Activează/dezactivează conectarea obligatorie | ### Administrarea furnizorilor | Endpoint | Metodă | Descriere | | ---------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `/api/providers` | GET/POST | Listează / creează furnizori | | `/api/providers/[id]` | GET/PUT/DELETE | Administrează un furnizor | | `/api/providers/[id]/test` | POST | Testează conexiunea furnizorului | | `/api/providers/[id]/models` | GET | Listează modelele furnizorului | | `/api/providers/validate` | POST | Validează configurația furnizorului | | `/api/providers/bulk` | POST | Adaugă în bloc chei API pentru UN SINGUR furnizor | | `/api/providers/import` | POST | Importă o LISTĂ eterogenă de furnizori dintr-un fișier CSV/JSON analizat (#6836); rezultate parțiale per rând în caz de eșec | | `/api/provider-nodes*` | Diverse | Administrarea nodurilor furnizorului | | `/api/provider-models` | GET/POST/PATCH/DELETE | Modele personalizate (adăugare, actualizare, ascundere/afișare, ștergere) | ### Fluxuri OAuth | Endpoint | Metodă | Descriere | | -------------------------------- | ------- | --------------------------- | | `/api/oauth/[provider]/[action]` | Diverse | OAuth specific furnizorului | ### Rutare și configurare | Endpoint | Metodă | Descriere | | --------------------- | -------- | ---------------------------------- | | `/api/models/alias` | GET/POST | Aliasuri pentru modele | | `/api/models/catalog` | GET | Toate modelele după furnizor + tip | | `/api/combos*` | Diverse | Administrarea combinațiilor | | `/api/keys*` | Diverse | Administrarea cheilor API | | `/api/pricing` | GET | Tarifele modelelor | ### Utilizare și analiză | Endpoint | Metodă | Descriere | | -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `/api/usage/history` | GET | Istoricul utilizării | | `/api/usage/logs` | GET | Jurnale de utilizare | | `/api/usage/request-logs` | GET | Jurnale la nivel de solicitare | | `/api/usage/[connectionId]` | GET | Utilizare per conexiune | | `/api/usage/token-limits` | GET/POST/DELETE | Bugete pentru limita de tokenuri per cheie API | | `/api/usage/model-latency-stats` | GET | Agregare continuă a latenței per furnizor/model (medie/p50/p95/p99, rată de succes); filtre: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) | | `/api/usage/cache-health` | GET | Rezumatul stării cache-ului de prompturi pe baza `call_logs` — raport scriere/citire, distribuția p50/p90/p99 a dimensiunii scrierilor, concentrarea scrierilor intensive, defalcare per model și un verdict `healthy`/`degraded`/`thrash`/`no-data`; parametri de interogare `range` (`1h`\|`24h`\|`7d`\|`30d`, implicit `24h`) și opțional `model` (#8827) | ### Setări | Endpoint | Metodă | Descriere | | ------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/settings` | GET/PUT/PATCH | Setări generale | | `/api/settings/proxy` | GET/PUT | Configurația proxy-ului de rețea | | `/api/settings/proxy/test` | POST | Testarea conexiunii proxy | | `/api/settings/ip-filter` | GET/PUT | Lista de adrese IP permise/blocate | | `/api/settings/thinking-budget` | GET/PUT | Modul de rescriere a **solicitării** pentru gândire/raționament (transmitere nemodificată / eliminare automată / personalizat / adaptiv). Independent de compresie. Consultați [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). | | `/api/settings/system-prompt` | GET/PUT | Prompt de sistem global | | `/api/settings/compression` | GET/PUT | Configurația globală de compresie | | `/api/settings/purge-request-history` | POST | Ștergerea rândurilor din jurnalul solicitărilor și a artefactelor locale din jurnalul apelurilor | ### Context și compresie | Endpoint | Metodă | Descriere | | -------------------------------------- | -------------- | ------------------------------------------------------------------------------ | | `/api/compression/preview` | POST | Previzualizarea compresiei off/lite/standard/aggressive/ultra/RTK/stacked | | `/api/compression/language-packs` | GET | Listează pachetele lingvistice Caveman disponibile | | `/api/compression/rules` | GET | Listează metadatele regulilor Caveman | | `/api/context/caveman/config` | GET/PUT | Alias pentru setările specifice Caveman | | `/api/context/rtk/config` | GET/PUT | Setări specifice RTK, inclusiv filtre personalizate și păstrarea ieșirii brute | | `/api/context/rtk/filters` | GET | Catalogul de filtre RTK și diagnosticarea filtrelor personalizate | | `/api/context/rtk/test` | POST | Rulează previzualizarea/testul RTK asupra unei încărcături utile textuale | | `/api/context/rtk/raw-output/[id]` | GET | Citește ieșirea brută redactată și păstrată, folosind ID-ul indicatorului | | `/api/context/combos` | GET/POST | Listează/creează combinații de compresie | | `/api/context/combos/[id]` | GET/PUT/DELETE | Detalii/actualizare/ștergere pentru combinația de compresie | | `/api/context/combos/[id]/assignments` | GET/PUT | Atribuie combinații de compresie combinațiilor de rutare | | `/api/context/analytics` | GET | Alias pentru analiza compresiei | ### Monitorizare | Endpoint | Metodă | Descriere | | ------------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/sessions` | GET | Urmărirea sesiunilor active | | `/api/rate-limits` | GET | Limite de rată pentru fiecare cont | | `/api/monitoring/health` | GET | Verificarea stării + rezumatul furnizorilor (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). Vizualizarea de administrare include `credentialHealth`: valori scalare din memoria cache a sondelor, `failedConnections` când `failed>0` și `staleDbNonOkCount` (`test_status` persistent din SQLite, nu indicatorul). Consultați [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). | | `/api/cache/stats` | GET/DELETE | Statistici cache / golire | | `/api/modality-bridge/stats` | GET | Valorile din memorie pentru `attempts`, reușite/`bridged`, eșecuri, accesări ale memoriei cache, `totalLatencyMs`, `latencySamples`, `averageLatencyMs` calculată pe baza numărului de eșantioane și ora ultimei utilizări (se resetează la repornire; necesită autentificare de administrare) | | `/api/modality-bridge/video/runtime` | GET | Verificare strictă a buclei locale de încredere înainte de autentificarea/sondarea de administrare; disponibilitatea și versiunile FFmpeg/ffprobe igienizate (fără stocare) | | `/api/modality-bridge/video/extract` | POST | Broker intern de octeți, autentificat, pentru bucla locală de încredere; intrare de 50 MiB, coadă limitată/ieșire de 32 MiB, capacitate `503`, deconectare `499`, termen-limită `504`; nu este un API public de încărcare | ### Copiere de rezervă și export/import | Endpoint | Metodă | Descriere | | --------------------------- | ------ | ------------------------------------------------------- | | `/api/db-backups` | GET | Listează copiile de rezervă disponibile | | `/api/db-backups` | PUT | Creează manual o copie de rezervă | | `/api/db-backups` | POST | Restaurează dintr-o anumită copie de rezervă | | `/api/db-backups/export` | GET | Descarcă baza de date ca fișier .sqlite | | `/api/db-backups/import` | POST | Încarcă un fișier .sqlite pentru a înlocui baza de date | | `/api/db-backups/exportAll` | GET | Descarcă o copie de rezervă completă ca arhivă .tar.gz | ### Sincronizare în cloud | Endpoint | Metodă | Descriere | | ---------------------- | ------- | ----------------------------------- | | `/api/sync/cloud` | Diverse | Operațiuni de sincronizare în cloud | | `/api/sync/initialize` | POST | Inițializează sincronizarea | | `/api/cloud/*` | Diverse | Gestionarea cloudului | ### Tuneluri | Endpoint | Metodă | Descriere | | -------------------------- | ------ | --------------------------------------------------------------------------------------- | | `/api/tunnels/cloudflared` | GET | Citește starea instalării și a rulării Cloudflare Quick Tunnel pentru panoul de control | | `/api/tunnels/cloudflared` | POST | Activează sau dezactivează Cloudflare Quick Tunnel (`action=enable/disable`) | | `/api/tunnels/ngrok` | GET | Citește starea de rulare a tunelului ngrok pentru panoul de control | | `/api/tunnels/ngrok` | POST | Activează sau dezactivează tunelul ngrok (`action=enable/disable`) | ### Instrumente CLI | Endpoint | Metodă | Descriere | | ---------------------------------- | ------ | --------------------------- | | `/api/cli-tools/claude-settings` | GET | Starea CLI Claude | | `/api/cli-tools/codex-settings` | GET | Starea CLI Codex | | `/api/cli-tools/droid-settings` | GET | Starea CLI Droid | | `/api/cli-tools/openclaw-settings` | GET | Starea CLI OpenClaw | | `/api/cli-tools/runtime/[toolId]` | GET | Mediu de rulare CLI generic | Răspunsurile CLI includ: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. ### Agenți ACP | Endpoint | Metodă | Descriere | | ----------------- | ------ | ------------------------------------------------------------------------------------- | | `/api/acp/agents` | GET | Listează toți agenții detectați (încorporați + personalizați), împreună cu starea lor | | `/api/acp/agents` | POST | Adaugă un agent personalizat sau reîmprospătează memoria cache de detectare | | `/api/acp/agents` | DELETE | Elimină un agent personalizat prin parametrul de interogare `id` | Răspunsul GET include `agents[]` (id, name, binary, version, installed, protocol, isCustom) și `summary` (total, installed, notFound, builtIn, custom). ### Reziliență și limite de rată | Endpoint | Metodă | Descriere | | --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------- | | `/api/resilience` | GET/PATCH | Obține/actualizează coada de cereri, perioada de pauză a conexiunii, întrerupătorul furnizorului și setările de așteptare | | `/api/resilience/reset` | POST | Resetează întrerupătoarele de circuit ale furnizorilor | | `/api/resilience/model-cooldowns` | GET | Listează blocările active per (furnizor, conexiune, model), sortate după timpul rămas | | `/api/resilience/model-cooldowns` | DELETE | Elimină o blocare de model — corpul `{provider, model}` sau `{all: true}` pentru a elimina totul | | `/api/rate-limits` | GET | Starea limitelor de rată per cont | | `/api/rate-limit` | GET | Configurația globală a limitei de rată | > Toate cele patru rute `/api/resilience/*` necesită **autentificare de administrare** (`requireManagementAuth`). Consultați [Reziliență (extinsă)](#resilience-extended) pentru o prezentare completă a diferențelor dintre întrerupătorul furnizorului, perioada de pauză a conexiunii și blocarea modelului. ### Evaluări | Endpoint | Metodă | Descriere | | ------------ | -------- | ------------------------------------------------ | | `/api/evals` | GET/POST | Listează suitele de evaluare / rulează evaluarea | ### Politici | Endpoint | Metodă | Descriere | | --------------- | --------------- | -------------------------------- | | `/api/policies` | GET/POST/DELETE | Gestionează politicile de rutare | ### Conformitate | Endpoint | Metodă | Descriere | | --------------------------- | ------ | ------------------------------------------------------------- | | `/api/compliance/audit-log` | GET | Jurnal de audit pentru conformitate (ultimele N înregistrări) | ### v1beta (compatibil cu Gemini) | Endpoint | Metodă | Descriere | | -------------------------- | ------ | ---------------------------------- | | `/v1beta/models` | GET | Listează modelele în format Gemini | | `/v1beta/models/{...path}` | POST | Endpoint Gemini `generateContent` | Aceste endpointuri reproduc formatul API-ului Gemini pentru clienții care necesită compatibilitate nativă cu SDK-ul Gemini. ### API-uri interne / de sistem | Endpoint | Metodă | Descriere | | ------------------------ | ------ | ---------------------------------------------------------------- | | `/api/init` | GET | Verificarea inițializării aplicației (utilizată la prima rulare) | | `/api/tags` | GET | Etichete de model compatibile cu Ollama (pentru clienții Ollama) | | `/api/restart` | POST | Declanșează repornirea controlată a serverului | | `/api/shutdown` | POST | Declanșează oprirea controlată a serverului | | `/api/system/env/repair` | POST | Repară variabilele de mediu ale furnizorului OAuth | > **Notă:** Aceste endpoint-uri sunt utilizate intern de sistem sau pentru compatibilitatea cu clienții Ollama. De regulă, acestea nu sunt apelate de utilizatorii finali. ### Repararea mediului OAuth _(v3.6.1+)_ ```bash POST /api/system/env/repair Content-Type: application/json { "provider": "claude-code" } ``` Repară variabilele de mediu OAuth lipsă sau corupte pentru un anumit furnizor. Returnează: ```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" } ``` --- ## Transcriere audio ```bash POST /v1/audio/transcriptions Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` Transcrieți fișiere audio folosind orice furnizor STT configurat. Primul segment al căii selectează furnizorul nativ (`openai/…`, `deepgram/…`). Gateway-urile care reexportă modelul altui furnizor utilizează un id calificat (`openrouter/deepgram/nova-3`). **Cerere:** ```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" ``` **Răspuns:** ```json { "text": "Bună, acesta este conținutul audio transcris.", "task": "transcribe", "language": "en", "duration": 12.5 } ``` **Exemple de id-uri de modele:** `openai/whisper-1` (necesită o cheie OpenAI), `openrouter/deepgram/nova-3` (necesită o cheie OpenRouter), `deepgram/nova-3` (necesită o cheie Deepgram nativă). O cerere simplă `deepgram/nova-3` **nu** utilizează OpenRouter. **Formate acceptate:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- ## Compatibilitate Ollama Pentru clienții care utilizează formatul API Ollama: ```bash # Endpoint de chat (format Ollama) POST /v1/api/chat # Listarea modelelor (format Ollama) GET /api/tags ``` Cererile sunt traduse automat între formatele Ollama și cele interne. ## Aliasuri tokenizate pentru VS Code / fără antet Utilizați aceste aliasuri atunci când o integrare nu poate introduce un antet `Authorization` și necesită încorporarea cheii API în URL-ul de bază. ```bash # Alias pentru catalog în stil OpenAI GET /api/v1/vscode/{token}/ GET /api/v1/vscode/{token}/models # Aliasuri pentru chat în stil OpenAI POST /api/v1/vscode/{token}/chat/completions POST /api/v1/vscode/{token}/responses # Aliasuri în stil Ollama POST /api/v1/vscode/{token}/api/chat GET /api/v1/vscode/{token}/api/tags ``` Exemplu: ```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":"salut"}]}' ``` Note: - Aliasurile tokenizate reutilizează aceleași rutine de gestionare ca `/v1/*` și `/api/tags`; structurile răspunsurilor rămân identice. - Preferați `Authorization: Bearer ...` ori de câte ori clientul acceptă anteturi personalizate. - Tokenurile bazate pe URL pot apărea în jurnalele proxy-ului invers, istoricul browserului și telemetria din afara OmniRoute. Tratați-le ca pe o opțiune de compatibilitate, nu ca pe modul implicit de autentificare. --- ## Telemetrie ```bash # Obține rezumatul telemetriei latenței (p50/p95/p99 pentru fiecare furnizor) GET /api/telemetry/summary ``` **Răspuns:** ```json { "providers": { "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } } } ``` --- ## Buget ```bash # Obține starea bugetului pentru toate cheile API GET /api/usage/budget # Setează sau actualizează un buget 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" } ``` > **Note privind schema** (`setBudgetSchema`): `apiKeyId` este obligatoriu; cel puțin una dintre valorile `dailyLimitUsd`, `weeklyLimitUsd` sau `monthlyLimitUsd` trebuie să fie mai mare decât zero. Câmpuri opționale: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Formatul învechit `{keyId, limit, period}` returnează `400 Bad Request`. ## Limite de tokenuri Bugete de **tokenuri** per cheie API (distincte de bugetul bazat pe USD de mai sus). Sunt aplicate direct în fluxul de procesare a cererii: când utilizarea din intervalul curent al unei chei atinge limita, cererile sunt respinse cu `429 Too Many Requests`. Limitele pot fi restrânse la un anumit `model`, la un `provider` sau pot fi aplicate `global` pentru întreaga cheie; când mai multe limite corespund unei cereri, se aplică cea mai restrictivă. ```bash # Listează limitele de tokenuri ale unei chei (include utilizarea curentă din interval) GET /api/usage/token-limits?apiKeyId=key-123 # Creează sau actualizează o limită de tokenuri POST /api/usage/token-limits Content-Type: application/json { "apiKeyId": "key-123", "scopeType": "model", "scopeValue": "openai/gpt-4o", "tokenLimit": 1000000, "resetInterval": "monthly", "enabled": true } # Șterge o limită de tokenuri după id DELETE /api/usage/token-limits?id=tl-abc ``` > **Note despre schemă** (`setTokenLimitSchema`): `apiKeyId` și `scopeType` (`model` | `provider` | `global`) sunt obligatorii. `scopeValue` este obligatoriu, cu excepția cazului în care `scopeType` este `global` (de exemplu, un id de model pentru domeniul `model`, un id de furnizor pentru domeniul `provider`). `tokenLimit` trebuie să fie un număr întreg pozitiv (convertit din șir). Opționale: `id` (omiteți-l pentru creare, furnizați-l pentru actualizare), `resetInterval` (`daily` | `weekly` | `monthly`, valoare implicită `monthly`), `resetTime` (`HH:MM`), `enabled` (valoare implicită `true`). Răspunsurile `GET` completează fiecare limită cu `tokensUsed`, `remaining`, `windowStart`, `periodStartAt` și `nextResetAt`. Acesta este un endpoint din clasa de administrare (autentificarea este aplicată central de fluxul de autorizare). ## Procesarea cererilor 1. Clientul trimite cererea către `/v1/*` 2. Handlerul rutei apelează `handleChat`, `handleEmbedding`, `handleAudioTranscription` sau `handleImageGeneration` 3. Modelul este rezolvat (furnizor/model direct sau alias/combinație) 4. Credențialele sunt selectate din baza de date locală, cu filtrare în funcție de disponibilitatea contului 5. Pentru chat: `handleChatCore` verifică memoria cache semantică/de semnături și rezolvă setările de compresie ale combinației 6. Compresia proactivă rulează înainte de conversia pentru furnizor atunci când este activată (`lite`, Caveman, RTK sau în stivă) 7. Executorul furnizorului trimite cererea în amonte 8. Răspunsul este convertit înapoi în formatul clientului (chat) sau returnat ca atare (încorporări/imagini/audio) 9. Sunt înregistrate utilizarea, analizele de compresie și jurnalele cererilor 10. Mecanismul de rezervă este aplicat în caz de erori, conform regulilor combinației Referință completă pentru arhitectură: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md) --- ## Gestionarea combinațiilor Combinațiile de rutare de nivel superior (deja rezumate în secțiunea `/api/combos*`) pot fi, de asemenea, mapate 1:1 dintr-un șablon de id de model, permițând redirecționarea transparentă a unui id de model în stil OpenAI către o combinație. | Metodă | Cale | Descriere | | ------ | -------------------------------- | -------------------------------------------------------------------------------- | | GET | `/api/model-combo-mappings` | Listează toate mapările model→combinație | | POST | `/api/model-combo-mappings` | Creează o mapare — corp: `{pattern, comboId, priority?, enabled?, description?}` | | GET | `/api/model-combo-mappings/[id]` | Preia o singură mapare | | PUT | `/api/model-combo-mappings/[id]` | Actualizează câmpurile unei mapări existente | | DELETE | `/api/model-combo-mappings/[id]` | Elimină o mapare | **Autentificare:** sesiune/cheie API de administrare (`requireManagementAuth`). --- ## Webhook-uri Abonamente webhook de ieșire pentru evenimentele OmniRoute (finalizarea solicitării, epuizarea cotei, rotația cheilor etc.). | Metodă | Cale | Descriere | | ------ | ------------------------- | --------------------------------------------------------------------------------------- | | GET | `/api/webhooks` | Listează webhook-urile (secretele sunt mascate ca `...`) | | POST | `/api/webhooks` | Creează un webhook — corp: `{url, events?: ["*"], secret?, description?}` | | GET | `/api/webhooks/[id]` | Preia un webhook | | PUT | `/api/webhooks/[id]` | Actualizează url/events/secret/description | | DELETE | `/api/webhooks/[id]` | Elimină un webhook | | POST | `/api/webhooks/[id]/test` | Trimite o sarcină utilă de test către URL-ul webhook-ului și returnează starea livrării | **Autentificare:** sesiune de administrare/cheie API (`requireManagementAuth`). --- ## Chei înregistrate (gestionare automată) Utilizate de subsistemul de gestionare automată a cheilor pentru a emite și roti chei API prin intermediul unui furnizor/cont subiacent, cu cote zilnice/orare. | Metodă | Cale | Descriere | | ------ | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/registered-keys` | Listează cheile înregistrate (doar prefixul mascat) | | POST | `/api/v1/registered-keys` | Emite o cheie nouă înregistrată — corp: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Returnează cheia brută **o singură dată**. Returnează `429` dacă solicitarea este refuzată din cauza cotei. | | GET | `/api/v1/registered-keys/[id]` | Preia metadatele unei chei înregistrate (fără materialul brut) | | DELETE | `/api/v1/registered-keys/[id]` | Revocă o cheie înregistrată | | POST | `/api/v1/registered-keys/[id]/revoke` | Endpoint pentru revocare explicită (același efect ca DELETE) | **Autentificare:** cheie API Bearer (`isAuthenticated`). Consultați și `/v1/quotas/check` și `/v1/issues/report`. --- ## Protocolul agenților Sarcini ale agenților cloud (Claude Code, Codex Cloud, OpenHands etc.) executate de la distanță în numele utilizatorilor OmniRoute. | Metodă | Cale | Descriere | | ------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/v1/agents/tasks` | Listează sarcinile — opțional `?provider=`, `?status=`, `?limit=` (1–500, implicit 50) | | POST | `/api/v1/agents/tasks` | Creează o sarcină — corp validat de `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Returnează `201` cu anvelopa sarcinii | | DELETE | `/api/v1/agents/tasks?id=...` | Șterge o sarcină | | GET | `/api/v1/agents/tasks/[id]` | Citește sarcina — actualizează sincron starea de la agentul cloud din amonte atunci când este setat un `external_id` | | POST | `/api/v1/agents/tasks/[id]` | Acțiune discriminatorie: `{action: "approve"}`, `{action: "message", message}` sau `{action: "cancel"}` | | DELETE | `/api/v1/agents/tasks/[id]` | Șterge o anumită sarcină după id | > **Autentificare:** autentificarea de administrare este obligatorie pentru fiecare metodă (`requireCloudAgentManagementAuth`). Înainte de v3.8.0, acestea nu necesitau autentificare — consultați commitul `588a0333` pentru modificarea incompatibilă. ```bash # Creează o sarcină cloud 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":"..."}}' ``` --- ## Proxy-uri de administrare Proxy-uri HTTP(S)/SOCKS de ieșire care pot fi atribuite furnizorilor, conturilor sau la nivel global. | Metodă | Cale | Descriere | | ------ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/management/proxies` | Listează proxy-urile (cu `?id=` returnează unul; cu `?id=&where_used=1` returnează graful atribuirilor) | | POST | `/api/v1/management/proxies` | Creează un proxy — corp validat de `createProxyRegistrySchema` | | PATCH | `/api/v1/management/proxies` | Actualizează proxy-ul — corp validat de `updateProxyRegistrySchema` (necesită `id`) | | DELETE | `/api/v1/management/proxies?id=...&force=1` | Șterge proxy-ul (utilizați `force=1` pentru a elimina atribuirile) | | GET | `/api/v1/management/proxies/assignments` | Listează atribuirile — filtrabile după `proxy_id`, `scope`, `scope_id`; transmiteți `resolve_connection_id=` pentru a determina proxy-ul activ al unei conexiuni | | PUT | `/api/v1/management/proxies/assignments` | Atribuie — corp validat de `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Golește memoria cache a dispecerului | | PUT | `/api/v1/management/proxies/bulk-assign` | Atribuie în masă — corp validat de `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) | | GET | `/api/v1/management/proxies/health?hours=24` | Agregă starea de funcționare a proxy-urilor (număr de reușite/eșecuri, latență) pe parcursul unui interval | **Autentificare:** sesiune de administrare/cheie API obligatorie pentru fiecare rută (`requireManagementAuth`). > Rutele `POST /api/v1/management/proxies/[id]/assignments` și `POST /api/v1/management/proxies/[id]/health` din descrierea sarcinii sunt deservite de rutele plate `/assignments` și `/health` prezentate mai sus — în baza de cod nu există subrute per id. --- ## Reziliență (extinsă) OmniRoute expune trei mecanisme independente pentru gestionarea defecțiunilor temporare; endpointurile de administrare de mai jos le permit operatorilor să le consulte și să le suprascrie: | Domeniu | Stocarea stării | Consultare | Resetare / ștergere | | ---------------------------------- | ----------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------- | | Circuit breaker al furnizorului | `domain_circuit_breakers` + în memorie | `/api/monitoring/health` | `POST /api/resilience/reset` | | Perioadă de așteptare a conexiunii | `rateLimitedUntil` pentru conexiunile furnizorului | `/api/rate-limits`, `/api/providers/[id]` | (se reactivează la nevoie; ștergere prin PUT pentru furnizor) | | Blocarea modelului | Registru în memorie pentru disponibilitatea modelelor | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` | `PATCH /api/resilience` acceptă suprascrieri pentru circuit breaker-ul furnizorului în `providerBreaker.oauth` și `providerBreaker.apikey`. Fiecare profil acceptă `degradationThreshold`, `failureThreshold` și `resetTimeoutMs`; aceleași câmpuri sunt disponibile în Tablou de bord → Setări → Reziliență. ```bash # Șterge blocarea unui singur 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"}' # Șterge toate blocările curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \ -H "Cookie: auth_token=..." \ -d '{"all":true}' ``` Pentru referința conceptuală completă și valorile implicite ale circuit breaker-ului, consultați [`CLAUDE.md`](../../CLAUDE.md) → „Starea de execuție a rezilienței”. --- ## Abilități Cadru pentru extinderea OmniRoute cu gestionari executabili personalizați, împreună cu integrări pentru marketplace. | Metodă | Cale | Descriere | | ------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/skills` | Listează abilitățile instalate — filtrabile după `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, cu paginare | | GET | `/api/skills/[id]` | Preia o abilitate | | PUT | `/api/skills/[id]` | Actualizează abilitatea (nume, descriere, mod, schemă, gestionar, etichete) | | DELETE | `/api/skills/[id]` | Dezinstalează o abilitate | | POST | `/api/skills/install` | Instalează o abilitate dintr-un manifest brut — corp: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` | | GET | `/api/skills/executions` | Listează execuțiile recente ale abilităților (jurnal de audit cu intrări/ieșiri/durată) | | GET | `/api/skills/marketplace?q=...` | Căutare/listă cu elemente populare din marketplace-ul SkillsMP (necesită setarea `skillsmpApiKey`) | | POST | `/api/skills/marketplace/install` | Instalează o abilitate după id din SkillsMP | | GET | `/api/skills/skillssh?q=&limit=` | Caută în registrul skills.sh | | POST | `/api/skills/skillssh/install` | Instalează o abilitate după id din skills.sh | **Autentificare:** sesiune de administrare/cheie API. Rutele de căutare în marketplace acceptă fie autentificarea de administrare, fie o cheie API Bearer (`isAuthenticated`). --- ## Memorie Stocare persistentă pentru memoria conversațională/factuală, delimitată per cheie API/sesiune. | Metodă | Cale | Descriere | | ------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------- | | GET | `/api/memory` | Listează memoriile — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, cu paginare prin `offset/limit` sau `page/limit` | | POST | `/api/memory` | Creează o memorie — corp validat de Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` | | GET | `/api/memory/[id]` | Preia o memorie | | DELETE | `/api/memory/[id]` | Șterge o memorie | | GET | `/api/memory/health` | Starea subsistemului de memorie (conectivitatea bazei de date, backendul pentru embeddings, starea indexului vectorial) | **Autentificare:** sesiune de administrare/cheie API (`requireManagementAuth`). Enumerarea `type`: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (consultați `MemoryType` în `src/lib/memory/types.ts`). --- ## Server MCP OmniRoute include un server Model Context Protocol încorporat, cu 3 transporturi (stdio, SSE, streamable-http) și instrumente cu domeniu de acces. Endpointurile panoului de control de mai jos citesc date despre stare/audit și intermediază transporturile HTTP. | Metodă | Cale | Descriere | | ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- | | GET | `/api/mcp/status` | Semnal de activitate, transport, stare online, ultimul apel, instrumente principale, rata de succes în ultimele 24 de ore | | GET | `/api/mcp/tools` | Lista instrumentelor MCP cu `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` | | GET | `/api/mcp/sse` | Deschide fluxul SSE pentru transportul SSE (returnează `503` dacă MCP este dezactivat sau transportul nu corespunde) | | POST | `/api/mcp/sse` | Trimite un cadru JSON-RPC prin transportul SSE | | GET | `/api/mcp/stream` | Deschide partea SSE a transportului Streamable HTTP (mesaje inițiate de server) | | POST | `/api/mcp/stream` | Trimite un cadru JSON-RPC prin transportul Streamable HTTP | | DELETE | `/api/mcp/stream` | Încheie o sesiune Streamable HTTP | | GET | `/api/mcp/audit` | Interoghează jurnalul de audit — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` | | GET | `/api/mcp/audit/stats` | Statistici de audit agregate (totaluri, rată de succes, durată medie, instrumente principale) | **Autentificare:** transporturile `sse`/`stream` respectă mecanismul de autentificare specific MCP (cheie API Bearer cu domeniul de acces `mcp`); rutele `status`/`tools`/`audit*` pot fi citite din panoul de control (nu este necesară nicio autentificare suplimentară în afară de accesul la gazda panoului de control). > Ambele transporturi HTTP sunt controlate de `settings.mcpEnabled` și `settings.mcpTransport` — o neconcordanță a transportului returnează `400`, iar o stare MCP dezactivată returnează `503`. --- ## Server A2A OmniRoute expune un endpoint A2A (Agent-la-Agent) JSON-RPC 2.0, plus un wrapper REST pentru inspectare/utilizare în panoul de control. ### JSON-RPC ```bash POST /a2a Authorization: Bearer your-api-key # opțional, cu excepția cazului în care OMNIROUTE_API_KEY este setată Content-Type: application/json { "jsonrpc": "2.0", "id": 1, "method": "message/send", "params": { "skill": "smart-routing", "messages": [{"role": "user", "content": "Direcționează această sarcină de programare"}] } } ``` Metode acceptate (toate controlate de `settings.a2aEnabled`): | Metodă | Descriere | | ---------------- | ------------------------------------------------------------------------- | | `message/send` | Executare sincronă a abilității; returnează `{task, artifacts, metadata}` | | `message/stream` | Executare SSE în flux a aceluiași set de abilități | | `tasks/get` | Preia o sarcină după `taskId` | | `tasks/cancel` | Anulează o sarcină după `taskId` | Abilități încorporate: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`. ### Fișa agentului ```bash GET /.well-known/agent.json ``` Returnează fișa publică a agentului A2A (nume, descriere, capabilități, catalog de abilități, schemă de autentificare) — memorată în cache public timp de 1h. Nu este necesară autentificarea. ### Utilitare REST | Metodă | Cale | Descriere | | ------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | GET | `/api/a2a/status` | Starea de activare A2A + statistici despre sarcini + rezumatul fișei agentului din cache | | GET | `/api/a2a/tasks` | Listează sarcinile — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` | | POST | `/api/a2a/tasks` | (Neimplementat ca utilitar REST — creați prin JSON-RPC `message/send`) | | GET | `/api/a2a/tasks/[id]` | Preia o sarcină | | POST | `/api/a2a/tasks/[id]/cancel` | Anulează o sarcină | **Autentificare:** utilitarele REST rulează fără autentificare de administrare (pot fi citite din panoul de control); ruta JSON-RPC `/a2a` utilizează Bearer `OMNIROUTE_API_KEY` dacă este configurată. --- ## Cloud, evaluări și analiză | Metodă | Cale | Descriere | | ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- | | POST | `/api/cloud/auth` | Verifică o cheie Bearer și returnează conexiunile mascate ale furnizorilor + aliasurile modelelor pentru clienții de sincronizare cloud | | POST | `/api/cloud/credentials/update` | Actualizează acreditările criptate pentru un furnizor sincronizat în cloud | | POST | `/api/cloud/model/resolve` | Rezolvă un ID logic de model într-un furnizor/model concret folosind tabelul local de rutare | | GET | `/api/cloud/models/alias` | Listează aliasurile modelelor așa cum sunt expuse sincronizării cloud | | GET | `/api/assess` | Citește cele mai recente clasificări ale evaluării (per furnizor/model) | | POST | `/api/assess` | Rulează o analiză — corp: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` | | GET | `/api/evals` | Listează suitele de evaluare încorporate + cele mai recente rulări | | POST | `/api/evals` | Declanșează o rulare de evaluare | | POST | `/api/evals/suites` | Creează o suită de evaluare personalizată — corp validat de `evalSuiteSaveSchema` | | GET | `/api/evals/suites/[id]` | Preia o suită de evaluare personalizată | **Autentificare:** `/api/cloud/auth` validează direct o cheie Bearer; celelalte rute `/api/cloud/*`, `/api/evals/*` și `/api/assess` necesită o sesiune/cheie API de administrare. Solicitarea POST către `/api/assess` utilizează `validateBody` cu o schemă de domeniu de tip uniune discriminată. --- ## Gestionarea ACP (Agent Client Protocol) ca procese copil. Aceste endpoint-uri gestionează detectarea agenților ACP și înregistrarea agenților personalizați. | Metodă | Cale | Descriere | | ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/acp/agents` | Listează toți agenții CLI cunoscuți (încorporați + personalizați), împreună cu starea instalării, versiunea și fișierul binar | | POST | `/api/acp/agents` | Înregistrează un agent ACP personalizat sau reîmprospătează memoria cache — corp: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` sau `{action: "refresh"}` | | DELETE | `/api/acp/agents` | Elimină un agent ACP personalizat — parametru de interogare: `?id=` | **Exemplu de răspuns** (`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 } ``` **Autentificare:** Necesită o sesiune de administrare (cookie-ul `auth_token` al panoului de control) sau o cheie API cu domeniu de administrare. Consultați [Cadrul ACP](../frameworks/ACP.md) pentru detalii complete. --- ## Analiză și observabilitate Endpoint-uri de analiză în timp real pentru monitorizarea rutării, compresiei și diversității furnizorilor. Acestea alimentează paginile `/dashboard/analytics/*`. ### Analiza rutării automate | Metodă | Cale | Descriere | | ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/auto-routing` | Statistici agregate privind rutarea automată: total apeluri, distribuția strategiilor, distribuția nivelurilor, furnizorii principali | | GET | `/api/analytics/auto-routing?days=7` | Statistici pentru un interval de timp (implicit 24 h) | **Exemplu de răspuns**: ```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 } ] } ``` ### Analiza compresiei | Metodă | Cale | Descriere | | ------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/compression` | Statistici agregate privind compresia: tokenuri economisite, procentul economisit, distribuția modurilor, utilizarea motoarelor | **Exemplu de răspuns**: ```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 } } ``` ### Urmărirea diversității furnizorilor | Metodă | Cale | Descriere | | ------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/diversity` | Urmărirea diversității pe baza entropiei Shannon: previne punctele unice de defecțiune prin măsurarea distribuției între furnizori | **Exemplu de răspuns**: ```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"] } ``` **Autentificare:** Necesită o sesiune de administrare sau o cheie API cu domeniu de administrare. --- ## Operațiuni de administrare Endpointuri accesibile exclusiv administratorilor pentru gestionarea operațională. | Metodă | Cale | Descriere | | ------ | ------------------------ | ----------------------------------------------------------------------------------------------------- | | GET | `/api/admin/concurrency` | Citește limitele actuale de concurență (globale + per furnizor) | | POST | `/api/admin/concurrency` | Actualizează limitele de concurență — corp: `{global?: number, perProvider?: Record}` | **Autentificare:** Necesită o sesiune de administrare cu domeniu de administrator. --- ## Gestionarea instrumentelor CLI Gestionați instrumentele CLI care se integrează cu OmniRoute (antigravity, chipotle, commandCode, devin-cli etc.). Consultați [Referința furnizorilor](./PROVIDER_REFERENCE.md) pentru lista completă. | Metodă | Cale | Descriere | | ------ | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/cli-tools/all-statuses` | Starea tuturor instrumentelor CLI (instalare, versiune, ultima detectare) | | GET | `/api/cli-tools/status` | Detalii despre starea unui instrument CLI (interogare `?tool=`) | | POST | `/api/cli-tools/apply` | Scrie configurația generată a unui instrument (`dryRun` afișează o previzualizare; `422` + `containerEphemeralTarget` când rulează în container; `migration` indică un fișier YAML Codex moștenit) | | GET | `/api/cli-tools/backups` | Listează copiile de rezervă ale configurațiilor instrumentelor CLI | | POST | `/api/cli-tools/backups` | Creează o copie de rezervă a configurațiilor tuturor instrumentelor CLI | | POST | `/api/cli-tools/backups` | Restaurare: același endpoint, cu `{tool, backupId}` în corp, restaurează copia de rezervă respectivă | | GET | `/api/cli-tools/antigravity-mitm` | Starea proxy-ului MITM Antigravity (instrumentul CLI „antigravity-mitm”) | | POST | `/api/cli-tools/antigravity-mitm/alias` | Configurează aliasurile antigravity-mitm | **Autentificare:** Necesită o sesiune de administrare. --- ## Abilitățile agenților Gestionați abilitățile agenților AI (similare GPT-urilor personalizate OpenAI, dar destinate agenților). | Metodă | Cale | Descriere | | ------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------- | | GET | `/api/agent-skills` | Listează toate abilitățile agenților (încorporate + personalizate) | | GET | `/api/agent-skills/[id]` | Obține o anumită abilitate a unui agent | | POST | `/api/agent-skills` | Creează o abilitate personalizată pentru agent — corp: `{name, description, prompt, model?, temperature?}` | | PUT | `/api/agent-skills/[id]` | Actualizează o abilitate personalizată a unui agent | | DELETE | `/api/agent-skills/[id]` | Șterge o abilitate personalizată a unui agent | | GET | `/api/agent-skills/[id]/raw` | Obține promptul brut + metadatele (fără execuție) | | POST | `/api/agent-skills/generate` | Generează cu AI o abilitate nouă dintr-o descriere în limbaj natural | **Autentificare:** Necesită o sesiune de administrare sau o cheie API cu domeniu de administrare. --- ## Gestionarea cache-ului Gestionați cache-ul semantic și cache-ul de raționament. | Metodă | Cale | Descriere | | ------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/cache` | Prezentare generală a cache-ului: numărul total de intrări, rata de accesare, dimensiunea pe disc | | GET | `/api/cache/entries` | Listează intrările din cache (cu paginare) | | DELETE | `/api/cache/entries` | Șterge intrările din cache (filtrare după parametrii de interogare) | | GET | `/api/cache/stats` | Statistici detaliate despre cache (pentru fiecare furnizor și model) | | GET | `/api/cache/reasoning` | Starea cache-ului de raționament (pentru reluarea raționamentului) | | DELETE | `/api/cache/reasoning` | Golește cache-ul de raționament — parametri de interogare: `?toolCallId=` (unul singur), `?provider=

` sau fără parametri (toate) | **Autentificare:** Necesită o sesiune de administrare. --- ## Sistemul de memorie Gestionați memoria persistentă (FTS5 + înglobări vectoriale). | Metodă | Cale | Descriere | | ------ | ------------------ | ------------------------------------------------------------------------------------ | | GET | `/api/memory` | Listează intrările din memorie (filtrare după domeniu, tip și interogare de căutare) | | POST | `/api/memory` | Creează o intrare nouă în memorie — corp: `{scope, type, content, metadata?}` | | GET | `/api/memory/[id]` | Obține o anumită intrare din memorie | | PUT | `/api/memory/[id]` | Actualizează o intrare din memorie | | DELETE | `/api/memory/[id]` | Șterge o intrare din memorie | | GET | `/api/memory?q=` | Caută în memorie (FTS5 + vectorial) — statisticile sunt incluse în același răspuns | **Autentificare:** Necesită o sesiune de administrare sau o cheie API cu domeniu de administrare. --- ## Webhook-uri Gestionați abonamentele webhook pentru evenimente. | Metodă | Cale | Descriere | | ------ | ------------------------------- | --------------------------------------------------------------------------- | | GET | `/api/webhooks` | Listează toate abonamentele webhook | | POST | `/api/webhooks` | Creează un abonament webhook — corp: `{url, events[], secret?, active?}` | | GET | `/api/webhooks/[id]` | Obține un anumit abonament webhook | | PUT | `/api/webhooks/[id]` | Actualizează un abonament webhook | | DELETE | `/api/webhooks/[id]` | Șterge un abonament webhook | | GET | `/api/webhooks/[id]/deliveries` | Listează istoricul livrărilor pentru un webhook (jurnal de reușite/eșecuri) | | POST | `/api/webhooks/[id]/test` | Trimite un eveniment de test către un webhook | **Autentificare:** Necesită o sesiune de administrare. Consultați [Cadrul pentru webhook-uri](../frameworks/WEBHOOKS.md) pentru lista completă a tipurilor de evenimente. --- ## Cadrul pentru abilități Gestionați abilitățile (cadrul pentru extensii agentice). | Metodă | Cale | Descriere | | ------ | ------------------------ | ---------------------------------------------------------------------------------------------------- | | GET | `/api/skills` | Listează toate abilitățile instalate (încorporate + personalizate) | | POST | `/api/skills/install` | Instalează o abilitate dintr-o cale locală sau de la un URL | | DELETE | `/api/skills/[id]` | Dezinstalează o abilitate | | PUT | `/api/skills/[id]` | Activează sau dezactivează o abilitate — corp: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` | | POST | `/api/skills/executions` | Execută o abilitate — corp: `{skillName, apiKeyId, input?, sessionId?}` | | GET | `/api/skills/executions` | Listează istoricul execuțiilor pentru toate abilitățile (filtrare după `?apiKeyId=`) | **Autentificare:** Necesită o sesiune de administrare sau o cheie API cu domeniu de administrare. Consultați [Cadrul pentru abilități](../frameworks/SKILLS.md) pentru detalii complete. --- ## Pluginuri Gestionați pluginurile OmniRoute (extensii terțe). | Metodă | Cale | Descriere | | ------ | ---------------------------------- | ------------------------------------ | | GET | `/api/plugins` | Listează pluginurile instalate | | POST | `/api/plugins/marketplace/install` | Instalează un plugin din marketplace | | DELETE | `/api/plugins/[name]` | Dezinstalează un plugin | | POST | `/api/plugins/[name]/activate` | Activează un plugin | | POST | `/api/plugins/[name]/deactivate` | Dezactivează un plugin | | GET | `/api/plugins/[name]/config` | Obține configurația pluginului | | PUT | `/api/plugins/[name]/config` | Actualizează configurația pluginului | **Autentificare:** Necesită o sesiune de administrare. Consultați [Cadrul pentru pluginuri](../frameworks/PLUGIN_SDK.md) pentru detalii complete. --- ## Rutare în umbră Compararea în umbră / A-B a furnizorilor **nu reprezintă o suprafață REST de sine stătătoare** — aceasta este configurată prin rutarea combinată (consultați [Combinare automată](../routing/AUTO-COMBO.md)). Metricile de comparare pentru fiecare combinație sunt furnizate prin `GET /api/combos/metrics`. --- ## Mecanisme de protecție Inspectați mecanismele de protecție din timpul execuției (detectarea PII, detectarea injectării de prompturi, intermedierea viziunii). Mecanismele de protecție rulează la fiecare solicitare; excluderea pentru fiecare apel se realizează prin antetul de solicitare `x-omniroute-disabled-guardrails` — nu există o suprafață persistentă pentru activare/dezactivare. | Metodă | Cale | Descriere | | ------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------- | | GET | `/api/guardrails` | Listează mecanismele de protecție înregistrate și starea lor (nume / activat / prioritate) | | POST | `/api/guardrails/test` | Rulează în mod de testare conducta dinaintea apelului pe un exemplu de intrare — corp: `{input, disabledGuardrails?}` | **Autentificare:** Necesită o sesiune de administrare. Consultați [Securitate > Mecanisme de protecție](../security/GUARDRAILS.md) pentru detalii complete. --- --- ## Autentificare Consultați [Autentificarea pentru administrare](../guides/MANAGEMENT-AUTH.md) pentru cele patru familii de acreditări (sesiune în panoul de control, token CLI local, token de acces `oma_live_…`, cheie API cu domeniu de administrare) și modul în care acestea diferă de cheile pentru inferență. - Rutele panoului de control (`/dashboard/*`) utilizează cookie-ul `auth_token` - Autentificarea utilizează hash-ul parolei salvate; alternativ, se utilizează `INITIAL_PASSWORD` - `requireLogin` poate fi activat sau dezactivat prin `/api/settings/require-login` - Rutele `/v1/*` necesită opțional o cheie API Bearer când `REQUIRE_API_KEY=true` - „token de administrare” / „cheie API cu domeniu de administrare” din această referință înseamnă una dintre familiile descrise în ghidul respectiv — nu un tip suplimentar nedefinit de secret > **Modificare incompatibilă (v3.8.0)** — `/api/v1/agents/tasks/*` și punctele finale pentru administrarea perioadei de așteptare necesită acum **autentificare pentru administrare** (cookie-ul `auth_token` al panoului de control sau o cheie API cu domeniu de administrare). Clienții care apelau anterior aceste rute fără autentificare vor primi `401 Unauthorized`. Consultați commitul `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).