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

API Reference (Română)

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

---

🌐 Limbi: 🇺🇸 English | 🇪🇹 አማርኛ | 🇸🇦 العربية | 🇦🇿 Azərbaycan dili | 🇧🇬 Български | 🇧🇩 বাংলা | 🇨🇿 Čeština | 🇩🇰 Dansk | 🇩🇪 Deutsch | 🇬🇷 Ελληνικά | 🇪🇸 Español | 🇪🇪 Eesti | 🇮🇷 فارسی | 🇫🇮 Suomi | 🇫🇷 Français | 🇮🇪 Gaeilge | 🇮🇳 ગુજરાતી | 🇳🇬 Hausa | 🇮🇱 עברית | 🇮🇳 हिन्दी | 🇭🇷 Hrvatski | 🇭🇺 Magyar | 🇦🇲 Հայերեն | 🇮🇩 Bahasa Indonesia | 🇳🇬 Igbo | 🇮🇹 Italiano | 🇯🇵 日本語 | 🇬🇪 ქართული | 🇰🇭 ខ្មែរ | 🇮🇳 ಕನ್ನಡ | 🇰🇷 한국어 | 🇱🇹 Lietuvių | 🇱🇻 Latviešu | 🇮🇳 മലയാളം | 🇮🇳 मराठी | 🇲🇾 Bahasa Melayu | 🇲🇹 Malti | 🇲🇲 မြန်မာ | 🇳🇵 नेपाली | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇮🇳 ଓଡ଼ିଆ | 🇮🇳 ਪੰਜਾਬੀ | 🇵🇭 Filipino | 🇵🇱 Polski | 🇵🇹 Português (Portugal) | 🇧🇷 Português (Brasil) | 🇷🇴 Română | 🇷🇺 Русский | 🇱🇰 සිංහල | 🇸🇰 Slovenčina | 🇸🇮 Slovenščina | 🇷🇸 Српски | 🇸🇪 Svenska | 🇰🇪 Kiswahili | 🇮🇳 தமிழ் | 🇮🇳 తెలుగు | 🇹🇭 ไทย | 🇹🇷 Türkçe | 🇺🇦 Українська | 🇵🇰 اردو | 🇺🇿 Oʻzbekcha | 🇻🇳 Tiếng Việt | 🇳🇬 Yorùbá | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)

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, care poate fi citit automat, și arborele de rute din src/app/api/ reprezintă sursele exhaustive.

---

Cuprins

• Completări de chat
• Contracte de închiriere exclusive pentru sesiuni gestionate
• Încorporări
• Generarea imaginilor
• OCR pentru documente
• Listarea modelelor
• Manifestul pluginului furnizorului
• Endpointuri de compatibilitate
• API pentru fișiere
• API pentru loturi
• API de căutare
• Streaming prin WebSocket
• Cote și raportarea problemelor
• Cache semantic
• Panou de control și administrare
• Administrarea combinațiilor
• Webhookuri
• Chei înregistrate (administrare automată)
• Protocolul agenților
• Proxy-uri de administrare
• Reziliență (extinsă)
• Abilități
• Memorie
• Server MCP
• Server A2A
• Cloud, evaluări și analiză
• Procesarea cererilor
• Autentificare

---

Completări de chat

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=<name>; provider=<alias>; latency_ms=<n> (<name> 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.

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

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

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:

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

{ "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ă:

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

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

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:

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:

{
  "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:<id>	Un singur motor, atunci când este activat, de exemplu engine:rtk.
<combo>	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: <mode>; source=<source>

unde <source> este una dintre valorile request-header, routing-override, active-profile, auto-trigger, default sau off.

---

Embeddings

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

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

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:

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

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

# Listează toate modelele de embeddings
GET /v1/embeddings

---

Generarea imaginilor

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).

# Listează toate modelele de imagini
GET /v1/images/generations

---

OCR pentru documente

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:

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

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:

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.

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/<provider>/<model>

Selectarea acestui id (de ex. într-o configurație Claude Code care atașează întotdeauna un bloc thinking) se rezolvă înapoi la modelul real <provider>/<model>, 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

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.

# 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

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

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)

# 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=<OMNIROUTE_API_KEY>"
# (sau: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# 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/<group>/codex/<model>". 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):

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)

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.

# Format text (contractul istoric — text simplu pentru un terminal)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Format structurat — ceea ce utilizează o interfață
curl -H "Authorization: Bearer <your-api-key>" \
  "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:

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

# Obține statisticile cache-ului
GET /api/cache/stats

# Golește toate cache-urile
DELETE /api/cache/stats

Exemplu de răspuns:

{
  "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]):

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

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.
/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.
/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ă) 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+)

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ă:

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

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:

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:

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

# 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ă.

# 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:

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

# Obține rezumatul telemetriei latenței (p50/p95/p99 pentru fiecare furnizor)
GET /api/telemetry/summary

Răspuns:

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

---

Buget

# 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ă.

# 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

---

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 <prefix>...)
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ă.

# 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=<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ță.

# Ș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 → „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

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

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=<agentId>

Exemplu de răspuns (GET /api/acp/agents):

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

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

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

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

{
  "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<string, number>}

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 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=<id> (unul singur), ?provider=<p> 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 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 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 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ă). 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 pentru detalii complete.

---

---

Autentificare

Consultați Autentificarea pentru administrare 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).