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

API Reference (Italiano)

🌐 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 · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

🌐 Lingue: 🇺🇸 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á | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)

Riferimento principale per l'API OmniRoute. Illustra l'interfaccia pubblica /v1 e gli endpoint di gestione più utilizzati; il file leggibile dalle macchine docs/openapi.yaml e l'albero delle route in src/app/api/ costituiscono le fonti esaustive.

---

Indice

• Completamenti chat
• Lease esclusive per sessioni gestite
• Embedding
• Generazione di immagini
• OCR dei documenti
• Elenco dei modelli
• Manifest del plugin del provider
• Endpoint di compatibilità
• API dei file
• API dei batch
• API di ricerca
• Streaming WebSocket
• Segnalazione di quote e problemi
• Cache semantica
• Dashboard e gestione
• Gestione delle combo
• Webhook
• Chiavi registrate (gestione automatica)
• Protocollo degli agenti
• Proxy di gestione
• Resilienza (estesa)
• Competenze
• Memoria
• Server MCP
• Server A2A
• Cloud, valutazioni e assessment
• Elaborazione delle richieste
• Autenticazione

---

Completamenti chat

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

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "Scrivi una funzione per..."}
  ],
  "stream": true
}

Header personalizzati

Header	Direzione	Descrizione
X-OmniRoute-No-Cache	Richiesta	Impostare su true per ignorare la cache
x-omniroute-no-memory	Richiesta	Impostare su true per saltare l'inserimento di memoria e competenze per questa richiesta (rispecchia no-cache; evita l'overhead di token/costi per chiamata)
X-OmniRoute-Progress	Richiesta	Impostare su true per ricevere eventi di avanzamento
X-Session-Id	Richiesta	Chiave di sessione persistente per l'affinità con sessioni esterne
x_session_id	Richiesta	È accettata anche la variante con trattino basso (HTTP diretto)
X-OmniRoute-Session-Id	Richiesta	Tag di sessione/conversazione fornito dal chiamante (utilizzato anche dalla memoria). Quando presente, viene salvato testualmente in call_logs.session_tag per l'attribuzione dei costi per sessione (#8249) — non viene mai generato se assente
Idempotency-Key	Richiesta	Chiave di deduplicazione (finestra di 5 s)
X-Request-Id	Richiesta	Chiave di deduplicazione alternativa
X-OmniRoute-Cache	Risposta	HIT o MISS (senza streaming)
X-OmniRoute-Idempotent	Risposta	true se deduplicata
X-OmniRoute-Progress	Risposta	enabled se il monitoraggio dell'avanzamento è attivo
X-OmniRoute-Session-Id	Risposta	ID di sessione effettivo utilizzato da OmniRoute
X-OmniRoute-Request-Id	Risposta	ID di correlazione della richiesta (quando noto)
X-OmniRoute-Version	Risposta	Versione della build di OmniRoute (sempre presente)
X-OmniRoute-Cost-Saved	Risposta	Importo in USD risparmiato dalla cache in caso di HIT (solo hit della cache)
X-OmniRoute-Decision	Risposta	Traccia dell'instradamento: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> è la strategia della combo oppure single per una richiesta non combo) — sempre presente nelle risposte di completamento

Nota su Nginx: se si utilizzano header con trattini bassi (ad esempio x_session_id), abilitare underscores_in_headers on;.

Header di telemetria dei costi: anche le risposte di successo non in streaming includono il set di telemetria dei costi X-OmniRoute-* — X-OmniRoute-Response-Cost (USD, con 10 decimali fissi; 0.0000000000 per richieste gratuite/senza prezzo), X-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out, X-OmniRoute-Model, X-OmniRoute-Provider, X-OmniRoute-Latency-Ms, X-OmniRoute-Cache-Hit e X-OmniRoute-Fallback-Attempts (solo quando > 0), oltre a X-OmniRoute-Request-Id e X-OmniRoute-Version. Questi header vengono restituiti dai completamenti chat, da /v1/responses, /v1/messages e dagli endpoint multimediali — /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/rerank, /v1/videos/generations, /v1/music/generations e /v1/moderations (costo sempre pari a 0). Il costo dei contenuti multimediali viene calcolato per modalità (per immagine, per secondo, per carattere, per unità di ricerca) quando sono disponibili informazioni sui prezzi; in caso contrario è pari a 0 (fail-open).

Semantica dei costi per i cache hit: in caso di HIT della cache semantica (X-OmniRoute-Cache-Hit: true) non viene effettuata alcuna chiamata upstream, pertanto X-OmniRoute-Response-Cost è pari a 0.0000000000 (il costo incrementale per servire il risultato dalla cache). Il costo originale/potenziale viene indicato separatamente in X-OmniRoute-Cost-Saved. I sistemi di fatturazione devono sommare X-OmniRoute-Response-Cost (i cache hit non hanno alcun costo); i sistemi di analisi della cache possono aggregare X-OmniRoute-Cost-Saved.

Lease esclusive di sessioni gestite

Il leasing esclusivo di sessioni gestite è un contratto di routing opzionale e indipendente dal client: un unico proprietario attivo detiene una connessione OmniRoute idonea. Non concede in leasing un modello, non richiede OAuth, non identifica un client specifico e non richiede un provider specifico.

La chiave API usata per l'autenticazione deve avere l'ambito lease:exclusive e un elenco allowedConnections esplicito e non vuoto. Il limite delle mutazioni del database impone la presenza congiunta di entrambi i campi durante la creazione della chiave e gli aggiornamenti parziali.

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

Le risposte riuscite di acquisizione, rinnovo e rilascio espongono i timestamp, state e l'esatto valore positivo di generation, ma mai la connessione selezionata o le credenziali. Il rinnovo e il rilascio specificano la generazione nel corpo JSON:

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

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

Il proprietario di un lease attivo può richiedere esplicitamente metadati di visualizzazione rispettosi della privacy per l'associazione corrente:

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

Questa azione di stato opzionale è protetta, in un'unica transazione del database, dal proprietario opaco, dalla chiave API gestita autenticata e dall'esatta generazione attiva. displayName è esclusivamente il nome configurato della connessione, senza spazi iniziali o finali; è null quando non esiste un nome configurato sicuro. OmniRoute non lo sostituisce mai con un indirizzo e-mail o con un'identità account generata. Il valore del provider è un'etichetta di visualizzazione non sensibile e non è mai un identificatore generato di provider compatibile. Sono esclusi credenziali, token, cookie, ID non elaborati della connessione o della chiave API, hash del proprietario, segreti di fencing e dati di routing interni.

Le ricerche con chiave errata, proprietario errato, generazione obsoleta oppure relative a lease mancanti, scaduti, rilasciati o invalidati restituiscono tutte lo stesso errore 409 LEASE_FENCE_STALE, senza metadati della connessione. Un client che ha ricevuto la risposta di attesa della capacità non dispone di alcuna associazione attiva da esaminare. Quando il routing modifica la connessione di un lease attivo, la stessa generazione rimane valida e lo stato restituisce atomicamente la nuova associazione, mai quella precedente. I client esistenti non subiscono modifiche, perché le risposte di acquisizione, rinnovo, rilascio e attesa mantengono i formati precedenti.

Questo contratto del server non modifica /status di OpenAI Codex standard. Attualmente, Codex standard segnala il proprio provider del modello e lo stato integrato di autenticazione/account, ma non visualizza metadati account arbitrari di provider personalizzati; una futura integrazione client dovrà chiamare questa azione e decidere come visualizzare connection.displayName.

Ogni richiesta di inferenza gestita fornisce quindi entrambe le intestazioni di controllo:

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

Il proprietario esatto, la generazione, la connessione attiva e la chiave API autenticata vengono sottoposti a fencing immediatamente prima di ogni tentativo upstream supportato. La riproduzione del proprietario e della generazione con un'altra chiave non riesce anche quando tale chiave consente la stessa connessione. I proprietari non elaborati non vengono resi persistenti, registrati nei log, conservati nello snapshot della richiesta o inoltrati upstream.

La contesa temporanea restituisce HTTP 429 con Retry-After e:

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

Questa risposta indica soltanto che l'insieme ordinario di connessioni idonee non era vuoto e che ogni candidato libero era detenuto da un lease attivo di un altro proprietario. Modelli/provider non supportati, mancata corrispondenza con i criteri, cooldown, quota, integrità e altri normali errori di idoneità mantengono le risposte OmniRoute esistenti.

x-omniroute-compression

Override del piano di compressione per la singola richiesta. Ha la precedenza più alta: prevale sull'override della combinazione di routing, sul profilo attivo, sull'attivazione automatica e sul valore Default del pannello. Valori:

Valore	Effetto
off	Nessuna compressione per questa richiesta.
default	Il profilo Default derivato dal pannello (ignora il profilo attivo).
engine:<id>	Un singolo motore, se abilitato, ad es. engine:rtk.
<combo>	Una combinazione denominata, confrontata prima per nome (senza distinzione tra maiuscole e minuscole), quindi per ID.

Note:

• I valori sconosciuti vengono ignorati (la richiesta non viene mai rifiutata); la risoluzione prosegue secondo il normale ordine di precedenza degli operatori.
• Se più combinazioni condividono lo stesso nome, specificare l'id della combinazione per ottenere una corrispondenza deterministica.
• Una combinazione il cui nome è off o default non può essere selezionata per nome (queste parole chiave vengono interpretate per prime); fare riferimento a tale combinazione tramite il relativo ID.
• L'interruttore principale della compressione è un vincolo assoluto: quando la compressione è disabilitata globalmente, questa intestazione non può abilitarla.

Il piano applicato viene restituito nell'intestazione della risposta:

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

dove <source> è uno tra request-header, routing-override, active-profile, auto-trigger, default o off.

---

Embedding

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

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

Provider disponibili: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, Jina AI.

Gli ID del catalogo sono nel formato provider/model (esempio: jina-ai/jina-embeddings-v5-omni-small). Vengono risolti anche gli ID dei modelli Jina senza prefisso presenti nel registro (ad esempio jina-embeddings-v5-text-small, jina-reranker-v3.5). Le operazioni Jina di embedding/reranking/classificazione/segmentazione usano innanzitutto le credenziali jina-ai della dashboard; JINA_AI_API_KEY viene usata come alternativa solo quando non esiste alcuna chiave nella dashboard. La scheda jina-reader è destinata esclusivamente a Reader / r.jina.ai (POST /v1/web/fetch) e non fornisce mai embedding o reranking.

I modelli del registro che dichiarano il supporto multimodale accettano anche fino a 32 elementi strutturati indipendenti dal provider. I tipi di elementi multimediali sono text, image, audio, video e document. Il relativo source multimediale può essere {"type":"url","url":"https://..."} oppure {"type":"base64","data":"...","media_type":"..."}.

Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano e l'alias di famiglia jina-ai/jina-embeddings-v5-omni → omni-small) accetta anche i documenti EmbeddingsV5Request nativi di Jina e li inoltra senza modificarli a 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,..." }]
    }
  ]
}

I valori nativi { image | audio | video | pdf } possono essere un URL HTTPS pubblico, un URI data: o dati base64 non elaborati. OmniRoute non converte tali oggetti in stringhe né recupera gli URL delle immagini native: Jina recupera direttamente i contenuti multimediali pubblici. I campi Jina aggiuntivi (task, normalized, truncate, embedding_type) vengono inoltrati. Gli SKU Jina di solo testo continuano a rifiutare i documenti non testuali.

Limiti di sicurezza e trasporto:

• Gli URL dei contenuti multimediali remoti devono essere HTTPS pubblici. Gli elementi canonici {type,source:url} vengono recuperati lato server (con nuova convalida dei reindirizzamenti, timeout, limiti di dimensione, DNS pubblico e blocco della connessione) e incorporati prima della chiamata al provider. Gli elementi Jina nativi {image:"https://..."} vengono inoltrati così come sono dopo lo stesso controllo HTTPS pubblico; Jina recupera l'URL.
• I contenuti multimediali base64 incorporati sono limitati a 8 MiB decodificati per elemento e a 16 MiB decodificati nell'intera richiesta.

Traduzione per provider (gli elementi canonici non vengono mai inoltrati senza modifiche):

• Modelli multimodali Jina: ogni elemento di primo livello diventa un oggetto con chiave corrispondente alla modalità (text / image / audio / video / pdf), utilizzando URI di dati per i contenuti multimediali incorporati; un vettore per ogni elemento di primo livello.
• Famiglia Gemini Embedding 2: un array di primo livello diventa una singola richiesta nativa models/{model}:embedContent con content.parts (text o inline_data).
• I modelli sconosciuti/dinamici senza metadati espliciti sulla modalità rifiutano l'input strutturato con 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"
}

Le combinazioni modello/modalità non supportate restituiscono HTTP 400 anziché convertire forzatamente l'elemento. I campi di estensione diversi da input nelle richieste legacy con stringhe/token continuano a essere trasmessi senza modifiche.

# Elenca tutti i modelli di embedding
GET /v1/embeddings

---

Generazione di immagini

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

{
  "model": "openai/gpt-image-2",
  "prompt": "Un bellissimo tramonto sulle montagne",
  "size": "1024x1024"
}

Provider disponibili: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, SD WebUI (locale), ComfyUI (locale).

# Elenca tutti i modelli di immagini
GET /v1/images/generations

---

OCR dei documenti

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 seleziona il provider OCR tramite un prefisso provider/model; un ID modello senza prefisso (ad es. mistral-ocr-latest) viene associato al relativo provider registrato, mentre se model viene omesso, il valore predefinito è Mistral (mistral-ocr-latest). Provider registrati (open-sse/config/ocrRegistry.ts):

ID provider	ID modello	Valore di model	Note
mistral	mistral-ocr-latest	mistral/mistral-ocr-latest (o semplicemente mistral-ocr-latest)	Sincrono: la risposta viene restituita direttamente dall'unica chiamata upstream.
azure-document-intelligence	prebuilt-read	azure-document-intelligence/prebuilt-read	Upstream asincrono (analyze + polling): vedi sotto.
vertex-deepseek-ocr	deepseek-ocr-maas	vertex-deepseek-ocr/deepseek-ocr-maas	Sincrono, tramite l'endpoint partner openapi/chat/completions di Vertex AI: vedi sotto per autenticazione/URL.

Tutti e tre i provider rispondono con lo stesso corpo nel formato di Mistral:

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

Flusso di polling di Azure Document Intelligence

L'API analyze di Azure Document Intelligence è asincrona: la richiesta iniziale restituisce un header Operation-Location anziché un corpo e il risultato deve essere recuperato tramite polling. L'handler (open-sse/handlers/ocr.ts) esegue il polling di tale URL ogni secondo per un massimo di 30 tentativi, termina immediatamente (senza continuare il polling) in caso di risposta di polling diversa da ok o di stato "failed" e restituisce 504 se l'operazione è ancora in esecuzione dopo l'esaurimento del numero di tentativi. La risposta finale di Azure viene normalizzata nello stesso formato pages/markdown utilizzato da Mistral prima di essere restituita al chiamante, pertanto il codice client non deve gestire il provider come caso speciale.

Autenticazione e risoluzione dell'endpoint OCR DeepSeek di Vertex AI

vertex-deepseek-ocr riutilizza la stessa autenticazione Vertex AI già supportata da OmniRoute per il traffico di chat/immagini (open-sse/executors/vertex.ts): la chiave API della connessione può essere una credenziale JSON di un Service Account (scambiata con un token di accesso OAuth di breve durata tramite il flusso JWT-bearer) oppure un token di accesso OAuth già generato, utilizzato così com'è. L'URL dell'endpoint upstream è l'endpoint partner generico openapi/chat/completions di Vertex, creato a partire dal progetto e dalla regione della connessione: un valore esplicito di providerSpecificData.project/providerSpecificData.region ha sempre la precedenza; in caso contrario, il progetto viene ricavato da project_id nel JSON del Service Account e la regione predefinita è us-central1. Entrambe le risoluzioni avvengono in open-sse/handlers/ocr.ts (resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl) e vengono utilizzate da src/app/api/v1/ocr/route.ts prima di inoltrare la richiesta a handleOcr.

---

Elenco dei modelli

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

→ Restituisce tutti i modelli di chat, embedding e immagini, oltre alle combinazioni, nel formato OpenAI

Prefissi degli ID dei modelli (?prefix=)

La maggior parte dei modelli viene pubblicizzata con un prefisso del provider. Il prefisso ricevuto è controllato dal feature flag MODELS_CATALOG_PREFIX_MODE e può essere sovrascritto per ogni richiesta mediante un parametro di query — utile per un client che desidera un elenco pulito senza modificare l'impostazione a livello di server per tutti gli altri:

GET /v1/models?prefix=alias        # un ID per modello — il prefisso alias breve
GET /v1/models?prefix=dual         # entrambe le forme (impostazione predefinita del server)
GET /v1/models?prefix=canonical    # solo il prefisso completo dell'ID del provider

Modalità	Genera	Note
dual	cc/claude-sonnet-4-6 e claude/claude-sonnet-4-6	Predefinita. Entrambi gli ID vengono indirizzati allo stesso modello; vengono mantenuti affinché le configurazioni client che hanno codificato una delle due forme continuino a funzionare. Raddoppia approssimativamente il catalogo.
alias	cc/claude-sonnet-4-6	Una voce per modello. I provider privi di un alias distinto continuano a generare la propria voce, quindi non si perde nulla.
canonical	claude/claude-sonnet-4-6	Una voce per modello con il prefisso completo dell'ID del provider. Anche i provider privi di un alias distinto (ad es. antigravity/…, agy/…) generano qui il proprio unico ID, quindi non si perde nulla.

Un mirror in modalità dual può essere riconosciuto anche senza il parametro di query: contiene un campo parent che punta all'ID principale.

I client che visualizzano un selettore di modelli dovrebbero richiedere ?prefix=alias — è ciò che fa l'estensione OmniCopilot per VS Code.

Varianti dei modelli senza ragionamento

Per i modelli Claude in grado di ragionare, /v1/models pubblicizza anche una variante senza ragionamento il cui ID ha come prefisso claude-3-omniroute-no-thinking/:

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

La selezione di questo ID (ad es. in una configurazione di Claude Code che include sempre un blocco thinking) viene ricondotta al vero <provider>/<model> con il ragionamento disattivato — thinking:{type:"disabled"} nel percorso /v1/messages, oppure con i campi reasoning/reasoning_effort rimossi nel percorso /v1/chat/completions. La variante è elencata solo per i modelli della famiglia Claude che supportano il ragionamento e rispettano disabled (pertanto, ad esempio, sono esclusi i modelli esclusivamente adattivi che rifiutano disabled). Gli operatori possono abilitare o disabilitare forzatamente la variante per ciascun modello tramite ModelSpec.noThinkingAlias.

---

Manifest del plugin del provider

GET /api/v1/provider-plugin-manifest

Restituisce il manifest JSON-safe del plugin del provider utilizzato da Bifrost, CLIProxyAPI e dai futuri router sidecar. La risposta viene generata dal registro dei provider TypeScript ed esclude intenzionalmente i segreti client OAuth, la risoluzione dell'ambiente di runtime, le funzioni executor, le intestazioni delle richieste e i dati degli account.

Utilizzare questo endpoint quando un sidecar viene eseguito fuori processo e non può importare direttamente open-sse/config/providerPluginManifestRegistry.ts.

---

Endpoint di compatibilità

Metodo	Percorso	Formato
POST	/v1/chat/completions	OpenAI
POST	/v1/messages	Anthropic
POST	/v1/responses	OpenAI Responses
POST	/v1/embeddings	OpenAI
POST	/v1/images/generations	OpenAI Images
POST	/v1/images/edits	OpenAI Images (modifica/inpainting)
POST	/v1/videos/generations	Generazione video in stile OpenAI
POST	/v1/music/generations	Generazione musicale in stile OpenAI
POST	/v1/audio/transcriptions	OpenAI Audio (STT)
POST	/v1/audio/speech	OpenAI TTS (restituisce il corpo audio)
POST	/v1/rerank	Reranking in stile Cohere/Voyage
POST	/v1/classify	Classificazione Jina (api.jina.ai)
POST	/v1/segment	Segmentatore Jina (segment.jina.ai)
POST	/v1/moderations	OpenAI Moderations
GET	/v1/models	OpenAI
POST	/v1/messages/count_tokens	Anthropic
GET	/v1beta/models	Gemini
POST	/v1beta/models/{...path}	Gemini generateContent
POST	/v1/api/chat	Ollama
GET	/api/v1/vscode/{token}/	Alias del catalogo OpenAI
GET	/api/v1/vscode/{token}/models	Alias dei modelli OpenAI
POST	/api/v1/vscode/{token}/chat/completions	Alias OpenAI con token
POST	/api/v1/vscode/{token}/responses	Alias OpenAI Responses con token
POST	/api/v1/vscode/{token}/api/chat	Alias Ollama con token
GET	/api/v1/vscode/{token}/api/tags	Alias dei tag Ollama con token

Tutte le route POST seguono la stessa struttura: Bearer your-api-key + corpo JSON convalidato tramite Zod (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema e così via; vedere src/shared/validation/schemas.ts). In caso di errore di convalida dello schema viene restituito un codice 4xx.

Per i client che non possono aggiungere Authorization: Bearer ..., OmniRoute accetta anche le chiavi API nell'URL, tramite la compatibilità con i parametri della stringa di query (?token=..., ?apiKey=..., ?api_key=..., ?key=...) oppure tramite gli endpoint dedicati /api/v1/vscode/{token}/... documentati di seguito.

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

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

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

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

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

# TTS — restituisce un corpo audio/mpeg (o nel formato richiesto)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Modifica di immagini (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# Generazione di video/musica (ID modello con prefisso del provider)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

Route dedicate ai provider

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

Il prefisso del provider viene aggiunto automaticamente se manca. I modelli non corrispondenti restituiscono 400.

---

API dei file

Endpoint compatibile con OpenAI per i file usati come input/output dei batch e per i caricamenti con una finalità specifica.

Metodo	Percorso	Descrizione
POST	/v1/files	Carica un file (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — massimo 512 MiB
GET	/v1/files	Elenca i file per la chiave API autenticata
GET	/v1/files/[id]	Recupera i metadati di un file
DELETE	/v1/files/[id]	Elimina un file
GET	/v1/files/[id]/content	Restituisce in streaming il contenuto non elaborato del file

Autenticazione: chiave API Bearer — l'ambito dei file è definito per ciascuna chiave API tramite getApiKeyRequestScope. Una chiave può visualizzare, scaricare ed eliminare esclusivamente i propri file; una sessione della dashboard priva di chiave può accedere all'intera istanza; l'accesso a un file senza proprietario (caricato in modo anonimo o tramite una sessione della dashboard) è negato a ogni chiamante che non usa una sessione. GET /v1/files rifiuta un chiamante anonimo — e una chiave fornita che non viene riconosciuta — con 401 anche quando REQUIRE_API_KEY=false, invece di elencare i file di tutti i tenant (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

API dei batch

Elaborazione batch compatibile con OpenAI.

Metodo	Percorso	Descrizione
POST	/v1/batches	Crea un batch — corpo convalidato da v1BatchCreateSchema (input_file_id, endpoint, completion_window)
GET	/v1/batches	Elenca i batch
GET	/v1/batches/[id]	Recupera lo stato del batch + request_counts
DELETE	/v1/batches/[id]	Elimina un batch completato/non riuscito
POST	/v1/batches/[id]/cancel	Annulla un batch in corso

Autenticazione: chiave API Bearer. L'ambito dei batch è definito per ciascuna chiave API secondo la stessa regola a tre vie applicata ai file: accesso consentito esclusivamente alla propria chiave, accesso all'intera istanza per la sessione della dashboard, accesso ai record senza proprietario negato a ogni chiamante che non usa una sessione (recupero, eliminazione, annullamento e verifica di input_file_id durante la creazione). GET /v1/batches rifiuta un chiamante anonimo con 401 anche quando REQUIRE_API_KEY=false.

---

API di ricerca

Astrazione dei provider web/di ricerca (Tavily, Brave, Exa, Serper, ecc.).

Metodo	Percorso	Descrizione
GET	/v1/search	Elenca i provider di ricerca configurati e le relative funzionalità
POST	/v1/search	Esegue una query di ricerca — corpo validato da v1SearchSchema, supporta caching/coalescing
GET	/v1/search/analytics	Statistiche per provider su hit/latenza/cache

Autenticazione: chiave API Bearer (extractApiKey + isValidApiKey). I criteri di ricerca vengono applicati tramite enforceApiKeyPolicy.

---

API di recupero web

Estrae contenuti da un URL tramite un provider di recupero web configurato (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

Metodo	Percorso	Descrizione
POST	/v1/web/fetch	Recupera/estrae un URL — corpo validato da v1WebFetchSchema

Autenticazione: chiave API Bearer (extractApiKey + isValidApiKey). I criteri vengono applicati tramite enforceApiKeyPolicy.

Fallback consapevole delle quote (#8297): quando non viene specificato alcun provider, il pool (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) viene percorso in ordine di priorità fisso (fill-first): un provider configurato ma soggetto a limitazione della frequenza viene ignorato anziché interrompere immediatamente la richiesta, mentre un errore upstream ritentabile/di quota (HTTP 429 sempre; 402/403 per i livelli gratuiti con quote di Firecrawl/Tavily/TinyFish — non per Jina Reader e mai per una semplice richiesta non valida 400) fa passare al successivo provider non ancora tentato e dotato di credenziali durante l'elaborazione della richiesta. Quando tutti i provider nel pool sono esauriti, l'endpoint restituisce un singolo 429 (con un'intestazione Retry-After) anziché il precedente 400 generico. Quando viene richiesto un provider esplicito, non avviene alcun fallback silenzioso: un provider esplicito soggetto a limitazione della frequenza o non funzionante espone il proprio errore (429 se soggetto a limitazione della frequenza, altrimenti lo stato upstream).

---

Streaming WebSocket

GET /v1/ws?handshake=1

Convalida un handshake di upgrade WebSocket e restituisce i messaggi di esempio del protocollo su rete (request, cancel). I frame WS effettivi vengono gestiti dal server WS incluso, al di fuori della tabella di routing di Next.js.

Autenticazione: chiave API Bearer durante l'handshake.

Responses API tramite WebSocket (solo codex)

# Stessi host:porta dell'API HTTP (valore predefinito 20128); esegue l'upgrade della connessione:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (oppure: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# Il primo frame DEVE essere response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

Un proxy Responses-API-over-WebSocket è collegato esclusivamente a codex (backend ChatGPT). Rimane in ascolto sulla stessa porta dell'API/dashboard nei percorsi /v1/responses, /responses e /api/v1/responses. Al primo frame response.create, esegue l'autenticazione e la preparazione tramite il bridge interno codex-responses-ws, seleziona una connessione OAuth codex e crea un tunnel verso wss://chatgpt.com/backend-api/codex/responses tramite il trasporto wreq-js. I modelli non codex vengono rifiutati (codex_ws_provider_required). Per il routing con condivisione della quota, utilizzare model: "qtSd/<group>/codex/<model>". Implementato in app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts.

Autenticazione: chiave API Bearer durante l'handshake. Il server HTTP incluso (server-ws.mjs) deve essere l'entrypoint attivo (lo è per impostazione predefinita quando esiste app/server-ws.mjs).

ID del modello: utilizzare l'ID ChatGPT semplice (senza prefisso codex/)

La Codex CLI di OpenAI convalida il nome del modello lato client quando supports_websockets = true e rifiuta gli ID con prefisso del provider come codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Inviare l'ID semplice (ad esempio gpt-5.5). Il bridge di OmniRoute è esclusivamente codex, pertanto risolve nuovamente un ID semplice come modello codex (resolveCodexWsModelInfo) prima di creare il tunnel upstream, anche se un gpt-5.5 semplice verrebbe altrimenti instradato verso un altro provider tramite HTTP.

Configurazione della Codex CLI di OpenAI

Indirizzare la Codex CLI verso OmniRoute aggiungendo un provider personalizzato con supporto WebSocket a ~/.codex/config.toml (utilizzare un CODEX_HOME separato per evitare di modificare una configurazione esistente):

model = "gpt-5.5"                 # ID semplice — NON "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # nessuna barra finale; l'URL WS viene derivato (utilizzare https/wss in produzione)
wire_api = "responses"                    # unico valore supportato da febbraio 2026
supports_websockets = true                # abilita il trasporto Responses-over-WS
env_key = "OMNIROUTE_API_KEY"             # contiene la chiave API di OmniRoute (Bearer)

export OMNIROUTE_API_KEY=sk-...           # una chiave API di OmniRoute (qualsiasi chiave se REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"

La CLI esegue l'upgrade di base_url + /responses a WebSocket e OmniRoute crea un tunnel verso la connessione OAuth codex selezionata. Convalidato end-to-end rispetto al server locale: ChatGPT restituisce codex.rate_limits + response.created e trasmette in streaming il completamento.

---

Quote e segnalazione dei problemi

Metodo	Percorso	Descrizione
GET	/v1/quotas/check	Pre-convalida la quota per un provider + accountId prima di emettere una chiave registrata
POST	/v1/issues/report	Segnala a GitHub un errore relativo alla quota/emissione della chiave (richiede GITHUB_ISSUES_REPO + token)

Autenticazione: chiave API Bearer (isAuthenticated).

---

Utilizzo self-service (/api/usage/om-usage)

Qualsiasi chiave API può leggere il proprio utilizzo e le proprie quote, senza autenticazione di gestione. Questo è l'endpoint usato da un client (CLI, il pannello OmniCopilot) per mostrare al titolare di una chiave la propria spesa.

# Formato testuale (il contratto storico: testo semplice per un terminale)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Formato strutturato: quello utilizzato da un'interfaccia utente
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

La chiave deve avere allowUsageCommand abilitato (disabilitato per impostazione predefinita: il gestore delle chiavi API della dashboard lo attiva o disattiva per ogni chiave). Senza questa opzione, l'endpoint risponde con 403.

?format=json restituisce una struttura discriminata, in modo che il chiamante non legga mai un campo dati da una risposta di rifiuto. In caso di successo:

{
  "allowed": true,
  // presente solo quando la chiave ha attivato limiti di utilizzo per chiave (USD giornalieri/settimanali):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // l'istantanea della quota del provider selezionato oppure null quando non è ancora presente nulla nella cache:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // le istantanee di tutte le connessioni, affinché un'interfaccia utente possa mostrare più provider affiancati:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

In caso di rifiuto (401 chiave non valida / 403 operazione non consentita), la stessa route restituisce { "allowed": false, "error": { "message": "…" } }: un campo personal/provider presente ma vuoto (chiave consentita, ma nessun dato ancora acquisito) rappresenta uno stato diverso da un rifiuto, e solo il formato JSON consente di distinguerli.

Autenticazione: la chiave API Bearer del chiamante, convalidata tramite isValidApiKey: questa non è l'interfaccia di gestione (/api/keys/…), che rimane protetta da requireManagementAuth.

---

Cache semantica

# Ottieni le statistiche della cache
GET /api/cache/stats

# Svuota tutte le cache
DELETE /api/cache/stats

Esempio di risposta:

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

Impatto sulla latenza

Un HIT della cache semantica restituisce la risposta dalla cache senza una chiamata upstream, pertanto il valore X-OmniRoute-Response-Latency riportato è prossimo allo zero (indipendentemente dalla latenza upstream originale). I client sensibili alla latenza (benchmark, monitoraggio p50/p99) devono controllare l'header di risposta X-OmniRoute-Cache-Latency:

Valore	Significato
synthetic	Risposta restituita dalla cache; la latenza non è il tempo upstream effettivo
(assente)	Risposta proveniente da una chiamata upstream effettiva

Esclusione della cache per chiave

Le chiavi API possono escludere le letture dalla cache semantica tramite cacheDefaultMode:

Valore	Comportamento
legacy	Comportamento normale della cache (impostazione predefinita)
bypass	Ignora completamente la ricerca nella cache; usa sempre l'upstream

Impostabile durante la creazione della chiave (POST /api/keys) o l'aggiornamento (PATCH /api/keys/[id]):

{ "cacheDefaultMode": "bypass" }

Esclusione per richiesta

Qualsiasi richiesta può ignorare la cache indipendentemente dalle impostazioni della chiave:

X-OmniRoute-No-Cache: true

---

Dashboard e gestione

Le route di gestione (/api/*, eccetto autenticazione/accesso pubblici) non sono autorizzate dalle normali chiavi API di inferenza. Famiglie di credenziali, ambiti ed esempi con curl: Autenticazione per la gestione.

Autenticazione

Endpoint	Metodo	Descrizione
/api/auth/login	POST	Accesso
/api/auth/logout	POST	Disconnessione
/api/settings/require-login	GET/PUT	Attiva/disattiva l'accesso obbligatorio

Gestione dei provider

Endpoint	Metodo	Descrizione
/api/providers	GET/POST	Elenca / crea provider
/api/providers/[id]	GET/PUT/DELETE	Gestisce un provider
/api/providers/[id]/test	POST	Verifica la connessione al provider
/api/providers/[id]/models	GET	Elenca i modelli del provider
/api/providers/validate	POST	Convalida la configurazione del provider
/api/providers/bulk	POST	Aggiunge in blocco chiavi API per UN SOLO provider
/api/providers/import	POST	Importa un ELENCO eterogeneo di provider da un file CSV/JSON analizzato (#6836); risultati con errori parziali per riga
/api/provider-nodes*	Vari	Gestione dei nodi dei provider
/api/provider-models	GET/POST/PATCH/DELETE	Modelli personalizzati (aggiunta, aggiornamento, occultamento/visualizzazione, eliminazione)

Flussi OAuth

Endpoint	Metodo	Descrizione
/api/oauth/[provider]/[action]	Vari	OAuth specifico del provider

Routing e configurazione

Endpoint	Metodo	Descrizione
/api/models/alias	GET/POST	Alias dei modelli
/api/models/catalog	GET	Tutti i modelli per provider + tipo
/api/combos*	Vari	Gestione delle combinazioni
/api/keys*	Vari	Gestione delle chiavi API
/api/pricing	GET	Prezzi dei modelli

Utilizzo e analisi

Endpoint	Metodo	Descrizione
/api/usage/history	GET	Cronologia di utilizzo
/api/usage/logs	GET	Log di utilizzo
/api/usage/request-logs	GET	Log a livello di richiesta
/api/usage/[connectionId]	GET	Utilizzo per connessione
/api/usage/token-limits	GET/POST/DELETE	Budget dei limiti di token per chiave API
/api/usage/model-latency-stats	GET	Aggregazione mobile della latenza per provider/modello (media/p50/p95/p99, percentuale di successo); filtri: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health	GET	Riepilogo dello stato della cache dei prompt su call_logs — rapporto scritture/letture, distribuzione p50/p90/p99 delle dimensioni di scrittura, concentrazione delle scritture intensive, suddivisione per modello e verdetto healthy/degraded/thrash/no-data; parametri di query range (1h|24h|7d|30d, valore predefinito 24h) e model opzionale (#8827)

Impostazioni

Endpoint	Metodo	Descrizione
/api/settings	GET/PUT/PATCH	Impostazioni generali
/api/settings/proxy	GET/PUT	Configurazione del proxy di rete
/api/settings/proxy/test	POST	Verifica della connessione proxy
/api/settings/ip-filter	GET/PUT	Elenco di indirizzi IP consentiti/bloccati
/api/settings/thinking-budget	GET/PUT	Modalità di riscrittura della richiesta per il budget di pensiero/ragionamento (passthrough / auto-strip / custom / adaptive). Indipendente dalla compressione. Vedere THINKING_BUDGET.md.
/api/settings/system-prompt	GET/PUT	Prompt di sistema globale
/api/settings/compression	GET/PUT	Configurazione globale della compressione
/api/settings/purge-request-history	POST	Cancella le righe del log delle richieste e gli artefatti locali del log delle chiamate

Contesto e compressione

Endpoint	Metodo	Descrizione
/api/compression/preview	POST	Anteprima della compressione off/lite/standard/aggressive/ultra/RTK/stacked
/api/compression/language-packs	GET	Elenca i pacchetti linguistici Caveman disponibili
/api/compression/rules	GET	Elenca i metadati delle regole Caveman
/api/context/caveman/config	GET/PUT	Alias delle impostazioni specifiche di Caveman
/api/context/rtk/config	GET/PUT	Impostazioni specifiche di RTK, inclusi filtri personalizzati e conservazione dell'output non elaborato
/api/context/rtk/filters	GET	Catalogo dei filtri RTK e diagnostica dei filtri personalizzati
/api/context/rtk/test	POST	Esegue un'anteprima/un test RTK su un payload di testo
/api/context/rtk/raw-output/[id]	GET	Legge l'output non elaborato oscurato conservato tramite ID puntatore
/api/context/combos	GET/POST	Elenca/crea combinazioni di compressione
/api/context/combos/[id]	GET/PUT/DELETE	Dettagli/aggiornamento/eliminazione della combinazione di compressione
/api/context/combos/[id]/assignments	GET/PUT	Assegna combinazioni di compressione alle combinazioni di instradamento
/api/context/analytics	GET	Alias per l'analisi della compressione

Monitoraggio

Endpoint	Metodo	Descrizione
/api/sessions	GET	Monitoraggio delle sessioni attive
/api/rate-limits	GET	Limiti di frequenza per account
/api/monitoring/health	GET	Controllo dello stato + riepilogo dei provider (catalogCount, configuredCount, activeCount, monitoredCount). La vista di gestione include credentialHealth: valori scalari della cache dei probe, failedConnections quando failed>0 e staleDbNonOkCount (test_status persistente di SQLite, non l'indicatore). Vedere MONITORING_GUIDE.md.
/api/cache/stats	GET/DELETE	Statistiche della cache / svuotamento
/api/modality-bridge/stats	GET	attempts in memoria, successi/bridged, errori, riscontri nella cache, totalLatencyMs, latencySamples, averageLatencyMs calcolata sul numero di campioni e ora dell'ultimo utilizzo (azzerati al riavvio; autenticazione di gestione)
/api/modality-bridge/video/runtime	GET	Controllo rigoroso del loopback attendibile prima dell'autenticazione/sondaggio di gestione; disponibilità e versioni sanificate di FFmpeg/ffprobe (no-store)
/api/modality-bridge/video/extract	POST	Broker interno autenticato di byte tramite loopback attendibile; input di 50 MiB, coda limitata/output di 32 MiB, 503 per capacità esaurita, 499 per disconnessione, 504 per scadenza; non è un'API pubblica per il caricamento di file

Backup ed esportazione/importazione

Endpoint	Metodo	Descrizione
/api/db-backups	GET	Elenca i backup disponibili
/api/db-backups	PUT	Crea un backup manuale
/api/db-backups	POST	Ripristina da un backup specifico
/api/db-backups/export	GET	Scarica il database come file .sqlite
/api/db-backups/import	POST	Carica un file .sqlite per sostituire il database
/api/db-backups/exportAll	GET	Scarica il backup completo come archivio .tar.gz

Sincronizzazione cloud

Endpoint	Metodo	Descrizione
/api/sync/cloud	Vari	Operazioni di sincronizzazione cloud
/api/sync/initialize	POST	Inizializza la sincronizzazione
/api/cloud/*	Vari	Gestione del cloud

Tunnel

Endpoint	Metodo	Descrizione
/api/tunnels/cloudflared	GET	Legge lo stato di installazione/esecuzione di Cloudflare Quick Tunnel per la dashboard
/api/tunnels/cloudflared	POST	Abilita o disabilita Cloudflare Quick Tunnel (action=enable/disable)
/api/tunnels/ngrok	GET	Legge lo stato di esecuzione di ngrok Tunnel per la dashboard
/api/tunnels/ngrok	POST	Abilita o disabilita ngrok Tunnel (action=enable/disable)

Strumenti CLI

Endpoint	Metodo	Descrizione
/api/cli-tools/claude-settings	GET	Stato della CLI Claude
/api/cli-tools/codex-settings	GET	Stato della CLI Codex
/api/cli-tools/droid-settings	GET	Stato della CLI Droid
/api/cli-tools/openclaw-settings	GET	Stato della CLI OpenClaw
/api/cli-tools/runtime/[toolId]	GET	Runtime CLI generico

Le risposte della CLI includono: installed, runnable, command, commandPath, runtimeMode, reason.

Agenti ACP

Endpoint	Metodo	Descrizione
/api/acp/agents	GET	Elenca tutti gli agenti rilevati (integrati + personalizzati) con il relativo stato
/api/acp/agents	POST	Aggiunge un agente personalizzato o aggiorna la cache di rilevamento
/api/acp/agents	DELETE	Rimuove un agente personalizzato tramite il parametro di query id

La risposta GET include agents[] (id, name, binary, version, installed, protocol, isCustom) e summary (total, installed, notFound, builtIn, custom).

Resilienza e limiti di frequenza

Endpoint	Metodo	Descrizione
/api/resilience	GET/PATCH	Ottiene/aggiorna la coda delle richieste, il cooldown della connessione, il breaker del provider e le impostazioni di attesa
/api/resilience/reset	POST	Reimposta i circuit breaker dei provider
/api/resilience/model-cooldowns	GET	Elenca i blocchi attivi per (provider, connessione, modello), ordinati per tempo rimanente
/api/resilience/model-cooldowns	DELETE	Rimuove un blocco del modello — corpo {provider, model} oppure {all: true} per cancellare tutto
/api/rate-limits	GET	Stato del limite di frequenza per account
/api/rate-limit	GET	Configurazione globale del limite di frequenza

Tutte e quattro le route /api/resilience/* richiedono l'autenticazione di gestione (requireManagementAuth). Consulta Resilienza (estesa) per un'analisi completa delle differenze tra breaker del provider, cooldown della connessione e blocco del modello.

Valutazioni

Endpoint	Metodo	Descrizione
/api/evals	GET/POST	Elenca le suite di valutazione / esegue la valutazione

Criteri

Endpoint	Metodo	Descrizione
/api/policies	GET/POST/DELETE	Gestisce i criteri di instradamento

Conformità

Endpoint	Metodo	Descrizione
/api/compliance/audit-log	GET	Registro di audit della conformità (ultimi N)

v1beta (compatibile con Gemini)

Endpoint	Metodo	Descrizione
/v1beta/models	GET	Elenca i modelli nel formato Gemini
/v1beta/models/{...path}	POST	Endpoint Gemini generateContent

Questi endpoint rispecchiano il formato API di Gemini per i client che richiedono la compatibilità nativa con l'SDK Gemini.

API interne / di sistema

Endpoint	Metodo	Descrizione
/api/init	GET	Verifica dell'inizializzazione dell'applicazione (usata al primo avvio)
/api/tags	GET	Tag dei modelli compatibili con Ollama (per i client Ollama)
/api/restart	POST	Avvia il riavvio controllato del server
/api/shutdown	POST	Avvia l'arresto controllato del server
/api/system/env/repair	POST	Ripara le variabili d'ambiente del provider OAuth

Nota: Questi endpoint vengono utilizzati internamente dal sistema o per la compatibilità con i client Ollama. In genere non vengono chiamati dagli utenti finali.

Riparazione dell'ambiente OAuth (v3.6.1+)

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

{
  "provider": "claude-code"
}

Ripara le variabili d'ambiente OAuth mancanti o danneggiate per un provider specifico. Restituisce:

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

---

Trascrizione audio

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

Trascrive i file audio utilizzando qualsiasi provider STT configurato. Il primo segmento del percorso seleziona il provider nativo (openai/…, deepgram/…). I gateway che riesportano il modello di un altro fornitore utilizzano un ID qualificato (openrouter/deepgram/nova-3).

Richiesta:

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

Risposta:

{
  "text": "Ciao, questo è il contenuto audio trascritto.",
  "task": "transcribe",
  "language": "it",
  "duration": 12.5
}

Esempi di ID modello: openai/whisper-1 (richiede una chiave OpenAI), openrouter/deepgram/nova-3 (richiede una chiave OpenRouter), deepgram/nova-3 (richiede una chiave Deepgram nativa). Una richiesta deepgram/nova-3 senza qualificatore non utilizza OpenRouter.

Formati supportati: mp3, wav, m4a, flac, ogg, webm.

---

Compatibilità con Ollama

Per i client che utilizzano il formato API di Ollama:

# Endpoint di chat (formato Ollama)
POST /v1/api/chat

# Elenco dei modelli (formato Ollama)
GET /api/tags

Le richieste vengono tradotte automaticamente tra il formato Ollama e i formati interni.

Alias tokenizzati per VS Code / senza header

Utilizza questi alias quando un'integrazione non può inserire un header Authorization e necessita che la chiave API sia incorporata nell'URL di base.

# Alias del catalogo in stile OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# Alias della chat in stile OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Alias in stile Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

Esempio:

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

Note:

• Gli alias tokenizzati riutilizzano gli stessi gestori di /v1/* e /api/tags; la struttura delle risposte rimane identica.
• Preferisci Authorization: Bearer ... ogni volta che il client supporta header personalizzati.
• I token basati su URL possono comparire nei log dei reverse proxy, nella cronologia del browser e nella telemetria esterna a OmniRoute. Considerali un'opzione di compatibilità, non la modalità di autenticazione predefinita.

---

Telemetria

# Ottiene il riepilogo della telemetria della latenza (p50/p95/p99 per provider)
GET /api/telemetry/summary

Risposta:

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

---

Budget

# Ottiene lo stato del budget per tutte le chiavi API
GET /api/usage/budget

# Imposta o aggiorna un budget
POST /api/usage/budget
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "dailyLimitUsd": 5.00,
  "weeklyLimitUsd": 30.00,
  "monthlyLimitUsd": 100.00,
  "warningThreshold": 0.8,
  "resetInterval": "monthly"
}

Note sullo schema (setBudgetSchema): apiKeyId è obbligatorio; almeno uno tra dailyLimitUsd, weeklyLimitUsd o monthlyLimitUsd deve essere maggiore di zero. Campi facoltativi: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). Il formato legacy {keyId, limit, period} restituisce 400 Bad Request.

Limiti di token

Budget di token per chiave API (distinti dal budget basato su USD descritto sopra). Vengono applicati direttamente durante l'elaborazione della richiesta: quando l'utilizzo della finestra corrente di una chiave raggiunge il relativo limite, le richieste vengono rifiutate con 429 Too Many Requests. I limiti possono essere circoscritti a uno specifico model, a un provider oppure applicati globalmente all'intera chiave; quando più limiti corrispondono a una richiesta, viene applicato quello più restrittivo.

# Elenca i limiti di token di una chiave (include l'utilizzo corrente della finestra)
GET /api/usage/token-limits?apiKeyId=key-123

# Crea o aggiorna un limite di token
POST /api/usage/token-limits
Content-Type: application/json

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

# Elimina un limite di token tramite id
DELETE /api/usage/token-limits?id=tl-abc

Note sullo schema (setTokenLimitSchema): apiKeyId e scopeType (model | provider | global) sono obbligatori. scopeValue è obbligatorio, a meno che scopeType non sia global (ad esempio, un id modello per l'ambito model, un id provider per l'ambito provider). tokenLimit deve essere un numero intero positivo (convertito da stringa). Facoltativi: id (ometterlo per creare, specificarlo per aggiornare), resetInterval (daily | weekly | monthly, valore predefinito monthly), resetTime (HH:MM), enabled (valore predefinito true). Le risposte GET arricchiscono ogni limite con tokensUsed, remaining, windowStart, periodStartAt e nextResetAt. Si tratta di un endpoint di gestione (l'autenticazione viene applicata centralmente dalla pipeline di autorizzazione).

Elaborazione delle richieste

1. Il client invia una richiesta a /v1/*
2. Il gestore della route chiama handleChat, handleEmbedding, handleAudioTranscription o handleImageGeneration
3. Il modello viene risolto (provider/modello diretto oppure alias/combo)
4. Le credenziali vengono selezionate dal DB locale filtrando in base alla disponibilità dell'account
5. Per la chat: handleChatCore verifica la cache semantica/delle firme e risolve le impostazioni di compressione della combo
6. Quando abilitata, la compressione proattiva viene eseguita prima della traduzione per il provider (lite, Caveman, RTK o in modalità combinata)
7. L'esecutore del provider invia la richiesta upstream
8. La risposta viene riconvertita nel formato del client (chat) oppure restituita così com'è (embedding/immagini/audio)
9. Vengono registrati l'utilizzo, i dati analitici sulla compressione e i log delle richieste
10. In caso di errore, viene applicato il fallback in base alle regole della combo

Riferimento completo dell'architettura: ARCHITECTURE.md

---

Gestione delle combo

Le combo di routing di livello superiore (già riepilogate in /api/combos*) possono anche essere mappate 1:1 a partire dal pattern di un id modello, consentendo il reindirizzamento trasparente di un id modello in stile OpenAI verso una combo.

Metodo	Percorso	Descrizione
GET	/api/model-combo-mappings	Elenca tutte le mappature modello→combo
POST	/api/model-combo-mappings	Crea una mappatura — corpo: {pattern, comboId, priority?, enabled?, description?}
GET	/api/model-combo-mappings/[id]	Recupera una singola mappatura
PUT	/api/model-combo-mappings/[id]	Aggiorna i campi di una mappatura esistente
DELETE	/api/model-combo-mappings/[id]	Rimuove una mappatura

Autenticazione: sessione di gestione/chiave API (requireManagementAuth).

---

Webhook

Sottoscrizioni webhook in uscita per gli eventi di OmniRoute (completamento delle richieste, esaurimento della quota, rotazione delle chiavi, ecc.).

Metodo	Percorso	Descrizione
GET	/api/webhooks	Elenca i webhook (i segreti sono mascherati come <prefix>...)
POST	/api/webhooks	Crea un webhook — corpo: {url, events?: ["*"], secret?, description?}
GET	/api/webhooks/[id]	Recupera un webhook
PUT	/api/webhooks/[id]	Aggiorna url/events/secret/description
DELETE	/api/webhooks/[id]	Rimuove un webhook
POST	/api/webhooks/[id]/test	Invia un payload di test all'URL del webhook e restituisce lo stato della consegna

Autenticazione: sessione di gestione/chiave API (requireManagementAuth).

---

Chiavi registrate (gestione automatica)

Utilizzate dal sottosistema di gestione automatica delle chiavi per emettere e ruotare chiavi API tramite un provider/account sottostante, con quote giornaliere/orarie.

Metodo	Percorso	Descrizione
GET	/api/v1/registered-keys	Elenca le chiavi registrate (solo il prefisso mascherato)
POST	/api/v1/registered-keys	Emette una nuova chiave registrata — corpo: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. Restituisce la chiave non mascherata una sola volta. Restituisce 429 se la quota non lo consente.
GET	/api/v1/registered-keys/[id]	Recupera i metadati di una chiave registrata (senza il materiale della chiave)
DELETE	/api/v1/registered-keys/[id]	Revoca una chiave registrata
POST	/api/v1/registered-keys/[id]/revoke	Endpoint di revoca esplicita (stesso effetto di DELETE)

Autenticazione: chiave API Bearer (isAuthenticated). Vedere anche /v1/quotas/check e /v1/issues/report.

---

Protocollo degli agenti

Attività degli agenti cloud (Claude Code, Codex Cloud, OpenHands, ecc.) eseguite da remoto per conto degli utenti di OmniRoute.

Metodo	Percorso	Descrizione
GET	/api/v1/agents/tasks	Elenca le attività — parametri facoltativi ?provider=, ?status=, ?limit= (1–500, valore predefinito 50)
POST	/api/v1/agents/tasks	Crea un'attività — corpo convalidato da CreateCloudAgentTaskSchema (providerId, prompt, source, options?). Restituisce 201 con l'envelope dell'attività
DELETE	/api/v1/agents/tasks?id=...	Elimina un'attività
GET	/api/v1/agents/tasks/[id]	Legge un'attività — aggiorna in modo sincrono lo stato dall'agente cloud upstream quando è impostato un external_id
POST	/api/v1/agents/tasks/[id]	Azione discriminata: {action: "approve"}, {action: "message", message} oppure {action: "cancel"}
DELETE	/api/v1/agents/tasks/[id]	Elimina un'attività specifica tramite id

Autenticazione: l'autenticazione di gestione è obbligatoria per ogni metodo (requireCloudAgentManagementAuth). Prima della versione v3.8.0 questi endpoint non richiedevano autenticazione — vedere il commit 588a0333 per la modifica incompatibile.

# Crea un'attività cloud di 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 di gestione

Proxy HTTP(S)/SOCKS in uscita che possono essere assegnati a provider, account o a livello globale.

Metodo	Percorso	Descrizione
GET	/api/v1/management/proxies	Elenca i proxy (con ?id= ne restituisce uno; con ?id=&where_used=1 restituisce il grafo delle assegnazioni)
POST	/api/v1/management/proxies	Crea un proxy — corpo convalidato da createProxyRegistrySchema
PATCH	/api/v1/management/proxies	Aggiorna un proxy — corpo convalidato da updateProxyRegistrySchema (richiede id)
DELETE	/api/v1/management/proxies?id=...&force=1	Elimina un proxy (usare force=1 per rimuovere le assegnazioni)
GET	/api/v1/management/proxies/assignments	Elenca le assegnazioni — filtrabili per proxy_id, scope, scope_id; passare resolve_connection_id=<id> per determinare il proxy attivo per una connessione
PUT	/api/v1/management/proxies/assignments	Assegna — corpo convalidato da proxyAssignmentSchema ({scope, scopeId?, proxyId?}). Svuota la cache del dispatcher
PUT	/api/v1/management/proxies/bulk-assign	Assegna in blocco — corpo convalidato da bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?})
GET	/api/v1/management/proxies/health?hours=24	Restituisce lo stato aggregato dei proxy (conteggi di successi/errori, latenza) per un intervallo temporale

Autenticazione: sessione di gestione/chiave API obbligatoria per ogni route (requireManagementAuth).

Le route POST /api/v1/management/proxies/[id]/assignments e POST /api/v1/management/proxies/[id]/health indicate nella descrizione dell'attività sono gestite dalle route piatte /assignments e /health mostrate sopra — nel codebase non esistono sottoroute per singolo id.

---

Resilienza (estesa)

OmniRoute espone tre meccanismi indipendenti per gli errori temporanei; gli endpoint di gestione riportati di seguito consentono agli operatori di consultarli e modificarli:

Ambito	Archiviazione dello stato	Consultazione	Reimpostazione / cancellazione
Circuit breaker provider	domain_circuit_breakers + in memoria	/api/monitoring/health	POST /api/resilience/reset
Cooldown connessione	rateLimitedUntil nelle connessioni dei provider	/api/rate-limits, /api/providers/[id]	(si riabilita in modo lazy; cancellabile tramite PUT del provider)
Blocco modello	Registro in memoria della disponibilità dei modelli	GET /api/resilience/model-cooldowns	DELETE /api/resilience/model-cooldowns

PATCH /api/resilience accetta sostituzioni dei circuit breaker dei provider in providerBreaker.oauth e providerBreaker.apikey. Ogni profilo supporta degradationThreshold, failureThreshold e resetTimeoutMs; gli stessi campi sono disponibili in Dashboard → Impostazioni → Resilienza.

# Cancella il blocco di un singolo modello
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"}'

# Cancella tutti i blocchi
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

Per il riferimento concettuale completo e i valori predefiniti dei circuit breaker, consulta CLAUDE.md → "Stato di runtime della resilienza".

---

Skill

Framework di skill per estendere OmniRoute con gestori eseguibili personalizzati, oltre alle integrazioni con i marketplace.

Metodo	Percorso	Descrizione
GET	/api/skills	Elenca le skill installate — filtrabili tramite ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local, con paginazione
GET	/api/skills/[id]	Recupera una skill
PUT	/api/skills/[id]	Aggiorna una skill (nome, descrizione, modalità, schema, gestore, tag)
DELETE	/api/skills/[id]	Disinstalla una skill
POST	/api/skills/install	Installa una skill da un manifest non elaborato — corpo: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET	/api/skills/executions	Elenca le esecuzioni recenti delle skill (registro di controllo con input/output/durata)
GET	/api/skills/marketplace?q=...	Cerca o elenca le skill più popolari nel marketplace SkillsMP (richiede l'impostazione skillsmpApiKey)
POST	/api/skills/marketplace/install	Installa una skill tramite id da SkillsMP
GET	/api/skills/skillssh?q=&limit=	Cerca nel registro skills.sh
POST	/api/skills/skillssh/install	Installa una skill tramite id da skills.sh

Autenticazione: sessione di gestione/chiave API. Le route di ricerca nei marketplace accettano l'autenticazione di gestione oppure una chiave API Bearer (isAuthenticated).

---

Memoria

Archivio persistente di memoria conversazionale/fattuale, con ambito definito per chiave API/sessione.

Metodo	Percorso	Descrizione
GET	/api/memory	Elenca i ricordi — ?apiKeyId=, ?type=, ?sessionId=, ?q=, con paginazione offset/limit o page/limit
POST	/api/memory	Crea un ricordo — corpo validato da Zod: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}
GET	/api/memory/[id]	Recupera un singolo ricordo
DELETE	/api/memory/[id]	Elimina un ricordo
GET	/api/memory/health	Stato del sottosistema di memoria (connettività al DB, backend degli embedding, stato dell'indice vettoriale)

Autenticazione: sessione di gestione/chiave API (requireManagementAuth). Enumerazione type: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (vedere MemoryType in src/lib/memory/types.ts).

---

Server MCP

OmniRoute include un server Model Context Protocol integrato con 3 trasporti (stdio, SSE, streamable-http) e strumenti con ambito definito. Gli endpoint della dashboard riportati di seguito leggono i dati relativi allo stato e all'audit e fungono da proxy per i trasporti HTTP.

Metodo	Percorso	Descrizione
GET	/api/mcp/status	Heartbeat, trasporto, stato online, ultima chiamata, strumenti principali, tasso di successo nelle ultime 24 ore
GET	/api/mcp/tools	Elenco degli strumenti MCP con name, description, scopes, phase, auditLevel, sourceEndpoints
GET	/api/mcp/sse	Apre uno stream SSE per il trasporto SSE (restituisce 503 se MCP è disabilitato o il trasporto non corrisponde)
POST	/api/mcp/sse	Invia un frame JSON-RPC sul trasporto SSE
GET	/api/mcp/stream	Apre il lato SSE del trasporto HTTP Streamable (messaggi avviati dal server)
POST	/api/mcp/stream	Invia un frame JSON-RPC sul trasporto HTTP Streamable
DELETE	/api/mcp/stream	Termina una sessione HTTP Streamable
GET	/api/mcp/audit	Interroga il registro di audit — ?limit=, ?offset=, ?tool=, `?success=true	false, ?apiKeyId=`
GET	/api/mcp/audit/stats	Statistiche aggregate di audit (totali, tasso di successo, durata media, strumenti principali)

Autenticazione: i trasporti sse/stream rispettano il meccanismo di autenticazione specifico di MCP (chiave API Bearer con ambito mcp); le route status/tools/audit* sono accessibili dalla dashboard (non è richiesta alcuna autenticazione aggiuntiva oltre alla possibilità di raggiungere l'host della dashboard).

Entrambi i trasporti HTTP sono controllati da settings.mcpEnabled e settings.mcpTransport — una mancata corrispondenza del trasporto restituisce 400, mentre uno stato MCP disabilitato restituisce 503.

---

Server A2A

OmniRoute espone un endpoint A2A (Agent-to-Agent) JSON-RPC 2.0, oltre a un wrapper REST per l'ispezione e l'utilizzo nella dashboard.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # facoltativo, a meno che OMNIROUTE_API_KEY non sia impostata
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "skill": "smart-routing",
    "messages": [{"role": "user", "content": "Route this coding task"}]
  }
}

Metodi supportati (tutti subordinati a settings.a2aEnabled):

Metodo	Descrizione
message/send	Esecuzione sincrona della skill; restituisce {task, artifacts, metadata}
message/stream	Esecuzione SSE in streaming dello stesso insieme di skill
tasks/get	Recupera un'attività tramite taskId
tasks/cancel	Annulla un'attività tramite taskId

Skill integrate: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.

Scheda agente

GET /.well-known/agent.json

Restituisce la scheda pubblica dell'agente A2A (nome, descrizione, funzionalità, catalogo delle skill, schema di autenticazione), memorizzata pubblicamente nella cache per 1 ora. Non è richiesta alcuna autenticazione.

Helper REST

Metodo	Percorso	Descrizione
GET	/api/a2a/status	Stato di abilitazione A2A + statistiche delle attività + riepilogo della scheda agente memorizzata nella cache
GET	/api/a2a/tasks	Elenca le attività — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset=
POST	/api/a2a/tasks	(Non implementato come helper REST: creare tramite JSON-RPC message/send)
GET	/api/a2a/tasks/[id]	Recupera una singola attività
POST	/api/a2a/tasks/[id]/cancel	Annulla un'attività

Autenticazione: gli helper REST vengono eseguiti senza autenticazione di gestione (sono leggibili dalla dashboard); la route JSON-RPC /a2a utilizza il token Bearer OMNIROUTE_API_KEY, se configurato.

---

Cloud, valutazioni e analisi

Metodo	Percorso	Descrizione
POST	/api/cloud/auth	Verifica una chiave Bearer e restituisce le connessioni ai provider mascherate + gli alias dei modelli per i client di sincronizzazione cloud
POST	/api/cloud/credentials/update	Aggiorna le credenziali crittografate di un provider sincronizzato con il cloud
POST	/api/cloud/model/resolve	Risolve l'ID logico di un modello in un provider/modello concreto utilizzando la tabella di routing locale
GET	/api/cloud/models/alias	Elenca gli alias dei modelli esposti alla sincronizzazione cloud
GET	/api/assess	Legge le categorizzazioni dell'analisi più recente (per provider/modello)
POST	/api/assess	Esegue un'analisi — corpo: `{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	/api/evals	Elenca le suite di valutazione integrate + le esecuzioni più recenti
POST	/api/evals	Avvia un'esecuzione di valutazione
POST	/api/evals/suites	Crea una suite di valutazione personalizzata — corpo convalidato da evalSuiteSaveSchema
GET	/api/evals/suites/[id]	Recupera una suite di valutazione personalizzata

Autenticazione: /api/cloud/auth convalida direttamente una chiave Bearer; le altre route /api/cloud/*, /api/evals/* e /api/assess richiedono una sessione di gestione/chiave API. La richiesta POST a /api/assess utilizza validateBody con uno schema di ambito basato su un'unione discriminata.

---

Gestione ACP (Agent Client Protocol)

come processi figlio. Questi endpoint gestiscono il rilevamento degli agenti ACP e la registrazione degli agenti personalizzati.

Metodo	Percorso	Descrizione
GET	/api/acp/agents	Elenca tutti gli agenti CLI noti (integrati + personalizzati) con stato di installazione, versione e binario
POST	/api/acp/agents	Registra un agente ACP personalizzato o aggiorna la cache — corpo: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} oppure {action: "refresh"}
DELETE	/api/acp/agents	Rimuove un agente ACP personalizzato — parametro di query: ?id=<agentId>

Esempio di risposta (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
}

Autenticazione: richiede una sessione di gestione (cookie auth_token della dashboard) oppure una chiave API con ambito di gestione.

Per tutti i dettagli, consulta Framework ACP.

---

Analisi e osservabilità

Endpoint di analisi in tempo reale per monitorare l'instradamento, la compressione e la diversità dei provider. Questi endpoint alimentano le pagine /dashboard/analytics/*.

Analisi dell'instradamento automatico

Metodo	Percorso	Descrizione
GET	/api/analytics/auto-routing	Statistiche aggregate sull'instradamento automatico: chiamate totali, distribuzione delle strategie, distribuzione dei livelli, provider principali
GET	/api/analytics/auto-routing?days=7	Statistiche relative a un intervallo temporale (valore predefinito: 24 ore)

Esempio di risposta:

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

Analisi della compressione

Metodo	Percorso	Descrizione
GET	/api/analytics/compression	Statistiche aggregate sulla compressione: token risparmiati, % di risparmio, distribuzione delle modalità, utilizzo dei motori

Esempio di risposta:

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

Monitoraggio della diversità dei provider

Metodo	Percorso	Descrizione
GET	/api/analytics/diversity	Monitoraggio della diversità basato sull'entropia di Shannon: evita singoli punti di errore misurando la distribuzione dei provider

Esempio di risposta:

{
  "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 rappresenta il 40% del traffico — valuta la possibilità di diversificare"]
}

Autenticazione: richiede una sessione di gestione oppure una chiave API con ambito di gestione.

---

Operazioni di amministrazione

Endpoint riservati agli amministratori per la gestione operativa.

Metodo	Percorso	Descrizione
GET	/api/admin/concurrency	Legge i limiti di concorrenza correnti (globali + per provider)
POST	/api/admin/concurrency	Aggiorna i limiti di concorrenza — corpo: {global?: number, perProvider?: Record<string, number>}

Autenticazione: Richiede una sessione di gestione con ambito amministratore.

---

Gestione degli strumenti CLI

Gestisce gli strumenti CLI che si integrano con OmniRoute (antigravity, chipotle, commandCode, devin-cli, ecc.). Consulta il Riferimento dei provider per l'elenco completo.

Metodo	Percorso	Descrizione
GET	/api/cli-tools/all-statuses	Stato di tutti gli strumenti CLI (installazione, versione, ultimo rilevamento)
GET	/api/cli-tools/status	Dettagli sullo stato di uno strumento CLI (query ?tool=)
POST	/api/cli-tools/apply	Scrive la configurazione generata di uno strumento (dryRun mostra un'anteprima; 422 + containerEphemeralTarget in ambiente containerizzato; migration segnala un YAML Codex legacy)
GET	/api/cli-tools/backups	Elenca i backup delle configurazioni degli strumenti CLI
POST	/api/cli-tools/backups	Crea un backup delle configurazioni di tutti gli strumenti CLI
POST	/api/cli-tools/backups	Ripristina: lo stesso endpoint, con {tool, backupId} nel corpo, ripristina il backup specificato
GET	/api/cli-tools/antigravity-mitm	Stato del proxy MITM Antigravity (lo strumento CLI "antigravity-mitm")
POST	/api/cli-tools/antigravity-mitm/alias	Configura gli alias di antigravity-mitm

Autenticazione: Richiede una sessione di gestione.

---

Competenze degli agenti

Gestisce le competenze degli agenti IA (simili ai GPT personalizzati di OpenAI, ma destinate agli agenti).

Metodo	Percorso	Descrizione
GET	/api/agent-skills	Elenca tutte le competenze degli agenti (integrate + personalizzate)
GET	/api/agent-skills/[id]	Recupera una competenza specifica di un agente
POST	/api/agent-skills	Crea una competenza personalizzata per un agente — corpo: {name, description, prompt, model?, temperature?}
PUT	/api/agent-skills/[id]	Aggiorna una competenza personalizzata di un agente
DELETE	/api/agent-skills/[id]	Elimina una competenza personalizzata di un agente
GET	/api/agent-skills/[id]/raw	Recupera il prompt non elaborato + i metadati (senza esecuzione)
POST	/api/agent-skills/generate	Genera tramite IA una nuova competenza a partire da una descrizione in linguaggio naturale

Autenticazione: Richiede una sessione di gestione o una chiave API con ambito di gestione.

---

Gestione della cache

Gestisci la cache semantica e la cache di ragionamento.

Metodo	Percorso	Descrizione
GET	/api/cache	Panoramica della cache: numero totale di voci, percentuale di riscontri, dimensioni su disco
GET	/api/cache/entries	Elenca le voci memorizzate nella cache (con paginazione)
DELETE	/api/cache/entries	Elimina le voci dalla cache (filtrando in base ai parametri della query)
GET	/api/cache/stats	Statistiche dettagliate della cache (per provider, per modello)
GET	/api/cache/reasoning	Stato della cache di ragionamento (per la riproduzione del ragionamento)
DELETE	/api/cache/reasoning	Svuota la cache di ragionamento — parametri della query: ?toolCallId=<id> (singola) oppure ?provider=<p> o nessuno (tutte)

Autenticazione: richiede una sessione di gestione.

---

Sistema di memoria

Gestisci la memoria persistente (FTS5 + incorporamenti vettoriali).

Metodo	Percorso	Descrizione
GET	/api/memory	Elenca le voci di memoria (filtrando per ambito, tipo e query di ricerca)
POST	/api/memory	Crea una nuova voce di memoria — corpo: {scope, type, content, metadata?}
GET	/api/memory/[id]	Ottiene una voce di memoria specifica
PUT	/api/memory/[id]	Aggiorna una voce di memoria
DELETE	/api/memory/[id]	Elimina una voce di memoria
GET	/api/memory?q=	Cerca nella memoria (FTS5 + vettori) — le statistiche sono incluse nella stessa risposta

Autenticazione: richiede una sessione di gestione o una chiave API con ambito di gestione.

---

Webhook

Gestisci le sottoscrizioni webhook per gli eventi.

Metodo	Percorso	Descrizione
GET	/api/webhooks	Elenca tutte le sottoscrizioni webhook
POST	/api/webhooks	Crea una sottoscrizione webhook — corpo: {url, events[], secret?, active?}
GET	/api/webhooks/[id]	Ottiene una sottoscrizione webhook specifica
PUT	/api/webhooks/[id]	Aggiorna una sottoscrizione webhook
DELETE	/api/webhooks/[id]	Elimina una sottoscrizione webhook
GET	/api/webhooks/[id]/deliveries	Elenca la cronologia delle consegne per un webhook (registro dei successi/fallimenti)
POST	/api/webhooks/[id]/test	Invia un evento di prova a un webhook

Autenticazione: richiede una sessione di gestione.

Consulta Framework dei webhook per l'elenco completo dei tipi di evento.

---

Framework delle skill

Gestisci le skill (il framework delle estensioni agentiche).

Metodo	Percorso	Descrizione
GET	/api/skills	Elenca tutte le skill installate (integrate + personalizzate)
POST	/api/skills/install	Installa una skill da un percorso locale o da un URL
DELETE	/api/skills/[id]	Disinstalla una skill
PUT	/api/skills/[id]	Abilita o disabilita una skill — corpo: {enabled?: boolean, mode?: "on" | "off" | "auto"}
POST	/api/skills/executions	Esegue una skill — corpo: {skillName, apiKeyId, input?, sessionId?}
GET	/api/skills/executions	Elenca la cronologia delle esecuzioni per tutte le skill (filtrabile tramite ?apiKeyId=)

Autenticazione: richiede una sessione di gestione o una chiave API con ambito di gestione.

Consulta Framework delle skill per tutti i dettagli.

---

Plugin

Gestisci i plugin di OmniRoute (estensioni di terze parti).

Metodo	Percorso	Descrizione
GET	/api/plugins	Elenca i plugin installati
POST	/api/plugins/marketplace/install	Installa un plugin dal marketplace
DELETE	/api/plugins/[name]	Disinstalla un plugin
POST	/api/plugins/[name]/activate	Attiva un plugin
POST	/api/plugins/[name]/deactivate	Disattiva un plugin
GET	/api/plugins/[name]/config	Recupera la configurazione del plugin
PUT	/api/plugins/[name]/config	Aggiorna la configurazione del plugin

Autenticazione: richiede una sessione di gestione.

Consulta Framework dei plugin per tutti i dettagli.

---

Routing shadow

Il confronto shadow / A-B dei provider non è un'interfaccia REST autonoma — viene configurato tramite il routing combinato (consulta Combinazione automatica). Le metriche di confronto per ciascuna combinazione sono fornite da GET /api/combos/metrics.

---

Guardrail

Esamina i guardrail di runtime (rilevamento delle PII, rilevamento dell'iniezione di prompt, bridging della visione). I guardrail vengono eseguiti per ogni richiesta; è possibile disabilitarli per singola chiamata tramite l'header di richiesta x-omniroute-disabled-guardrails — non esiste un'interfaccia persistente per abilitarli o disabilitarli.

Metodo	Percorso	Descrizione
GET	/api/guardrails	Elenca i guardrail registrati e il relativo stato (nome / abilitazione / priorità)
POST	/api/guardrails/test	Esegue una prova della pipeline preliminare alla chiamata su un input di esempio — corpo: {input, disabledGuardrails?}

Autenticazione: richiede una sessione di gestione.

Consulta Sicurezza > Guardrail per tutti i dettagli.

---

---

Autenticazione

Consulta Autenticazione per la gestione per informazioni sulle quattro famiglie di credenziali (sessione della dashboard, token CLI locale, Access Token oma_live_…, chiave API con ambito di gestione) e sulle relative differenze rispetto alle chiavi di inferenza.

• Le route della dashboard (/dashboard/*) utilizzano il cookie auth_token
• L'accesso utilizza l'hash della password salvato; in alternativa, viene usato INITIAL_PASSWORD
• requireLogin è configurabile tramite /api/settings/require-login
• Le route /v1/* possono richiedere una chiave API Bearer quando REQUIRE_API_KEY=true
• In questa documentazione, "token di gestione" / "chiave API con ambito di gestione" indica una delle famiglie descritte in quella guida, non un tipo aggiuntivo di segreto non definito

Modifica incompatibile (v3.8.0) — /api/v1/agents/tasks/* e gli endpoint di gestione del periodo di attesa ora richiedono l'autenticazione per la gestione (cookie auth_token della dashboard o chiave API con ambito di gestione). I client che in precedenza chiamavano queste route senza autenticazione riceveranno 401 Unauthorized. Consulta il commit 588a0333 (fix(auth): require management auth for agent and cooldown APIs).