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

API Reference (Português (Portugal))

🌐 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-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

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

Referência principal para a API do OmniRoute. Abrange a interface pública /v1 e os endpoints de gestão mais utilizados; o ficheiro legível por máquinas docs/openapi.yaml e a árvore de rotas em src/app/api/ constituem as fontes exaustivas.

---

Índice

• Conclusões de chat
• Concessões exclusivas de sessões geridas
• Embeddings
• Geração de imagens
• OCR de documentos
• Listar modelos
• Manifesto do plugin do fornecedor
• Endpoints de compatibilidade
• API de ficheiros
• API de lotes
• API de pesquisa
• Streaming por WebSocket
• Comunicação de quotas e problemas
• Cache semântica
• Painel e gestão
• Gestão de combinações
• Webhooks
• Chaves registadas (gestão automática)
• Protocolo de agentes
• Proxies de gestão
• Resiliência (alargada)
• Competências
• Memória
• Servidor MCP
• Servidor A2A
• Cloud, avaliações e análise
• Processamento de pedidos
• Autenticação

---

Conclusões 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
}

Cabeçalhos personalizados

Cabeçalho	Direção	Descrição
X-OmniRoute-No-Cache	Pedido	Defina como true para ignorar a cache
x-omniroute-no-memory	Pedido	Defina como true para omitir a injeção de memória e competências neste pedido (reflete o comportamento sem cache; evita a sobrecarga de tokens/custo por chamada)
X-OmniRoute-Progress	Pedido	Defina como true para receber eventos de progresso
X-Session-Id	Pedido	Chave de sessão persistente para afinidade externa de sessões
x_session_id	Pedido	A variante com caráter de sublinhado também é aceite (HTTP direto)
X-OmniRoute-Session-Id	Pedido	Etiqueta de sessão/conversa fornecida pelo autor da chamada (também alimenta a memória). Quando presente, é mantida literalmente em call_logs.session_tag para atribuição de custos por sessão (#8249) — nunca é sintetizada quando ausente
Idempotency-Key	Pedido	Chave de desduplicação (janela de 5 s)
X-Request-Id	Pedido	Chave de desduplicação alternativa
X-OmniRoute-Cache	Resposta	HIT ou MISS (sem streaming)
X-OmniRoute-Idempotent	Resposta	true se tiver sido desduplicado
X-OmniRoute-Progress	Resposta	enabled se o acompanhamento do progresso estiver ativo
X-OmniRoute-Session-Id	Resposta	ID de sessão efetivo utilizado pelo OmniRoute
X-OmniRoute-Request-Id	Resposta	ID de correlação do pedido (quando conhecido)
X-OmniRoute-Version	Resposta	Versão da compilação do OmniRoute (sempre presente)
X-OmniRoute-Cost-Saved	Resposta	Valor em USD que a cache permitiu poupar num HIT (apenas acertos na cache)
X-OmniRoute-Decision	Resposta	Rasto do encaminhamento: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> é a estratégia da combinação ou single para um pedido que não utiliza uma combinação) — sempre presente nas respostas de conclusão

Nota sobre o Nginx: se depender de cabeçalhos com carateres de sublinhado (por exemplo, x_session_id), ative underscores_in_headers on;.

Cabeçalhos de telemetria de custos: as respostas bem-sucedidas sem streaming também incluem o conjunto de telemetria de custos X-OmniRoute-* — X-OmniRoute-Response-Cost (USD, com 10 casas decimais fixas; 0.0000000000 para utilização gratuita/sem preço definido), 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 (apenas quando > 0), além de X-OmniRoute-Request-Id e X-OmniRoute-Version. Estes são emitidos pelas conclusões de chat, por /v1/responses, /v1/messages e pelos endpoints de multimédia — /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/rerank, /v1/videos/generations, /v1/music/generations e /v1/moderations (custo sempre 0). O custo de multimédia é calculado por modalidade (por imagem, por segundo, por carácter, por unidade de pesquisa) quando os preços estão disponíveis; caso contrário, é 0 (fail-open).

Semântica de custos dos acertos de cache: num ACERTO da cache semântica (X-OmniRoute-Cache-Hit: true), não é efetuada qualquer chamada a montante, pelo que X-OmniRoute-Response-Cost é 0.0000000000 (o custo incremental de servir o acerto). O custo original/que teria sido incorrido é indicado separadamente em X-OmniRoute-Cost-Saved. Os sistemas consumidores de dados de faturação devem somar X-OmniRoute-Response-Cost (os acertos não têm custos); os sistemas de análise da cache podem agregar X-OmniRoute-Cost-Saved.

Concessões Exclusivas de Sessões Geridas

A concessão exclusiva de sessões geridas é um contrato de encaminhamento opcional e independente do cliente: um proprietário ativo detém uma ligação OmniRoute elegível. Não concede um modelo, não requer OAuth, não identifica um cliente específico, nem requer um fornecedor específico.

A chave de API usada na autenticação tem de ter o âmbito lease:exclusive e uma lista allowedConnections explícita e não vazia. O limite de mutação da base de dados impõe ambos os campos em conjunto durante a criação da chave e as atualizações parciais.

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

As respostas bem-sucedidas de aquisição, renovação e libertação expõem marcas temporais, state e o valor positivo exato de generation, mas nunca a ligação selecionada nem as credenciais. A renovação e a libertação fornecem a geração no corpo JSON:

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

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

O proprietário de uma concessão ativa pode solicitar explicitamente metadados de apresentação que preservam a privacidade para a sua associação atual:

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

Esta ação de estado opcional é delimitada pelo proprietário opaco, pela chave de API gerida autenticada e pela geração ativa exata numa única transação da base de dados. displayName é apenas o nome configurado da ligação sem espaços em branco no início ou no fim; é null quando não existe um nome configurado seguro. O OmniRoute nunca o substitui por um e-mail ou uma identidade de conta gerada. O valor do fornecedor é uma etiqueta de apresentação não sensível e nunca um identificador de fornecedor compatível gerado. São excluídos credenciais, tokens, cookies, identificadores não processados de ligações ou chaves de API, hashes de proprietários, segredos de delimitação e dados de encaminhamento internos.

As consultas com chave errada, proprietário errado, geração obsoleta, ausente, expirada, libertada ou invalidada devolvem todas o mesmo erro 409 LEASE_FENCE_STALE, sem metadados da ligação. Um cliente que tenha recebido a resposta de espera por capacidade não tem qualquer associação ativa para inspecionar. Quando o encaminhamento altera uma concessão ativa, a mesma geração permanece válida e o estado devolve atomicamente a nova associação, nunca a antiga. Os clientes existentes permanecem inalterados porque as respostas de aquisição, renovação, libertação e espera mantêm os respetivos formatos anteriores.

Este contrato do servidor não altera o /status do OpenAI Codex padrão. Atualmente, o Codex padrão comunica o seu fornecedor de modelo e o estado integrado de autenticação/conta, mas não apresenta metadados arbitrários de contas de fornecedores personalizados; uma futura integração do cliente terá de chamar esta ação e decidir como apresentar connection.displayName.

Cada pedido de inferência gerida fornece então ambos os cabeçalhos de controlo:

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

O proprietário exato, a geração, a ligação ativa e a chave de API autenticada são delimitados imediatamente antes de cada tentativa suportada junto do serviço a montante. A reutilização do proprietário e da geração com outra chave falha mesmo quando essa chave permite a mesma ligação. Os proprietários não processados não são conservados, registados, retidos no instantâneo do pedido nem reencaminhados para o serviço a montante.

A contenção temporária devolve HTTP 429 com Retry-After e:

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

Esta resposta significa apenas que o conjunto elegível normal não estava vazio e que todos os candidatos livres estavam detidos por uma concessão ativa de terceiros. Modelos/fornecedores não suportados, incompatibilidade de políticas, período de espera, quota, estado de funcionamento e outras falhas normais de elegibilidade mantêm as respostas existentes do OmniRoute.

x-omniroute-compression

Substituição, por pedido, do plano de compressão. Tem a precedência mais elevada — sobrepõe-se à substituição da combinação de encaminhamento, ao perfil ativo, à ativação automática e à Predefinição do painel. Valores:

Valor	Efeito
off	Sem compressão para este pedido.
default	O perfil Predefinido derivado do painel (ignora o perfil ativo).
engine:<id>	Um único motor, quando ativado, por exemplo, engine:rtk.
<combo>	Uma combinação nomeada, primeiro por correspondência de nome (sem distinção entre maiúsculas e minúsculas) e depois por identificador.

Notas:

• Os valores desconhecidos são ignorados (o pedido nunca é rejeitado); a resolução prossegue de acordo com a precedência normal dos operadores.
• Se várias combinações tiverem o mesmo nome, forneça o id da combinação para obter uma correspondência determinística.
• Uma combinação cujo nome seja off ou default não pode ser selecionada pelo nome (essas palavras-chave são interpretadas primeiro); referencie essa combinação pelo respetivo identificador.
• O comutador principal da compressão é uma restrição absoluta: quando a compressão está globalmente desativada, este cabeçalho não a pode ativar.

O plano aplicado é devolvido no cabeçalho da resposta:

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

em que <source> é um de request-header, routing-override, active-profile, auto-trigger, default ou 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"
}

Fornecedores disponíveis: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, Jina AI.

Os identificadores do catálogo seguem o formato provider/model (exemplo: jina-ai/jina-embeddings-v5-omni-small). Os identificadores simples de modelos Jina presentes no registo (por exemplo, jina-embeddings-v5-text-small, jina-reranker-v3.5) também são resolvidos. As operações embed/rerank/classify/segment da Jina utilizam primeiro as credenciais jina-ai do painel; JINA_AI_API_KEY é utilizada como alternativa apenas quando não existe nenhuma chave no painel. O cartão jina-reader destina-se apenas ao Reader / r.jina.ai (POST /v1/web/fetch) e nunca disponibiliza embeddings nem rerank.

Os modelos do registo que anunciam suporte multimodal também aceitam até 32 itens estruturados independentes do fornecedor. Os tipos de itens multimédia são text, image, audio, video e document. O respetivo source é {"type":"url","url":"https://..."} ou {"type":"base64","data":"...","media_type":"..."}.

O Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano e o alias da família jina-ai/jina-embeddings-v5-omni → omni-small) também aceita documentos EmbeddingsV5Request nativos da Jina e reencaminha-os intactos para 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,..." }]
    }
  ]
}

Os valores nativos { image | audio | video | pdf } podem ser um URL HTTPS público, um URI data: ou base64 em bruto. O OmniRoute não converte esses objetos em strings nem obtém URLs de imagens nativos — a Jina obtém os conteúdos multimédia públicos diretamente. Os campos adicionais da Jina (task, normalized, truncate, embedding_type) são reencaminhados. Os SKUs da Jina apenas de texto continuam a rejeitar documentos que não sejam de texto.

Limites de segurança e transporte:

• Os URLs de conteúdos multimédia remotos têm de utilizar HTTPS público. Os itens canónicos {type,source:url} são obtidos no lado do servidor (revalidação de redirecionamentos, limite de tempo, limites de tamanho, DNS público e fixação da ligação) e incorporados antes da chamada ao fornecedor. Os itens nativos da Jina {image:"https://..."} são reencaminhados tal como estão após a mesma verificação de HTTPS público; a Jina obtém o URL.
• Os conteúdos multimédia base64 incorporados estão limitados a 8 MiB descodificados por item e a 16 MiB descodificados em todo o pedido.

Tradução para o fornecedor (os itens canónicos nunca são reencaminhados sem alterações):

• Modelos multimodais da Jina: cada item de nível superior transforma-se num objeto com uma chave de modalidade (text / image / audio / video / pdf), utilizando URIs de dados para conteúdos multimédia incorporados; um vetor por item de nível superior.
• Família Gemini Embedding 2: uma matriz de nível superior transforma-se num único pedido nativo models/{model}:embedContent com content.parts (text ou inline_data).
• Os modelos desconhecidos/dinâmicos sem metadados explícitos de modalidade rejeitam entradas estruturadas com 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"
}

As combinações de modelo/modalidade não suportadas devolvem HTTP 400 em vez de converterem o item. Os campos de extensão que não sejam de entrada em pedidos legados de strings/tokens continuam a ser transmitidos sem alterações.

# Listar todos os modelos de embeddings
GET /v1/embeddings

---

Geração de imagens

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

{
  "model": "openai/gpt-image-2",
  "prompt": "Um belo pôr do sol sobre montanhas",
  "size": "1024x1024"
}

Fornecedores disponíveis: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, SD WebUI (local), ComfyUI (local).

# Listar todos os modelos de imagem
GET /v1/images/generations

---

OCR de documentos

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 seleciona o fornecedor de OCR através de um prefixo provider/model; um ID de modelo sem prefixo (por exemplo, mistral-ocr-latest) é associado ao respetivo fornecedor registado e, se model for omitido, é utilizado por predefinição o Mistral (mistral-ocr-latest). Fornecedores registados (open-sse/config/ocrRegistry.ts):

ID do fornecedor	ID do modelo	Valor de model	Notas
mistral	mistral-ocr-latest	mistral/mistral-ocr-latest (ou apenas mistral-ocr-latest)	Síncrono — a resposta é devolvida diretamente a partir da única chamada ao serviço a montante.
azure-document-intelligence	prebuilt-read	azure-document-intelligence/prebuilt-read	Serviço a montante assíncrono (analyze + consulta) — consulte abaixo.
vertex-deepseek-ocr	deepseek-ocr-maas	vertex-deepseek-ocr/deepseek-ocr-maas	Síncrono, através do endpoint parceiro openapi/chat/completions do Vertex AI — consulte abaixo para obter informações sobre a autenticação/URL.

Os três fornecedores respondem com o mesmo corpo no formato do Mistral:

{
  "pages": [{ "index": 0, "markdown": "# Texto extraído..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}

Fluxo de consulta do Azure Document Intelligence

A API analyze do Azure Document Intelligence é assíncrona: o pedido inicial devolve um cabeçalho Operation-Location em vez de um corpo, sendo necessário consultar o resultado. O processador (open-sse/handlers/ocr.ts) consulta esse URL a cada segundo, até um máximo de 30 tentativas, falha imediatamente (não continua a consultar) perante uma resposta de consulta que não seja ok ou um estado "failed" e devolve 504 se a operação ainda estiver em execução depois de esgotado o limite de tentativas. A resposta final do Azure é normalizada para o mesmo formato pages/markdown utilizado pelo Mistral antes de ser devolvida ao autor da chamada, pelo que o código do cliente não precisa de tratar o fornecedor como um caso especial.

Autenticação e resolução do endpoint do Vertex AI DeepSeek OCR

O vertex-deepseek-ocr reutiliza a mesma autenticação do Vertex AI já suportada pelo OmniRoute para tráfego de conversação/imagens (open-sse/executors/vertex.ts): a chave da API da ligação pode ser uma credencial JSON de conta de serviço (trocada por um token de acesso OAuth de curta duração através do fluxo JWT bearer) ou um token de acesso OAuth já emitido, utilizado tal como está. O URL do endpoint a montante é o endpoint parceiro genérico openapi/chat/completions do Vertex, criado a partir do projeto e da região da ligação — um providerSpecificData.project/providerSpecificData.region explícito tem sempre precedência; caso contrário, o projeto é derivado do project_id do JSON da conta de serviço e a região assume por predefinição us-central1. Ambas as resoluções ocorrem em open-sse/handlers/ocr.ts (resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl) e são utilizadas por src/app/api/v1/ocr/route.ts antes do encaminhamento para handleOcr.

---

Listar modelos

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

→ Devolve todos os modelos de conversação, embeddings e imagens + combinações no formato OpenAI

Prefixos de ID dos modelos (?prefix=)

A maioria dos modelos é anunciada sob um prefixo de fornecedor. O prefixo obtido é controlado pelo sinalizador de funcionalidade MODELS_CATALOG_PREFIX_MODE e pode ser substituído por pedido através de um parâmetro de consulta — útil para um cliente que pretenda uma lista simples sem alterar a definição global do servidor para todos os outros:

GET /v1/models?prefix=alias        # um ID por modelo — o prefixo de alias curto
GET /v1/models?prefix=dual         # ambas as formas (predefinição do servidor)
GET /v1/models?prefix=canonical    # apenas o prefixo completo do ID do fornecedor

Modo	Emite	Notas
dual	cc/claude-sonnet-4-6 e claude/claude-sonnet-4-6	Predefinição. Ambos os IDs encaminham para o mesmo modelo; são mantidos para que as configurações de clientes que tenham uma das formas codificada continuem a funcionar. Duplica aproximadamente o catálogo.
alias	cc/claude-sonnet-4-6	Uma entrada por modelo. Os fornecedores sem um alias distinto continuam a emitir a respetiva entrada, pelo que nada se perde.
canonical	claude/claude-sonnet-4-6	Uma entrada por modelo sob o prefixo completo do ID do fornecedor. Os fornecedores sem um alias distinto (por exemplo, antigravity/…, agy/…) também emitem aqui o seu único ID, pelo que nada se perde.

Um espelho em modo dual também pode ser reconhecido sem o parâmetro de consulta: inclui um campo parent que aponta para o ID principal.

Os clientes que apresentam um seletor de modelos devem pedir ?prefix=alias — é isto que a extensão OmniCopilot para o VS Code faz.

Variantes de modelos sem raciocínio

Para modelos Claude com capacidade de raciocínio, /v1/models também anuncia uma variante sem raciocínio, cujo ID tem o prefixo claude-3-omniroute-no-thinking/:

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

A seleção deste ID (por exemplo, numa configuração do Claude Code que inclui sempre um bloco thinking) é resolvida novamente para o verdadeiro <provider>/<model> com o raciocínio suprimido — thinking:{type:"disabled"} no caminho /v1/messages, ou com os campos reasoning/reasoning_effort removidos no caminho /v1/chat/completions. A variante só é apresentada para modelos da família Claude que suportam raciocínio e respeitam disabled (pelo que, por exemplo, são excluídos os modelos exclusivamente adaptativos que rejeitam disabled). Os operadores podem forçar a ativação ou desativação da variante por modelo através de ModelSpec.noThinkingAlias.

---

Manifesto do Plugin de Fornecedor

GET /api/v1/provider-plugin-manifest

Devolve o manifesto JSON seguro do plugin de fornecedor utilizado pelo Bifrost, CLIProxyAPI e futuros routers sidecar. A resposta é gerada a partir do registo de fornecedores TypeScript e exclui intencionalmente segredos de cliente OAuth, resolução do ambiente de execução, funções executoras, cabeçalhos de pedidos e dados de contas.

Utilize este endpoint quando um sidecar é executado fora do processo e não consegue importar open-sse/config/providerPluginManifestRegistry.ts diretamente.

---

Endpoints de Compatibilidade

Método	Caminho	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 (edição/inpainting)
POST	/v1/videos/generations	Geração de vídeo ao estilo OpenAI
POST	/v1/music/generations	Geração de música ao estilo OpenAI
POST	/v1/audio/transcriptions	OpenAI Audio (STT)
POST	/v1/audio/speech	OpenAI TTS (devolve corpo de áudio)
POST	/v1/rerank	Reranking ao estilo Cohere/Voyage
POST	/v1/classify	Classificação Jina (api.jina.ai)
POST	/v1/segment	Segmentador 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 do catálogo OpenAI
GET	/api/v1/vscode/{token}/models	Alias dos modelos OpenAI
POST	/api/v1/vscode/{token}/chat/completions	Alias OpenAI com token
POST	/api/v1/vscode/{token}/responses	Alias OpenAI Responses com token
POST	/api/v1/vscode/{token}/api/chat	Alias Ollama com token
GET	/api/v1/vscode/{token}/api/tags	Alias de etiquetas Ollama com token

Todas as rotas POST seguem a mesma estrutura: Bearer your-api-key + corpo JSON validado pelo Zod (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema, etc.; consulte src/shared/validation/schemas.ts). É devolvido um erro 4xx em caso de falha de validação do esquema.

Para clientes que não conseguem anexar Authorization: Bearer ..., o OmniRoute também aceita chaves de API no URL através da compatibilidade com parâmetros de consulta (?token=..., ?apiKey=..., ?api_key=..., ?key=...) ou dos endpoints dedicados /api/v1/vscode/{token}/... documentados abaixo.

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

# Classificação Jina (credenciais da Foundation API)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

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

# Pesquisa Jina (s.jina.ai; aliases de fornecedor: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# Moderações
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — devolve um corpo audio/mpeg (ou no formato solicitado)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Edição de imagem (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# Geração de vídeo/música (ID do modelo com prefixo do fornecedor)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

Rotas Dedicadas de Fornecedores

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

O prefixo do fornecedor é adicionado automaticamente se estiver em falta. Modelos não correspondentes devolvem 400.

---

API de Ficheiros

Endpoint de ficheiros compatível com a OpenAI para entrada/saída em lote e carregamentos com finalidade de ficheiro.

Método	Caminho	Descrição
POST	/v1/files	Carregar um ficheiro (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — máximo de 512 MiB
GET	/v1/files	Listar ficheiros da chave de API autenticada
GET	/v1/files/[id]	Obter os metadados de um ficheiro
DELETE	/v1/files/[id]	Eliminar um ficheiro
GET	/v1/files/[id]/content	Transmitir o conteúdo bruto do ficheiro

Autenticação: Chave de API Bearer — os ficheiros são delimitados por chave de API através de getApiKeyRequestScope. Uma chave apenas vê, transfere e elimina os seus próprios ficheiros; uma sessão do painel sem uma chave lê toda a instância; o acesso a um ficheiro sem proprietário (carregamento anónimo ou através de uma sessão do painel) é recusado a todos os autores de chamadas sem sessão. GET /v1/files rejeita um autor de chamada anónimo — e uma chave fornecida que não seja resolvida — com 401, mesmo quando REQUIRE_API_KEY=false, em vez de listar os ficheiros de todos os inquilinos (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

API de Lotes

Processamento em lote compatível com a OpenAI.

Método	Caminho	Descrição
POST	/v1/batches	Criar lote — corpo validado por v1BatchCreateSchema (input_file_id, endpoint, completion_window)
GET	/v1/batches	Listar lotes
GET	/v1/batches/[id]	Obter o estado do lote + request_counts
DELETE	/v1/batches/[id]	Eliminar um lote concluído/com falha
POST	/v1/batches/[id]/cancel	Cancelar um lote em curso

Autenticação: Chave de API Bearer. Os lotes são delimitados por chave de API segundo a mesma regra tripartida aplicada aos ficheiros: apenas a própria chave, sessão do painel para toda a instância, registos sem proprietário recusados a todos os autores de chamadas sem sessão (obtenção, eliminação, cancelamento e verificação de input_file_id durante a criação). GET /v1/batches rejeita um autor de chamada anónimo com 401, mesmo quando REQUIRE_API_KEY=false.

---

API de Pesquisa

Abstração de fornecedores de pesquisa/web (Tavily, Brave, Exa, Serper, etc.).

Método	Caminho	Descrição
GET	/v1/search	Lista os fornecedores de pesquisa configurados e as respetivas capacidades
POST	/v1/search	Executa uma consulta de pesquisa — corpo validado por v1SearchSchema, suporta cache/coalescência
GET	/v1/search/analytics	Estatísticas de acertos/latência/cache por fornecedor

Autenticação: chave de API Bearer (extractApiKey + isValidApiKey). Política de pesquisa aplicada através de enforceApiKeyPolicy.

---

API de Obtenção Web

Extrai conteúdo de um URL através de um fornecedor de obtenção web configurado (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

Método	Caminho	Descrição
POST	/v1/web/fetch	Obtém/extrai um URL — corpo validado por v1WebFetchSchema

Autenticação: chave de API Bearer (extractApiKey + isValidApiKey). Política aplicada através de enforceApiKeyPolicy.

Fallback sensível à quota (#8297): quando não é indicado um provider explícito, o conjunto (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) é percorrido por ordem fixa de prioridade (preenchimento do primeiro disponível) — um fornecedor configurado mas sujeito a limitação de pedidos é ignorado em vez de interromper imediatamente o pedido, e uma falha a montante repetível/de quota (HTTP 429 sempre; 402/403 para escalões gratuitos do tipo quota do Firecrawl/Tavily/TinyFish — não para o Jina Reader, e nunca para um simples pedido inválido 400) passa para o fornecedor seguinte ainda não experimentado e com credenciais, no momento do pedido. Quando todos os fornecedores do conjunto estiverem esgotados, o endpoint devolve um único 429 (com um cabeçalho Retry-After) em vez do anterior 400 genérico. Quando é solicitado um provider explícito, não existe fallback silencioso — um fornecedor explícito sujeito a limitação de pedidos ou com falha apresenta o seu próprio erro (429 se estiver sujeito a limitação de pedidos; caso contrário, o estado a montante).

---

Transmissão por WebSocket

GET /v1/ws?handshake=1

Valida um handshake de atualização para WebSocket e devolve as mensagens de exemplo do protocolo de comunicação (request, cancel). Os frames WS reais são processados pelo servidor WS incluído, fora da tabela de rotas do Next.js.

Autenticação: chave de API Bearer durante o handshake.

API Responses através de WebSocket (apenas codex)

# Mesmo anfitrião:porta que a API HTTP (predefinição 20128); atualizar a ligação:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (ou: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# O primeiro frame TEM DE ser response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

Um proxy de Responses-API-através-de-WebSocket está associado exclusivamente ao codex (backend do ChatGPT). Escuta na mesma porta que a API/painel nos caminhos /v1/responses, /responses e /api/v1/responses. No primeiro frame response.create, efetua a autenticação e a preparação através da ponte interna codex-responses-ws, seleciona uma ligação OAuth do codex e cria um túnel para wss://chatgpt.com/backend-api/codex/responses através do transporte wreq-js. Os modelos que não sejam codex são rejeitados (codex_ws_provider_required). Para encaminhamento por partilha de quota, utilize model: "qtSd/<group>/codex/<model>". Implementado em app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts.

Autenticação: chave de API Bearer durante o handshake. O servidor HTTP incluído (server-ws.mjs) tem de ser o ponto de entrada ativo (e é, por predefinição, quando app/server-ws.mjs existe).

ID do modelo: utilize o ID simples do ChatGPT (sem o prefixo codex/)

A CLI Codex da OpenAI valida o nome do modelo no lado do cliente quando supports_websockets = true e rejeita IDs com prefixo de fornecedor, como codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Envie o ID simples (por exemplo, gpt-5.5). A ponte do OmniRoute destina-se apenas ao codex, pelo que volta a resolver um ID simples como um modelo codex (resolveCodexWsModelInfo) antes de criar o túnel a montante — embora um gpt-5.5 simples fosse, de outra forma, encaminhado para outro fornecedor através de HTTP.

Configurar a CLI Codex da OpenAI

Direcione a CLI Codex para o OmniRoute adicionando um fornecedor personalizado com suporte para WebSocket a ~/.codex/config.toml (utilize um CODEX_HOME separado para evitar alterar uma configuração existente):

model = "gpt-5.5"                 # ID simples — NÃO "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # sem barra final; o URL WS é derivado (utilize https/wss em produção)
wire_api = "responses"                    # único valor suportado desde fevereiro de 2026
supports_websockets = true                # ativa o transporte Responses-através-de-WS
env_key = "OMNIROUTE_API_KEY"             # contém a chave de API do OmniRoute (Bearer)

export OMNIROUTE_API_KEY=sk-...           # uma chave de API do OmniRoute (qualquer chave se REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"

A CLI atualiza base_url + /responses para um WebSocket e o OmniRoute cria um túnel para a ligação OAuth do codex selecionada. Validado de ponta a ponta relativamente ao servidor local: o ChatGPT devolve codex.rate_limits + response.created e transmite a conclusão.

---

Relatórios de Quotas e Problemas

Método	Caminho	Descrição
GET	/v1/quotas/check	Pré-validar a quota para um provider + accountId antes de emitir uma chave registada
POST	/v1/issues/report	Comunicar ao GitHub uma falha de emissão de quota/chave (requer GITHUB_ISSUES_REPO + token)

Autenticação: chave de API Bearer (isAuthenticated).

---

Utilização em modo de autosserviço (/api/usage/om-usage)

Qualquer chave de API pode consultar a sua própria utilização e quotas — sem autenticação de gestão. Este é o endpoint que um cliente (CLI, o painel OmniCopilot) utiliza para mostrar ao titular de uma chave os respetivos gastos.

# Formato de texto (o contrato histórico — texto simples para um terminal)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Formato estruturado — o que uma IU consome
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

A chave tem de ter allowUsageCommand ativado (desativado por predefinição — o gestor de chaves de API do painel alterna esta opção por chave). Sem esta opção, o endpoint responde com 403.

?format=json devolve uma estrutura discriminada, para que o autor da chamada nunca leia um campo de dados de uma recusa. Em caso de sucesso:

{
  "allowed": true,
  // presente apenas quando a chave optou por limites de utilização por chave (USD diários/semanais):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // o instantâneo da quota do fornecedor selecionado, ou null quando ainda não existe nada em cache:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // o instantâneo de cada ligação, para que uma IU possa apresentar vários fornecedores lado a lado:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

Em caso de recusa (401 chave inválida / 403 não permitido), a mesma rota devolve { "allowed": false, "error": { "message": "…" } } — um personal/provider presente, mas vazio (chave permitida, ainda não foi obtida nenhuma informação), representa um estado diferente de uma recusa, e apenas o formato JSON permite distingui-los.

Autenticação: a própria chave de API Bearer do autor da chamada, validada com isValidApiKey — esta não é a interface de gestão (/api/keys/…), que permanece protegida por requireManagementAuth.

---

Cache Semântica

# Obter estatísticas da cache
GET /api/cache/stats

# Limpar todas as caches
DELETE /api/cache/stats

Exemplo de resposta:

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

Impacto na latência

Um HIT da cache semântica fornece a resposta a partir da cache **sem uma chamada ao serviço a montante **, pelo que o valor de X-OmniRoute-Response-Latency comunicado é próximo de zero (independentemente da latência original do serviço a montante). Os clientes sensíveis à latência (benchmarking, monitorização de p50/p99) devem verificar o cabeçalho de resposta X-OmniRoute-Cache-Latency:

Valor	Significado
synthetic	Resposta fornecida a partir da cache; a latência não é o tempo real do serviço a montante
(ausente)	Resposta de uma chamada real ao serviço a montante

Ignorar a cache por chave

As chaves de API podem optar por não fazer leituras da cache semântica através de cacheDefaultMode:

Valor	Comportamento
legacy	Comportamento normal da cache (predefinição)
bypass	Ignorar totalmente a consulta da cache; aceder sempre ao serviço a montante

Defina durante a criação da chave (POST /api/keys) ou atualização (PATCH /api/keys/[id]):

{ "cacheDefaultMode": "bypass" }

Ignorar a cache por pedido

Qualquer pedido pode ignorar a cache, independentemente das definições da chave:

X-OmniRoute-No-Cache: true

---

Painel e Gestão

As rotas de gestão (/api/*, exceto autenticação/início de sessão públicos) não são autorizadas por chaves de API de inferência comuns. Famílias de credenciais, âmbitos e exemplos com curl: Autenticação de Gestão.

Autenticação

Endpoint	Método	Descrição
/api/auth/login	POST	Iniciar sessão
/api/auth/logout	POST	Terminar sessão
/api/settings/require-login	GET/PUT	Ativar/desativar início de sessão obrigatório

Gestão de Fornecedores

Endpoint	Método	Descrição
/api/providers	GET/POST	Listar/criar fornecedores
/api/providers/[id]	GET/PUT/DELETE	Gerir um fornecedor
/api/providers/[id]/test	POST	Testar a ligação ao fornecedor
/api/providers/[id]/models	GET	Listar os modelos do fornecedor
/api/providers/validate	POST	Validar a configuração do fornecedor
/api/providers/bulk	POST	Adicionar em massa chaves de API para UM fornecedor
/api/providers/import	POST	Importar uma LISTA heterogénea de fornecedores a partir de um ficheiro CSV/JSON analisado (#6836); resultados por linha com falhas parciais
/api/provider-nodes*	Vários	Gestão de nós de fornecedores
/api/provider-models	GET/POST/PATCH/DELETE	Modelos personalizados (adicionar, atualizar, ocultar/mostrar, eliminar)

Fluxos OAuth

Endpoint	Método	Descrição
/api/oauth/[provider]/[action]	Vários	OAuth específico do fornecedor

Encaminhamento e Configuração

Endpoint	Método	Descrição
/api/models/alias	GET/POST	Aliases de modelos
/api/models/catalog	GET	Todos os modelos por fornecedor + tipo
/api/combos*	Vários	Gestão de combinações
/api/keys*	Vários	Gestão de chaves de API
/api/pricing	GET	Preços dos modelos

Utilização e Análise

Endpoint	Método	Descrição
/api/usage/history	GET	Histórico de utilização
/api/usage/logs	GET	Registos de utilização
/api/usage/request-logs	GET	Registos ao nível dos pedidos
/api/usage/[connectionId]	GET	Utilização por ligação
/api/usage/token-limits	GET/POST/DELETE	Limites de tokens por chave de API
/api/usage/model-latency-stats	GET	Agregação contínua da latência por fornecedor/modelo (média/p50/p95/p99, taxa de sucesso); filtros: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health	GET	Resumo do estado da cache de prompts em call_logs — proporção de escrita/leitura, distribuição p50/p90/p99 do tamanho de escrita, concentração de escritas intensivas, divisão por modelo e um veredito healthy/degraded/thrash/no-data; parâmetros de consulta range (1h|24h|7d|30d, predefinição 24h) e model opcional (#8827)

Definições

Endpoint	Método	Descrição
/api/settings	GET/PUT/PATCH	Definições gerais
/api/settings/proxy	GET/PUT	Configuração do proxy de rede
/api/settings/proxy/test	POST	Testar a ligação ao proxy
/api/settings/ip-filter	GET/PUT	Lista de permissões/bloqueios de IP
/api/settings/thinking-budget	GET/PUT	Modo de reescrita de pedidos do orçamento de pensamento/raciocínio (passagem direta / remoção automática / personalizado / adaptativo). Independente da compressão. Consulte THINKING_BUDGET.md.
/api/settings/system-prompt	GET/PUT	Prompt de sistema global
/api/settings/compression	GET/PUT	Configuração global de compressão
/api/settings/purge-request-history	POST	Limpar as linhas do registo de pedidos e os artefactos locais do registo de chamadas

Contexto e compressão

Endpoint	Método	Descrição
/api/compression/preview	POST	Pré-visualizar compressão off/lite/standard/aggressive/ultra/RTK/stacked
/api/compression/language-packs	GET	Listar pacotes de idiomas Caveman disponíveis
/api/compression/rules	GET	Listar metadados das regras Caveman
/api/context/caveman/config	GET/PUT	Alias das definições específicas do Caveman
/api/context/rtk/config	GET/PUT	Definições específicas do RTK, incluindo filtros personalizados e retenção da saída não processada
/api/context/rtk/filters	GET	Catálogo de filtros RTK e diagnósticos de filtros personalizados
/api/context/rtk/test	POST	Executar a pré-visualização/teste do RTK com um payload de texto
/api/context/rtk/raw-output/[id]	GET	Ler a saída não processada, anonimizada e retida, através do ID do ponteiro
/api/context/combos	GET/POST	Listar/criar combinações de compressão
/api/context/combos/[id]	GET/PUT/DELETE	Consultar/atualizar/eliminar os detalhes de uma combinação de compressão
/api/context/combos/[id]/assignments	GET/PUT	Atribuir combinações de compressão a combinações de encaminhamento
/api/context/analytics	GET	Alias das análises de compressão

Monitorização

Endpoint	Método	Descrição
/api/sessions	GET	Acompanhamento de sessões ativas
/api/rate-limits	GET	Limites de frequência por conta
/api/monitoring/health	GET	Verificação do estado de funcionamento + resumo dos fornecedores (catalogCount, configuredCount, activeCount, monitoredCount). A vista de gestão inclui credentialHealth: valores escalares da cache de sondagens, failedConnections quando failed>0 e staleDbNonOkCount (test_status persistente do SQLite, não o indicador). Consulte MONITORING_GUIDE.md.
/api/cache/stats	GET/DELETE	Estatísticas da cache / limpar
/api/modality-bridge/stats	GET	attempts em memória, sucessos/bridged, falhas, acertos da cache, totalLatencyMs, latencySamples, averageLatencyMs calculada com base no número de amostras e hora da última utilização (reposto ao reiniciar; autenticação de gestão)
/api/modality-bridge/video/runtime	GET	Verificação rigorosa de loopback fidedigno antes da autenticação/sondagem de gestão; disponibilidade e versões sanitizadas do FFmpeg/ffprobe (no-store)
/api/modality-bridge/video/extract	POST	Intermediário interno autenticado de bytes através de loopback fidedigno; entrada de 50 MiB, fila limitada/saída de 32 MiB, capacidade 503, desconexão 499, prazo excedido 504; não é uma API pública de carregamento

Cópia de segurança e exportação/importação

Endpoint	Método	Descrição
/api/db-backups	GET	Listar cópias de segurança disponíveis
/api/db-backups	PUT	Criar uma cópia de segurança manual
/api/db-backups	POST	Restaurar a partir de uma cópia específica
/api/db-backups/export	GET	Transferir a base de dados como ficheiro .sqlite
/api/db-backups/import	POST	Carregar um ficheiro .sqlite para substituir a base de dados
/api/db-backups/exportAll	GET	Transferir a cópia de segurança completa como arquivo .tar.gz

Sincronização na nuvem

Endpoint	Método	Descrição
/api/sync/cloud	Vários	Operações de sincronização na nuvem
/api/sync/initialize	POST	Inicializar a sincronização
/api/cloud/*	Vários	Gestão da nuvem

Túneis

Endpoint	Método	Descrição
/api/tunnels/cloudflared	GET	Consultar o estado de instalação/execução do Cloudflare Quick Tunnel no painel
/api/tunnels/cloudflared	POST	Ativar ou desativar o Cloudflare Quick Tunnel (action=enable/disable)
/api/tunnels/ngrok	GET	Consultar o estado de execução do ngrok Tunnel no painel
/api/tunnels/ngrok	POST	Ativar ou desativar o ngrok Tunnel (action=enable/disable)

Ferramentas CLI

Endpoint	Método	Descrição
/api/cli-tools/claude-settings	GET	Estado da CLI Claude
/api/cli-tools/codex-settings	GET	Estado da CLI Codex
/api/cli-tools/droid-settings	GET	Estado da CLI Droid
/api/cli-tools/openclaw-settings	GET	Estado da CLI OpenClaw
/api/cli-tools/runtime/[toolId]	GET	Execução genérica da CLI

As respostas da CLI incluem: installed, runnable, command, commandPath, runtimeMode, reason.

Agentes ACP

Endpoint	Método	Descrição
/api/acp/agents	GET	Listar todos os agentes detetados (integrados + personalizados) com estado
/api/acp/agents	POST	Adicionar um agente personalizado ou atualizar a cache de deteção
/api/acp/agents	DELETE	Remover um agente personalizado através do parâmetro de consulta id

A resposta GET inclui agents[] (id, name, binary, version, installed, protocol, isCustom) e summary (total, installed, notFound, builtIn, custom).

Resiliência e limites de taxa

Endpoint	Método	Descrição
/api/resilience	GET/PATCH	Obter/atualizar a fila de pedidos, o período de espera da ligação, o disjuntor do fornecedor e as definições de espera
/api/resilience/reset	POST	Repor os disjuntores dos fornecedores
/api/resilience/model-cooldowns	GET	Listar bloqueios ativos por (fornecedor, ligação, modelo), ordenados pelo tempo restante
/api/resilience/model-cooldowns	DELETE	Limpar um bloqueio de modelo — corpo {provider, model} ou {all: true} para limpar tudo
/api/rate-limits	GET	Estado do limite de taxa por conta
/api/rate-limit	GET	Configuração global do limite de taxa

As quatro rotas /api/resilience/* requerem autenticação de gestão (requireManagementAuth). Consulte Resiliência (alargada) para uma análise completa das diferenças entre o disjuntor do fornecedor, o período de espera da ligação e o bloqueio do modelo.

Avaliações

Endpoint	Método	Descrição
/api/evals	GET/POST	Listar conjuntos de avaliação/executar avaliação

Políticas

Endpoint	Método	Descrição
/api/policies	GET/POST/DELETE	Gerir políticas de encaminhamento

Conformidade

Endpoint	Método	Descrição
/api/compliance/audit-log	GET	Registo de auditoria de conformidade (últimos N)

v1beta (compatível com Gemini)

Endpoint	Método	Descrição
/v1beta/models	GET	Listar modelos no formato Gemini
/v1beta/models/{...path}	POST	Endpoint generateContent do Gemini

Estes endpoints reproduzem o formato da API do Gemini para clientes que esperam compatibilidade nativa com o SDK do Gemini.

APIs internas/do sistema

Endpoint	Método	Descrição
/api/init	GET	Verificação da inicialização da aplicação (utilizada na primeira execução)
/api/tags	GET	Etiquetas de modelos compatíveis com Ollama (para clientes Ollama)
/api/restart	POST	Aciona o reinício controlado do servidor
/api/shutdown	POST	Aciona o encerramento controlado do servidor
/api/system/env/repair	POST	Repara as variáveis de ambiente do fornecedor OAuth

Nota: Estes endpoints são utilizados internamente pelo sistema ou para compatibilidade com clientes Ollama. Normalmente, não são chamados pelos utilizadores finais.

Reparação do ambiente OAuth (v3.6.1+)

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

{
  "provider": "claude-code"
}

Repara variáveis de ambiente OAuth em falta ou danificadas para um fornecedor específico. Devolve:

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

---

Transcrição de áudio

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

Transcreva ficheiros de áudio utilizando qualquer fornecedor de STT configurado. O primeiro segmento do caminho seleciona o fornecedor nativo (openai/…, deepgram/…). Os gateways que reexportam o modelo de outro fornecedor utilizam um ID qualificado (openrouter/deepgram/nova-3).

Pedido:

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

Resposta:

{
  "text": "Olá, este é o conteúdo de áudio transcrito.",
  "task": "transcribe",
  "language": "en",
  "duration": 12.5
}

Exemplos de IDs de modelos: openai/whisper-1 (requer uma chave da OpenAI), openrouter/deepgram/nova-3 (requer uma chave da OpenRouter), deepgram/nova-3 (requer uma chave nativa da Deepgram). Um pedido simples deepgram/nova-3 não utiliza a OpenRouter.

Formatos suportados: mp3, wav, m4a, flac, ogg, webm.

---

Compatibilidade com Ollama

Para clientes que utilizam o formato da API da Ollama:

# Endpoint de conversação (formato Ollama)
POST /v1/api/chat

# Listagem de modelos (formato Ollama)
GET /api/tags

Os pedidos são traduzidos automaticamente entre os formatos Ollama e internos.

Aliases tokenizados do VS Code / sem cabeçalho

Utilize estes aliases quando uma integração não conseguir injetar um cabeçalho Authorization e precisar de incorporar a chave da API no URL base.

# Alias de catálogo ao estilo da OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# Aliases de conversação ao estilo da OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Aliases ao estilo da Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

Exemplo:

curl https://your-host.example/api/v1/vscode/YOUR_API_KEY/models
curl -X POST https://your-host.example/api/v1/vscode/YOUR_API_KEY/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}'

Notas:

• Os aliases tokenizados reutilizam os mesmos processadores que /v1/* e /api/tags; os formatos das respostas permanecem idênticos.
• Dê preferência a Authorization: Bearer ... sempre que o cliente suportar cabeçalhos personalizados.
• Os tokens baseados em URL podem aparecer nos registos do proxy inverso, no histórico do navegador e na telemetria fora do OmniRoute. Considere-os uma opção de compatibilidade, não o modo de autenticação predefinido.

---

Telemetria

# Obter o resumo da telemetria de latência (p50/p95/p99 por fornecedor)
GET /api/telemetry/summary

Resposta:

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

---

Orçamento

# Obter o estado do orçamento para todas as chaves da API
GET /api/usage/budget

# Definir ou atualizar um orçamento
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"
}

Notas do esquema (setBudgetSchema): apiKeyId é obrigatório; pelo menos um de dailyLimitUsd, weeklyLimitUsd ou monthlyLimitUsd tem de ser superior a zero. Campos opcionais: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). O formato antigo {keyId, limit, period} devolve 400 Bad Request.

Limites de tokens

Orçamentos de tokens por chave de API (distintos do Orçamento baseado em USD acima). Aplicados diretamente no percurso do pedido: quando a utilização de uma chave na janela atual atinge o respetivo limite, os pedidos são rejeitados com 429 Too Many Requests. Os limites podem ser restringidos a um model específico, a um provider ou aplicados de forma global em toda a chave; quando vários limites correspondem a um pedido, prevalece o mais restritivo.

# Listar os limites de tokens de uma chave (inclui a utilização atual da janela)
GET /api/usage/token-limits?apiKeyId=key-123

# Criar ou atualizar um limite de tokens
POST /api/usage/token-limits
Content-Type: application/json

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

# Eliminar um limite de tokens por id
DELETE /api/usage/token-limits?id=tl-abc

Notas sobre o esquema (setTokenLimitSchema): apiKeyId e scopeType (model | provider | global) são obrigatórios. scopeValue é obrigatório, exceto quando scopeType é global (por exemplo, um id de modelo para o âmbito model ou um id de fornecedor para o âmbito provider). tokenLimit tem de ser um número inteiro positivo (convertido a partir de uma cadeia de caracteres). Opcionais: id (omitir para criar, fornecer para atualizar), resetInterval (daily | weekly | monthly, predefinição monthly), resetTime (HH:MM), enabled (predefinição true). As respostas GET complementam cada limite com tokensUsed, remaining, windowStart, periodStartAt e nextResetAt. Este é um endpoint da classe de gestão (autenticação aplicada centralmente pelo pipeline de autorização).

Processamento de pedidos

1. O cliente envia um pedido para /v1/*
2. O processador de rotas chama handleChat, handleEmbedding, handleAudioTranscription ou handleImageGeneration
3. O modelo é resolvido (fornecedor/modelo direto ou alias/combinação)
4. As credenciais são selecionadas a partir da base de dados local, com filtragem pela disponibilidade da conta
5. Para conversação: handleChatCore verifica a cache semântica/de assinaturas e resolve as definições de compressão da combinação
6. A compressão proativa é executada antes da tradução para o fornecedor, quando ativada (lite, Caveman, RTK ou em cadeia)
7. O executor do fornecedor envia o pedido para o serviço a montante
8. A resposta é novamente traduzida para o formato do cliente (conversação) ou devolvida tal como está (embeddings/imagens/áudio)
9. A utilização, as análises de compressão e os registos de pedidos são guardados
10. Em caso de erro, é aplicado o recurso alternativo de acordo com as regras da combinação

Referência completa da arquitetura: ARCHITECTURE.md

---

Gestão de combinações

As combinações de encaminhamento de nível superior (já resumidas em /api/combos*) também podem ser mapeadas 1:1 a partir de um padrão de id de modelo, permitindo o redirecionamento transparente de um id de modelo ao estilo da OpenAI para uma combinação.

Método	Caminho	Descrição
GET	/api/model-combo-mappings	Listar todos os mapeamentos modelo→combinação
POST	/api/model-combo-mappings	Criar mapeamento — corpo: {pattern, comboId, priority?, enabled?, description?}
GET	/api/model-combo-mappings/[id]	Obter um único mapeamento
PUT	/api/model-combo-mappings/[id]	Atualizar campos de um mapeamento existente
DELETE	/api/model-combo-mappings/[id]	Remover um mapeamento

Autenticação: sessão/chave de API de gestão (requireManagementAuth).

---

Webhooks

Subscrições de webhooks de saída para eventos do OmniRoute (conclusão de pedidos, esgotamento de quotas, rotação de chaves, etc.).

Método	Caminho	Descrição
GET	/api/webhooks	Lista os webhooks (os segredos são ocultados como <prefix>...)
POST	/api/webhooks	Cria um webhook — corpo: {url, events?: ["*"], secret?, description?}
GET	/api/webhooks/[id]	Obtém um webhook
PUT	/api/webhooks/[id]	Atualiza url/events/secret/description
DELETE	/api/webhooks/[id]	Remove um webhook
POST	/api/webhooks/[id]/test	Envia um payload de teste para o URL do webhook e devolve o estado da entrega

Autenticação: sessão de gestão/chave de API (requireManagementAuth).

---

Chaves registadas (gestão automática)

Utilizadas pelo subsistema de gestão automática de chaves para emitir e rodar chaves de API junto de um fornecedor/uma conta subjacente, com quotas diárias/horárias.

Método	Caminho	Descrição
GET	/api/v1/registered-keys	Lista as chaves registadas (apenas o prefixo ocultado)
POST	/api/v1/registered-keys	Emite uma nova chave registada — corpo: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. Devolve a chave não ocultada uma única vez. Devolve 429 se a quota for recusada.
GET	/api/v1/registered-keys/[id]	Obtém os metadados de uma chave registada (sem o conteúdo não ocultado)
DELETE	/api/v1/registered-keys/[id]	Revoga uma chave registada
POST	/api/v1/registered-keys/[id]/revoke	Endpoint de revogação explícita (o mesmo efeito que DELETE)

Autenticação: chave de API Bearer (isAuthenticated). Consulte também /v1/quotas/check e /v1/issues/report.

---

Protocolo de Agentes

Tarefas de agentes na cloud (Claude Code, Codex Cloud, OpenHands, etc.) executadas remotamente em nome dos utilizadores do OmniRoute.

Método	Caminho	Descrição
GET	/api/v1/agents/tasks	Lista tarefas — ?provider=, ?status=, ?limit= opcionais (1–500, predefinição: 50)
POST	/api/v1/agents/tasks	Cria uma tarefa — corpo validado por CreateCloudAgentTaskSchema (providerId, prompt, source, options?). Devolve 201 com o envelope da tarefa
DELETE	/api/v1/agents/tasks?id=...	Elimina uma tarefa
GET	/api/v1/agents/tasks/[id]	Lê uma tarefa — atualiza sincronamente o estado a partir do agente na cloud a montante quando external_id está definido
POST	/api/v1/agents/tasks/[id]	Ação discriminada: {action: "approve"}, {action: "message", message} ou {action: "cancel"}
DELETE	/api/v1/agents/tasks/[id]	Elimina uma tarefa específica por id

Autenticação: é necessária autenticação de gestão em todos os métodos (requireCloudAgentManagementAuth). Antes da v3.8.0, estes métodos não exigiam autenticação — consulte o commit 588a0333 para obter informações sobre a alteração incompatível.

# Criar uma tarefa na cloud do 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":"..."}}'

---

Proxies de Gestão

Proxies HTTP(S)/SOCKS de saída que podem ser atribuídos a fornecedores, contas ou globalmente.

Método	Caminho	Descrição
GET	/api/v1/management/proxies	Lista proxies (com ?id= devolve um; com ?id=&where_used=1 devolve o grafo de atribuições)
POST	/api/v1/management/proxies	Cria um proxy — corpo validado por createProxyRegistrySchema
PATCH	/api/v1/management/proxies	Atualiza um proxy — corpo validado por updateProxyRegistrySchema (requer id)
DELETE	/api/v1/management/proxies?id=...&force=1	Elimina um proxy (utilize force=1 para remover as atribuições)
GET	/api/v1/management/proxies/assignments	Lista atribuições — filtráveis por proxy_id, scope, scope_id; indique resolve_connection_id=<id> para determinar o proxy ativo de uma ligação
PUT	/api/v1/management/proxies/assignments	Atribui — corpo validado por proxyAssignmentSchema ({scope, scopeId?, proxyId?}). Limpa a cache do dispatcher
PUT	/api/v1/management/proxies/bulk-assign	Efetua uma atribuição em massa — corpo validado por bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?})
GET	/api/v1/management/proxies/health?hours=24	Agrega o estado dos proxies (contagens de sucessos/falhas, latência) ao longo de um período

Autenticação: sessão de gestão/chave de API em todas as rotas (requireManagementAuth).

Os endpoints POST /api/v1/management/proxies/[id]/assignments e POST /api/v1/management/proxies/[id]/health da descrição da tarefa são disponibilizados através das rotas planas /assignments e /health apresentadas acima — não existem sub-rotas por id na base de código.

---

Resiliência (alargada)

O OmniRoute disponibiliza três mecanismos independentes para falhas temporárias; os endpoints de gestão abaixo permitem aos operadores consultá-los e substituí-los:

Âmbito	Armazenamento do estado	Consulta	Reposição / limpeza
Disjuntor do fornecedor	domain_circuit_breakers + em memória	/api/monitoring/health	POST /api/resilience/reset
Suspensão temporária da ligação	rateLimitedUntil nas ligações dos fornecedores	/api/rate-limits, /api/providers/[id]	(reativa-se de forma diferida; limpar via PUT do fornecedor)
Bloqueio do modelo	Registo de disponibilidade dos modelos em memória	GET /api/resilience/model-cooldowns	DELETE /api/resilience/model-cooldowns

PATCH /api/resilience aceita substituições do disjuntor do fornecedor em providerBreaker.oauth e providerBreaker.apikey. Cada perfil suporta degradationThreshold, failureThreshold e resetTimeoutMs; os mesmos campos estão disponíveis em Painel → Definições → Resiliência.

# Limpar o bloqueio de um único modelo
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"}'

# Limpar todos os bloqueios
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

Para obter a referência conceptual completa e os valores predefinidos do disjuntor, consulte CLAUDE.md → "Estado de execução da resiliência".

---

Competências

Framework de competências para expandir o OmniRoute com processadores executáveis personalizados, além de integrações com marketplaces.

Método	Caminho	Descrição
GET	/api/skills	Lista as competências instaladas — filtráveis por ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local, com paginação
GET	/api/skills/[id]	Obtém uma competência
PUT	/api/skills/[id]	Atualiza uma competência (nome, descrição, modo, esquema, processador, etiquetas)
DELETE	/api/skills/[id]	Desinstala uma competência
POST	/api/skills/install	Instala uma competência a partir de um manifesto em bruto — corpo: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET	/api/skills/executions	Lista as execuções recentes de competências (registo de auditoria com entradas/saídas/duração)
GET	/api/skills/marketplace?q=...	Pesquisa/lista de populares do marketplace SkillsMP (requer a definição skillsmpApiKey)
POST	/api/skills/marketplace/install	Instala uma competência pelo ID do SkillsMP
GET	/api/skills/skillssh?q=&limit=	Pesquisa no registo skills.sh
POST	/api/skills/skillssh/install	Instala uma competência pelo ID do skills.sh

Autenticação: sessão de gestão/chave de API. As rotas de pesquisa em marketplaces aceitam autenticação de gestão ou uma chave de API Bearer (isAuthenticated).

---

Memória

Armazenamento persistente de memória conversacional/factual, limitado por chave de API/sessão.

Método	Caminho	Descrição
GET	/api/memory	Lista memórias — ?apiKeyId=, ?type=, ?sessionId=, ?q=, com paginação offset/limit ou page/limit
POST	/api/memory	Cria uma memória — corpo validado pelo Zod: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}
GET	/api/memory/[id]	Obtém uma memória
DELETE	/api/memory/[id]	Elimina uma memória
GET	/api/memory/health	Estado de funcionamento do subsistema de memória (conectividade à BD, backend de embeddings, estado do índice vetorial)

Autenticação: sessão de gestão/chave de API (requireManagementAuth). Enumeração type: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (consulte MemoryType em src/lib/memory/types.ts).

---

Servidor MCP

O OmniRoute inclui um servidor Model Context Protocol integrado com 3 transportes (stdio, SSE, streamable-http) e ferramentas com âmbitos definidos. Os endpoints do dashboard abaixo leem dados de estado/auditoria e atuam como proxy dos transportes HTTP.

Método	Caminho	Descrição
GET	/api/mcp/status	Heartbeat, transporte, estado online, última chamada, ferramentas mais utilizadas, taxa de sucesso nas últimas 24 h
GET	/api/mcp/tools	Lista de ferramentas MCP com name, description, scopes, phase, auditLevel, sourceEndpoints
GET	/api/mcp/sse	Abre um fluxo SSE para o transporte SSE (devolve 503 se o MCP estiver desativado ou o transporte não corresponder)
POST	/api/mcp/sse	Envia uma trama JSON-RPC através do transporte SSE
GET	/api/mcp/stream	Abre o lado SSE do transporte Streamable HTTP (mensagens iniciadas pelo servidor)
POST	/api/mcp/stream	Envia uma trama JSON-RPC através do transporte Streamable HTTP
DELETE	/api/mcp/stream	Termina uma sessão Streamable HTTP
GET	/api/mcp/audit	Consulta o registo de auditoria — ?limit=, ?offset=, ?tool=, `?success=true	false, ?apiKeyId=`
GET	/api/mcp/audit/stats	Estatísticas agregadas de auditoria (totais, taxa de sucesso, duração média, ferramentas mais utilizadas)

Autenticação: os transportes sse/stream respeitam a interface de autenticação específica do MCP (chave de API Bearer com âmbito mcp); as rotas status/tools/audit* podem ser lidas a partir do dashboard (não é necessária autenticação adicional para além de conseguir aceder ao anfitrião do dashboard).

Ambos os transportes HTTP são controlados por settings.mcpEnabled e settings.mcpTransport — uma incompatibilidade de transporte devolve 400; um estado de MCP desativado devolve 503.

---

Servidor A2A

O OmniRoute disponibiliza um ponto final A2A (Agente para Agente) JSON-RPC 2.0, bem como um wrapper REST para utilização em inspeção/painéis.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # opcional, exceto se OMNIROUTE_API_KEY estiver definida
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "skill": "smart-routing",
    "messages": [{"role": "user", "content": "Encaminhe esta tarefa de programação"}]
  }
}

Métodos suportados (todos condicionados a settings.a2aEnabled):

Método	Descrição
message/send	Execução síncrona de competências; devolve {task, artifacts, metadata}
message/stream	Execução SSE em streaming do mesmo conjunto de competências
tasks/get	Obtém uma tarefa através de taskId
tasks/cancel	Cancela uma tarefa através de taskId

Competências incorporadas: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.

Cartão do agente

GET /.well-known/agent.json

Devolve o cartão público do agente A2A (nome, descrição, capacidades, catálogo de competências, esquema de autenticação) — armazenado publicamente em cache durante 1 h. Não requer autenticação.

Auxiliares REST

Método	Caminho	Descrição
GET	/api/a2a/status	A2A ativado + estatísticas de tarefas + resumo do cartão do agente em cache
GET	/api/a2a/tasks	Lista tarefas — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset=
POST	/api/a2a/tasks	(Não implementado como auxiliar REST — criar através de JSON-RPC message/send)
GET	/api/a2a/tasks/[id]	Obtém uma tarefa
POST	/api/a2a/tasks/[id]/cancel	Cancela uma tarefa

Autenticação: os auxiliares REST são executados sem autenticação de gestão (podem ser consultados pelo painel); a rota JSON-RPC /a2a utiliza o Bearer OMNIROUTE_API_KEY, caso esteja configurado.

---

Cloud, avaliações e análise

Método	Caminho	Descrição
POST	/api/cloud/auth	Verifica uma chave Bearer e devolve ligações de fornecedores mascaradas + aliases de modelos para clientes de sincronização na cloud
POST	/api/cloud/credentials/update	Atualiza credenciais encriptadas de um fornecedor sincronizado com a cloud
POST	/api/cloud/model/resolve	Resolve um ID de modelo lógico para um fornecedor/modelo concreto utilizando a tabela de encaminhamento local
GET	/api/cloud/models/alias	Lista aliases de modelos conforme disponibilizados à sincronização na cloud
GET	/api/assess	Lê as categorizações da avaliação mais recente (por fornecedor/modelo)
POST	/api/assess	Executa uma avaliação — corpo: `{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	/api/evals	Lista conjuntos de avaliações incorporados + execuções mais recentes
POST	/api/evals	Inicia uma execução de avaliação
POST	/api/evals/suites	Cria um conjunto de avaliações personalizado — corpo validado por evalSuiteSaveSchema
GET	/api/evals/suites/[id]	Obtém um conjunto de avaliações personalizado

Autenticação: /api/cloud/auth valida diretamente uma chave Bearer; as restantes rotas /api/cloud/*, /api/evals/* e /api/assess requerem uma sessão/chave de API de gestão. O POST de /api/assess utiliza validateBody com um esquema de âmbito de união discriminada.

---

Gestão de ACP (Agent Client Protocol)

como processos-filho. Estes endpoints gerem a deteção de agentes ACP e o registo de agentes personalizados.

Método	Caminho	Descrição
GET	/api/acp/agents	Lista todos os agentes CLI conhecidos (integrados + personalizados), incluindo o estado de instalação, a versão e o binário
POST	/api/acp/agents	Regista um agente ACP personalizado ou atualiza a cache — corpo: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} ou {action: "refresh"}
DELETE	/api/acp/agents	Remove um agente ACP personalizado — parâmetro de consulta: ?id=<agentId>

Exemplo de resposta (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
}

Autenticação: Requer uma sessão de gestão (cookie auth_token do dashboard) ou uma chave de API com âmbito de gestão.

Consulte Framework ACP para obter todos os detalhes.

---

Análise e observabilidade

Endpoints de análise em tempo real para monitorizar o encaminhamento, a compressão e a diversidade de fornecedores. Estes suportam as páginas /dashboard/analytics/*.

Análise do encaminhamento automático

Método	Caminho	Descrição
GET	/api/analytics/auto-routing	Estatísticas agregadas do encaminhamento automático: total de chamadas, distribuição por estratégia, escalão e fornecedores principais
GET	/api/analytics/auto-routing?days=7	Estatísticas para um intervalo temporal (predefinição: 24 h)

Exemplo de resposta:

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

Análise da compressão

Método	Caminho	Descrição
GET	/api/analytics/compression	Estatísticas agregadas da compressão: tokens poupados, percentagem de poupança, distribuição por modo e utilização do motor

Exemplo de resposta:

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

Monitorização da diversidade de fornecedores

Método	Caminho	Descrição
GET	/api/analytics/diversity	Monitorização da diversidade baseada na entropia de Shannon: evita pontos únicos de falha ao medir a distribuição por fornecedor

Exemplo de resposta:

{
  "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": ["A OpenAI representa 40% do tráfego — considere diversificar"]
}

Autenticação: Requer uma sessão de gestão ou uma chave de API com âmbito de gestão.

---

Operações de Administração

Endpoints exclusivos para administradores destinados à gestão operacional.

Método	Caminho	Descrição
GET	/api/admin/concurrency	Consultar os limites de concorrência atuais (globais + por fornecedor)
POST	/api/admin/concurrency	Atualizar os limites de concorrência — corpo: {global?: number, perProvider?: Record<string, number>}

Autenticação: Requer uma sessão de gestão com âmbito de administrador.

---

Gestão de Ferramentas CLI

Faça a gestão das ferramentas CLI que se integram com o OmniRoute (antigravity, chipotle, commandCode, devin-cli, etc.). Consulte a Referência de Fornecedores para obter a lista completa.

Método	Caminho	Descrição
GET	/api/cli-tools/all-statuses	Estado de todas as ferramentas CLI (instalada, versão, última utilização)
GET	/api/cli-tools/status	Detalhes do estado de uma ferramenta CLI (consulta ?tool=)
POST	/api/cli-tools/apply	Escrever a configuração gerada de uma ferramenta (dryRun apresenta uma pré-visualização; 422 + containerEphemeralTarget quando executada num contentor; migration assinala um YAML legado do Codex)
GET	/api/cli-tools/backups	Listar cópias de segurança das configurações das ferramentas CLI
POST	/api/cli-tools/backups	Criar uma cópia de segurança das configurações de todas as ferramentas CLI
POST	/api/cli-tools/backups	Restaurar: o mesmo endpoint com {tool, backupId} no corpo restaura essa cópia de segurança
GET	/api/cli-tools/antigravity-mitm	Estado do proxy MITM do Antigravity (a ferramenta CLI "antigravity-mitm")
POST	/api/cli-tools/antigravity-mitm/alias	Configurar aliases do antigravity-mitm

Autenticação: Requer uma sessão de gestão.

---

Competências de Agentes

Faça a gestão das competências de agentes de IA (semelhantes aos GPTs personalizados da OpenAI, mas destinadas a agentes).

Método	Caminho	Descrição
GET	/api/agent-skills	Listar todas as competências de agentes (incorporadas + personalizadas)
GET	/api/agent-skills/[id]	Obter uma competência de agente específica
POST	/api/agent-skills	Criar uma competência de agente personalizada — corpo: {name, description, prompt, model?, temperature?}
PUT	/api/agent-skills/[id]	Atualizar uma competência de agente personalizada
DELETE	/api/agent-skills/[id]	Eliminar uma competência de agente personalizada
GET	/api/agent-skills/[id]/raw	Obter o prompt e os metadados em bruto (sem execução)
POST	/api/agent-skills/generate	Gerar através de IA uma nova competência a partir de uma descrição em linguagem natural

Autenticação: Requer uma sessão de gestão ou uma chave de API com âmbito de gestão.

---

Gestão da Cache

Faça a gestão da cache semântica e da cache de raciocínio.

Método	Caminho	Descrição
GET	/api/cache	Visão geral da cache: total de entradas, taxa de acertos, tamanho no disco
GET	/api/cache/entries	Listar entradas em cache (com paginação)
DELETE	/api/cache/entries	Eliminar entradas da cache (filtrar por parâmetros de consulta)
GET	/api/cache/stats	Estatísticas detalhadas da cache (por fornecedor, por modelo)
GET	/api/cache/reasoning	Estado da cache de raciocínio (para repetição do raciocínio)
DELETE	/api/cache/reasoning	Limpar a cache de raciocínio — parâmetros de consulta: ?toolCallId=<id> (individual), ?provider=<p> ou nenhum (todas)

Autenticação: Requer uma sessão de gestão.

---

Sistema de Memória

Faça a gestão da memória persistente (FTS5 + embeddings vetoriais).

Método	Caminho	Descrição
GET	/api/memory	Listar entradas de memória (filtrar por âmbito, tipo e consulta de pesquisa)
POST	/api/memory	Criar uma nova entrada de memória — corpo: {scope, type, content, metadata?}
GET	/api/memory/[id]	Obter uma entrada de memória específica
PUT	/api/memory/[id]	Atualizar uma entrada de memória
DELETE	/api/memory/[id]	Eliminar uma entrada de memória
GET	/api/memory?q=	Pesquisar na memória (FTS5 + vetorial) — as estatísticas são incluídas na mesma resposta

Autenticação: Requer uma sessão de gestão ou uma chave de API com âmbito de gestão.

---

Webhooks

Faça a gestão das subscrições de webhooks para eventos.

Método	Caminho	Descrição
GET	/api/webhooks	Listar todas as subscrições de webhooks
POST	/api/webhooks	Criar uma subscrição de webhook — corpo: {url, events[], secret?, active?}
GET	/api/webhooks/[id]	Obter uma subscrição de webhook específica
PUT	/api/webhooks/[id]	Atualizar uma subscrição de webhook
DELETE	/api/webhooks/[id]	Eliminar uma subscrição de webhook
GET	/api/webhooks/[id]/deliveries	Listar o histórico de entregas de um webhook (registo de sucessos/falhas)
POST	/api/webhooks/[id]/test	Enviar um evento de teste para um webhook

Autenticação: Requer uma sessão de gestão.

Consulte Infraestrutura de Webhooks para ver todos os tipos de eventos.

---

Framework de Skills

Gerir Skills (o framework de extensões com capacidade de agente).

Método	Caminho	Descrição
GET	/api/skills	Listar todas as skills instaladas (integradas + personalizadas)
POST	/api/skills/install	Instalar uma skill a partir de um caminho local ou URL
DELETE	/api/skills/[id]	Desinstalar uma skill
PUT	/api/skills/[id]	Ativar ou desativar uma skill — corpo: {enabled?: boolean, mode?: "on" | "off" | "auto"}
POST	/api/skills/executions	Executar uma skill — corpo: {skillName, apiKeyId, input?, sessionId?}
GET	/api/skills/executions	Listar o histórico de execuções de todas as skills (filtrar por ?apiKeyId=)

Autenticação: Requer uma sessão de gestão ou uma chave de API com âmbito de gestão.

Consulte Framework de Skills para obter todos os detalhes.

---

Plugins

Gerir plugins do OmniRoute (extensões de terceiros).

Método	Caminho	Descrição
GET	/api/plugins	Listar os plugins instalados
POST	/api/plugins/marketplace/install	Instalar um plugin a partir do marketplace
DELETE	/api/plugins/[name]	Desinstalar um plugin
POST	/api/plugins/[name]/activate	Ativar um plugin
POST	/api/plugins/[name]/deactivate	Desativar um plugin
GET	/api/plugins/[name]/config	Obter a configuração do plugin
PUT	/api/plugins/[name]/config	Atualizar a configuração do plugin

Autenticação: Requer uma sessão de gestão.

Consulte Framework de Plugins para obter todos os detalhes.

---

Encaminhamento Sombra

A comparação sombra/A-B de fornecedores não constitui uma superfície REST autónoma — é configurada através do encaminhamento combinado (consulte Combinação Automática). As métricas de comparação por combinação são disponibilizadas por GET /api/combos/metrics.

---

Barreiras de Proteção

Inspecionar as barreiras de proteção em tempo de execução (deteção de PII, deteção de injeção de prompts, intermediação de visão). As barreiras de proteção são executadas em todos os pedidos; a exclusão por chamada é efetuada através do cabeçalho de pedido x-omniroute-disabled-guardrails — não existe uma interface persistente para as ativar/desativar.

Método	Caminho	Descrição
GET	/api/guardrails	Listar as barreiras de proteção registadas e o respetivo estado (nome/ativação/prioridade)
POST	/api/guardrails/test	Executar uma simulação do pipeline anterior à chamada com uma entrada de exemplo — corpo: {input, disabledGuardrails?}

Autenticação: Requer uma sessão de gestão.

Consulte Segurança > Barreiras de Proteção para obter todos os detalhes.

---

---

Autenticação

Consulte Autenticação de gestão para obter informações sobre as quatro famílias de credenciais (sessão do painel, token da CLI local, Token de Acesso oma_live_…, chave de API com âmbito de gestão) e como diferem das chaves de inferência.

• As rotas do painel (/dashboard/*) utilizam o cookie auth_token
• O início de sessão utiliza o hash da palavra-passe guardada; como alternativa, utiliza INITIAL_PASSWORD
• requireLogin pode ser ativado ou desativado através de /api/settings/require-login
• As rotas /v1/* podem exigir opcionalmente uma chave de API Bearer quando REQUIRE_API_KEY=true
• Nesta referência, «token de gestão» / «chave de API com âmbito de gestão» significa uma das famílias descritas nesse guia — não um tipo de segredo adicional indefinido

Alteração incompatível (v3.8.0) — /api/v1/agents/tasks/* e os endpoints de gestão do período de espera exigem agora autenticação de gestão (cookie auth_token do painel ou uma chave de API com âmbito de gestão). Os clientes que anteriormente chamavam estas rotas sem autenticação receberão 401 Unauthorized. Consulte o commit 588a0333 (fix(auth): require management auth for agent and cooldown APIs).