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

API Reference (Português (Brasil))

🌐 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 · 🇷🇴 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 da API do OmniRoute. Ela abrange a interface pública /v1 e os endpoints de gerenciamento mais utilizados; o arquivo legível por máquina docs/openapi.yaml e a árvore de rotas em src/app/api/ são as fontes completas.

---

Sumário

• Conclusões de Chat
• Locações Exclusivas de Sessões Gerenciadas
• Embeddings
• Geração de Imagens
• OCR de Documentos
• Listar Modelos
• Manifesto de Plugin de Provedor
• Endpoints de Compatibilidade
• API de Arquivos
• API de Lotes
• API de Pesquisa
• Streaming via WebSocket
• Relatórios de Cotas e Problemas
• Cache Semântico
• Painel e Gerenciamento
• Gerenciamento de Combos
• Webhooks
• Chaves Registradas (Gerenciamento Automático)
• Protocolo de Agentes
• Proxies de Gerenciamento
• Resiliência (estendida)
• Habilidades
• Memória
• Servidor MCP
• Servidor A2A
• Nuvem, Avaliações e Análise
• Processamento de Requisições
• 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": "Escreva uma função para..."}
  ],
  "stream": true
}

Cabeçalhos Personalizados

Cabeçalho	Direção	Descrição
X-OmniRoute-No-Cache	Requisição	Defina como true para ignorar o cache
x-omniroute-no-memory	Requisição	Defina como true para ignorar a injeção de memória + habilidades nesta requisição (reflete no-cache; evita a sobrecarga de tokens/custo por chamada)
X-OmniRoute-Progress	Requisição	Defina como true para eventos de progresso
X-Session-Id	Requisição	Chave de sessão persistente para afinidade de sessão externa
x_session_id	Requisição	A variante com sublinhado também é aceita (HTTP direto)
X-OmniRoute-Session-Id	Requisição	Tag de sessão/conversa fornecida pelo chamador (também alimenta a memória). Quando presente, é persistida literalmente em call_logs.session_tag para atribuição de custos por sessão (#8249) — nunca é sintetizada quando ausente
Idempotency-Key	Requisição	Chave de desduplicação (janela de 5 s)
X-Request-Id	Requisição	Chave de desduplicação alternativa
X-OmniRoute-Cache	Resposta	HIT ou MISS (sem streaming)
X-OmniRoute-Idempotent	Resposta	true se desduplicada
X-OmniRoute-Progress	Resposta	enabled se o acompanhamento de progresso estiver ativado
X-OmniRoute-Session-Id	Resposta	ID de sessão efetivo usado pelo OmniRoute
X-OmniRoute-Request-Id	Resposta	ID de correlação da requisição (quando conhecido)
X-OmniRoute-Version	Resposta	Versão da build do OmniRoute (sempre presente)
X-OmniRoute-Cost-Saved	Resposta	Valor em USD que o cache evitou em um HIT (apenas acertos de cache)
X-OmniRoute-Decision	Resposta	Rastreamento de roteamento: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> é a estratégia do combo ou single para uma requisição sem combo) — sempre presente nas respostas de conclusão

Observação sobre o Nginx: se você depende de cabeçalhos com sublinhado (por exemplo, x_session_id), habilite 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 operações gratuitas/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 (somente quando > 0), além de X-OmniRoute-Request-Id e X-OmniRoute-Version. Eles são emitidos por conclusões de chat, /v1/responses, /v1/messages e pelos endpoints de mídia — /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/rerank, /v1/videos/generations, /v1/music/generations e /v1/moderations (sempre com custo 0). O custo de mídia é calculado por modalidade (por imagem, por segundo, por caractere, por unidade de pesquisa) quando os preços estão disponíveis; caso contrário, é 0 (fail-open).

Semântica de custo em acertos de cache: em um HIT do cache semântico (X-OmniRoute-Cache-Hit: true), nenhuma chamada upstream é feita, portanto, X-OmniRoute-Response-Cost é 0.0000000000 (o custo incremental de atender ao acerto). O custo original/que teria sido incorrido é informado separadamente em X-OmniRoute-Cost-Saved. Os consumidores de faturamento devem somar X-OmniRoute-Response-Cost (acertos não têm custo); as análises de cache podem agregar X-OmniRoute-Cost-Saved.

Concessões exclusivas de sessão gerenciada

A concessão exclusiva de sessão gerenciada é um contrato de roteamento opcional e neutro em relação ao cliente: um proprietário ativo mantém uma conexão OmniRoute elegível. Ela não concede um modelo, não exige OAuth, não identifica um cliente específico e não exige um provedor específico.

A chave de API usada na autenticação deve ter o escopo lease:exclusive e uma lista allowedConnections explícita e não vazia. O limite de mutação do banco de dados exige ambos os campos em conjunto na criação da chave e em 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 liberação expõem timestamps, state e o valor positivo exato de generation, mas nunca a conexão selecionada ou as credenciais. A renovação e a liberaçã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 exibição que preservam a privacidade para sua vinculaçã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"
  }
}

Essa ação de status opcional é protegida pelo proprietário opaco, pela chave de API gerenciada autenticada e pela geração ativa exata em uma única transação de banco de dados. displayName é apenas o nome configurado da conexão após a remoção de espaços em branco nas extremidades; ele é null quando não existe um nome configurado seguro. O OmniRoute nunca substitui esse valor por um e-mail ou por uma identidade de conta gerada. O valor do provedor é um rótulo de exibição não confidencial e nunca um identificador gerado de provedor compatível. Credenciais, tokens, cookies, IDs brutos de conexão ou de chave de API, hashes de proprietário, segredos de fencing e dados internos de roteamento são excluídos.

Consultas com chave incorreta, proprietário incorreto, geração obsoleta, ausente, expirada, liberada ou invalidada retornam o mesmo erro 409 LEASE_FENCE_STALE, sem metadados da conexão. Um cliente que recebeu a resposta de espera por capacidade não tem nenhuma vinculação ativa para inspecionar. Quando o roteamento faz a transição de uma concessão ativa, a mesma geração permanece válida, e o status retorna atomicamente a nova vinculação, nunca a antiga. Os clientes existentes permanecem inalterados porque as respostas de aquisição, renovação, liberação e espera mantêm seus formatos anteriores.

Este contrato do servidor não altera o /status padrão do OpenAI Codex. Atualmente, o Codex padrão informa seu provedor de modelo e o estado interno de autenticação/conta, mas não renderiza metadados arbitrários de contas de provedores personalizados; uma integração futura do cliente deverá chamar essa ação e decidir como exibir connection.displayName.

Cada solicitação de inferência gerenciada fornece então ambos os cabeçalhos de controle:

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

O proprietário exato, a geração, a conexão ativa e a chave de API autenticada são validados por fencing imediatamente antes de cada tentativa upstream compatível. Reutilizar o proprietário e a geração com outra chave falha mesmo quando essa chave permite a mesma conexão. Os proprietários brutos não são persistidos, registrados em logs, mantidos no snapshot da solicitação nem encaminhados ao upstream.

A contenção temporária retorna 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
}

Essa resposta significa apenas que o conjunto elegível comum não estava vazio e que todos os candidatos livres estavam mantidos por uma concessão ativa de outro proprietário. Modelos/provedores não compatíveis, incompatibilidade de política, cooldown, cota, integridade e outras falhas comuns de elegibilidade mantêm suas respostas OmniRoute existentes.

x-omniroute-compression

Substituição por solicitação do plano de compactação. Maior precedência — prevalece sobre a substituição da combinação de roteamento, o perfil ativo, o acionamento automático e o padrão do painel. Valores:

Valor	Efeito
off	Sem compactação para esta solicitação.
default	O perfil padrão derivado do painel (ignora o perfil ativo).
engine:<id>	Um único mecanismo quando habilitado, por exemplo, engine:rtk.
<combo>	Uma combinação nomeada, comparada primeiro pelo nome (sem diferenciar maiúsculas de minúsculas) e depois pelo ID.

Observações:

• Valores desconhecidos são ignorados (a solicitação nunca é rejeitada); a resolução prossegue para a precedência normal dos operadores.
• Se várias combinações compartilharem um 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 seu ID.
• O controle mestre de compactação é uma barreira rígida: quando a compactação está desabilitada globalmente, esse cabeçalho não pode habilitá-la.

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

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

em que <source> é um dentre 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"
}

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

Os IDs do catálogo seguem o formato provider/model (exemplo: jina-ai/jina-embeddings-v5-omni-small). IDs de modelos Jina sem o provedor que aparecem no registro (por exemplo, jina-embeddings-v5-text-small, jina-reranker-v3.5) também são resolvidos. As operações de embedding/rerank/classify/segment da Jina usam primeiro as credenciais jina-ai do painel; JINA_AI_API_KEY é usada como alternativa somente quando não existe uma chave no painel. O cartão jina-reader é exclusivo para o Reader / r.jina.ai (POST /v1/web/fetch) e nunca fornece embeddings nem rerank.

Os modelos do registro que anunciam suporte multimodal também aceitam até 32 itens estruturados neutros em relação ao provedor. Os tipos de item de mídia são text, image, audio, video e document. O source da mídia pode ser {"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 nativos EmbeddingsV5Request da Jina e os encaminha 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 uma URL HTTPS pública, um URI data: ou base64 bruto. O OmniRoute não converte esses objetos em strings nem busca URLs nativas de imagens — a própria Jina recupera a mídia pública. Campos adicionais da Jina (task, normalized, truncate, embedding_type) são encaminhados. SKUs da Jina exclusivos para texto ainda rejeitam documentos que não sejam de texto.

Limites de segurança e transporte:

• URLs de mídia remota devem usar HTTPS público. Itens canônicos {type,source:url} são buscados no lado do servidor (revalidação de redirecionamento, tempo limite, limites de tamanho, DNS público, fixação de conexão) e incorporados antes da chamada ao provedor. Itens nativos da Jina {image:"https://..."} são encaminhados como estão após a mesma verificação de HTTPS público; a Jina busca a URL.
• Mídia base64 embutida é limitada a 8 MiB decodificados por item e 16 MiB decodificados em toda a solicitação.

Tradução para o provedor (itens canônicos nunca são encaminhados sem alterações):

• Modelos multimodais da Jina: cada item de nível superior se torna um objeto com chave de modalidade (text / image / audio / video / pdf) usando URIs de dados para mídia embutida; um vetor por item de nível superior.
• Família Gemini Embedding 2: um array de nível superior se torna uma única solicitação nativa models/{model}:embedContent com content.parts (text ou inline_data).
• 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"
}

Combinações não compatíveis de modelo/modalidade retornam HTTP 400 em vez de converter o item. Campos de extensão que não sejam de entrada em solicitações legadas de string/token continuam sendo repassados sem alterações.

# Listar todos os modelos de embedding
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": "A beautiful sunset over mountains",
  "size": "1024x1024"
}

Provedores 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 provedor de OCR por meio de um prefixo provider/model; um ID de modelo sem prefixo (por exemplo, mistral-ocr-latest) é resolvido para seu provedor registrado, e, quando model é omitido, o padrão é Mistral (mistral-ocr-latest). Provedores registrados (open-sse/config/ocrRegistry.ts):

ID do provedor	ID do modelo	Valor de model	Observações
mistral	mistral-ocr-latest	mistral/mistral-ocr-latest (ou apenas mistral-ocr-latest)	Síncrono — a resposta é retornada diretamente da única chamada ao serviço upstream.
azure-document-intelligence	prebuilt-read	azure-document-intelligence/prebuilt-read	Upstream assíncrono (analyze + sondagem) — veja abaixo.
vertex-deepseek-ocr	deepseek-ocr-maas	vertex-deepseek-ocr/deepseek-ocr-maas	Síncrono, por meio do endpoint de parceiro openapi/chat/completions do Vertex AI — veja abaixo sobre autenticação/URL.

Todos os três provedores respondem com o mesmo corpo no formato do Mistral:

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

Fluxo de sondagem do Azure Document Intelligence

A API analyze do Azure Document Intelligence é assíncrona: a solicitação inicial retorna um cabeçalho Operation-Location em vez de um corpo, e o resultado deve ser consultado periodicamente. O manipulador (open-sse/handlers/ocr.ts) consulta essa URL a cada segundo por até 30 tentativas, falha imediatamente (sem continuar a sondagem) em caso de uma resposta de sondagem que não seja ok ou de um status "failed", e retorna 504 se a operação ainda estiver em execução após o esgotamento do limite de tentativas. A resposta final do Azure é normalizada para o mesmo formato pages/markdown usado pelo Mistral antes de ser retornada ao chamador, portanto o código do cliente não precisa tratar o provedor como um caso especial.

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

vertex-deepseek-ocr reutiliza a mesma autenticação do Vertex AI que o OmniRoute já oferece para tráfego de chat/imagens (open-sse/executors/vertex.ts): a chave de API da conexão é uma credencial JSON de Service Account (trocada por um token de acesso OAuth de curta duração por meio do fluxo JWT bearer) ou um token de acesso OAuth já emitido, usado sem alterações. A URL do endpoint upstream é o endpoint genérico de parceiro openapi/chat/completions do Vertex, construído com base no projeto e na região da conexão — valores explícitos de providerSpecificData.project/providerSpecificData.region sempre têm prioridade; caso contrário, o projeto é derivado do project_id no JSON da Service Account, e o padrão da regiã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

→ Retorna todos os modelos de chat, embedding e imagem + combinações no formato da OpenAI

Prefixos de ID de modelo (?prefix=)

A maioria dos modelos é anunciada sob um prefixo de provedor. O prefixo recebido é controlado pela feature flag MODELS_CATALOG_PREFIX_MODE e pode ser substituído por requisição com um parâmetro de consulta — útil para um cliente que deseja uma lista limpa sem alterar a configuração global do servidor para todos os demais:

GET /v1/models?prefix=alias        # um ID por modelo — o prefixo curto do alias
GET /v1/models?prefix=dual         # ambas as formas (padrão do servidor)
GET /v1/models?prefix=canonical    # somente o prefixo completo do ID do provedor

Modo	Emite	Observações
dual	cc/claude-sonnet-4-6 e claude/claude-sonnet-4-6	Padrão. Ambos os IDs são encaminhados para o mesmo modelo; mantidos para que as configurações de clientes que fixaram uma das formas continuem funcionando. Aproximadamente dobra o catálogo.
alias	cc/claude-sonnet-4-6	Uma entrada por modelo. Provedores sem um alias distinto ainda emitem sua entrada, portanto nada é perdido.
canonical	claude/claude-sonnet-4-6	Uma entrada por modelo sob o prefixo completo do ID do provedor. Provedores sem um alias distinto (por exemplo, antigravity/…, agy/…) também emitem aqui seu único ID, portanto nada é perdido.

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

Clientes que renderizam um seletor de modelos devem solicitar ?prefix=alias — é isso que a extensão OmniCopilot para VS Code faz.

Variantes de modelo 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>

Selecionar esse ID (por exemplo, em uma configuração do Claude Code que sempre anexa um bloco thinking) faz com que ele seja resolvido de volta para o <provider>/<model> real com o raciocínio suprimido — thinking:{type:"disabled"} no endpoint /v1/messages, ou com os campos reasoning/reasoning_effort removidos no endpoint /v1/chat/completions. A variante é listada somente para modelos da família Claude que oferecem suporte a raciocínio e respeitam disabled (portanto, por exemplo, modelos exclusivamente adaptativos que rejeitam disabled são excluídos). Os operadores podem ativar ou desativar à força a variante por modelo por meio de ModelSpec.noThinkingAlias.

---

Manifesto do Plugin de Provedor

GET /api/v1/provider-plugin-manifest

Retorna o manifesto JSON-safe dos plugins de provedores usado pelo Bifrost, CLIProxyAPI e por futuros roteadores sidecar. A resposta é gerada a partir do registro de provedores TypeScript e exclui intencionalmente segredos de clientes OAuth, resolução de ambiente em tempo de execução, funções executoras, cabeçalhos de requisição e dados de contas.

Use este endpoint quando um sidecar for executado fora do processo e não puder 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 no estilo OpenAI
POST	/v1/music/generations	Geração de música no estilo OpenAI
POST	/v1/audio/transcriptions	OpenAI Audio (STT)
POST	/v1/audio/speech	OpenAI TTS (retorna corpo de áudio)
POST	/v1/rerank	Rerank no 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 tokenizado do OpenAI
POST	/api/v1/vscode/{token}/responses	Alias tokenizado do OpenAI Responses
POST	/api/v1/vscode/{token}/api/chat	Alias tokenizado do Ollama
GET	/api/v1/vscode/{token}/api/tags	Alias tokenizado das tags do Ollama

Todas as rotas POST seguem o mesmo formato: Bearer your-api-key + corpo JSON validado pelo Zod (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema etc.; consulte src/shared/validation/schemas.ts). Um status 4xx é retornado em caso de falha na validação do esquema.

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

# Rerank
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 provedor: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

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

# TTS — retorna 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 prefixado pelo provedor)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

Rotas Dedicadas de Provedores

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

O prefixo do provedor é adicionado automaticamente caso esteja ausente. Modelos incompatíveis retornam 400.

---

API de Arquivos

Endpoint de arquivos compatível com a OpenAI para entrada/saída em lote e uploads com finalidade específica.

Método	Caminho	Descrição
POST	/v1/files	Faz upload de um arquivo (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — máximo de 512 MiB
GET	/v1/files	Lista os arquivos da chave de API autenticada
GET	/v1/files/[id]	Recupera os metadados de um arquivo
DELETE	/v1/files/[id]	Exclui um arquivo
GET	/v1/files/[id]/content	Transmite o corpo bruto do arquivo de volta

Autenticação: Chave de API Bearer — os arquivos têm escopo por chave de API via getApiKeyRequestScope. Uma chave vê, baixa e exclui apenas seus próprios arquivos; uma sessão do painel sem uma chave lê a instância inteira; um arquivo sem proprietário (upload anônimo ou de sessão do painel) tem o acesso negado para todos os chamadores que não sejam da sessão. GET /v1/files rejeita um chamador anônimo — e uma chave fornecida que não seja resolvida — com 401, mesmo quando REQUIRE_API_KEY=false, em vez de listar os arquivos de todos os locatários (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	Cria um lote — corpo validado por v1BatchCreateSchema (input_file_id, endpoint, completion_window)
GET	/v1/batches	Lista os lotes
GET	/v1/batches/[id]	Recupera o status do lote + request_counts
DELETE	/v1/batches/[id]	Exclui um lote concluído/com falha
POST	/v1/batches/[id]/cancel	Cancela um lote em andamento

Autenticação: Chave de API Bearer. Os lotes têm escopo por chave de API segundo a mesma regra tripla dos arquivos: somente a própria chave, sessão do painel em toda a instância, registros com proprietário nulo negados a todos os chamadores que não sejam da sessão (recuperação, exclusão, cancelamento e verificação de input_file_id na criação). GET /v1/batches rejeita um chamador anônimo com 401, mesmo quando REQUIRE_API_KEY=false.

---

API de Busca

Abstração de provedores de busca na web (Tavily, Brave, Exa, Serper etc.).

Método	Caminho	Descrição
GET	/v1/search	Lista os provedores de busca configurados e seus recursos
POST	/v1/search	Executa uma consulta de busca — corpo validado por v1SearchSchema, com suporte a cache/coalescência
GET	/v1/search/analytics	Estatísticas de acertos/latência/cache por provedor

Autenticação: chave de API Bearer (extractApiKey + isValidApiKey). A política de busca é aplicada por meio de enforceApiKeyPolicy.

---

API de Busca de Conteúdo Web

Extrai conteúdo de uma URL por meio de um provedor configurado de busca de conteúdo web (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

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

Autenticação: chave de API Bearer (extractApiKey + isValidApiKey). A política é aplicada por meio de enforceApiKeyPolicy.

Fallback ciente de cotas (#8297): quando nenhum provider explícito é informado, o pool (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) é percorrido em ordem fixa de prioridade (preenchimento prioritário) — um provedor configurado, mas com limite de taxa atingido, é ignorado em vez de encerrar imediatamente a solicitação, e uma falha recuperável/de cota no serviço upstream (HTTP 429 sempre; 402/403 para níveis gratuitos com cota do Firecrawl/Tavily/TinyFish — não para o Jina Reader e nunca para uma solicitação inválida simples com status 400) passa para o próximo provedor ainda não tentado e com credenciais disponíveis no momento da solicitação. Quando todos os provedores do pool estão esgotados, o endpoint retorna um único 429 (com um cabeçalho Retry-After) em vez do 400 genérico anterior. Quando um provider explícito é solicitado, não há fallback silencioso — um provedor explícito com limite de taxa atingido ou com falha expõe seu próprio erro (429 se o limite de taxa tiver sido atingido; caso contrário, o status do serviço upstream).

---

Streaming via WebSocket

GET /v1/ws?handshake=1

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

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

API Responses via WebSocket (somente codex)

# Mesmo host:porta da API HTTP (padrão 20128); faça o upgrade da conexão:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (ou: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

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

Um proxy da API Responses via WebSocket está conectado exclusivamente ao codex (backend do ChatGPT). Ele escuta na mesma porta que a API/o painel nos caminhos /v1/responses, /responses e /api/v1/responses. No primeiro frame response.create, ele autentica e prepara por meio da ponte interna codex-responses-ws, seleciona uma conexão OAuth do codex e cria um túnel para wss://chatgpt.com/backend-api/codex/responses por meio do transporte wreq-js. Modelos que não sejam codex são rejeitados (codex_ws_provider_required). Para roteamento por compartilhamento de cota, use 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) deve ser o ponto de entrada ativo (e é, por padrão, quando app/server-ws.mjs existe).

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

A Codex CLI da OpenAI valida o nome do modelo no lado do cliente quando supports_websockets = true e rejeita IDs com prefixo de provedor, 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 é exclusiva para codex, portanto, antes de criar o túnel para o serviço upstream, ela resolve novamente um ID simples como um modelo codex (resolveCodexWsModelInfo) — embora um gpt-5.5 simples fosse, de outra forma, roteado para outro provedor via HTTP.

Configuração da Codex CLI da OpenAI

Direcione a Codex CLI para o OmniRoute adicionando um provedor personalizado com suporte a WebSocket ao ~/.codex/config.toml (use 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; a URL do WS é derivada (use https/wss em produção)
wire_api = "responses"                    # único valor compatível desde fevereiro de 2026
supports_websockets = true                # habilita o transporte Responses-over-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 faz o upgrade de base_url + /responses para um WebSocket, e o OmniRoute cria um túnel até a conexão OAuth do codex selecionada. Validado de ponta a ponta com o servidor local: o ChatGPT retorna codex.rate_limits + response.created e transmite a conclusão em streaming.

---

Relatórios de cotas e problemas

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

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

---

Uso por autoatendimento (/api/usage/om-usage)

Qualquer chave de API pode consultar seu próprio uso e suas cotas — sem autenticação de gerenciamento. Este é o endpoint que um cliente (CLI, o painel do OmniCopilot) usa para mostrar os gastos ao titular de uma chave.

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

# Formato estruturado — o que uma interface de usuário consome
curl -H "Authorization: Bearer <sua-chave-de-api>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

A chave deve ter allowUsageCommand habilitado (desabilitado por padrão — o gerenciador de chaves de API do painel alterna essa opção por chave). Sem isso, o endpoint responde com 403.

?format=json retorna uma estrutura discriminada para que o chamador nunca leia um campo de dados de uma recusa. Em caso de sucesso:

{
  "allowed": true,
  // presente somente quando a chave optou por limites de uso por chave (USD diário/semanal):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // o instantâneo de cotas do provedor selecionado, ou null quando ainda não há nada em cache:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // o instantâneo de cada conexão, para que uma interface possa renderizar vários provedores lado a lado:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

Em caso de recusa (401 para chave inválida / 403 para acesso não permitido), a mesma rota retorna { "allowed": false, "error": { "message": "…" } } — um personal/provider presente, porém vazio (chave permitida, mas sem informações obtidas ainda), representa um estado diferente de uma recusa, e somente o formato JSON faz essa distinção.

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

---

Cache semântico

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

# Limpar todos os 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 ACERTO no cache semântico fornece a resposta a partir do cache sem uma chamada ao serviço upstream, portanto, o X-OmniRoute-Response-Latency informado é próximo de zero (independentemente da latência original do serviço upstream). Clientes sensíveis à latência (benchmarking, monitoramento de p50/p99) devem verificar o cabeçalho de resposta X-OmniRoute-Cache-Latency:

Valor	Significado
synthetic	Resposta fornecida pelo cache; a latência não representa o tempo real upstream
(ausente)	Resposta proveniente de uma chamada real ao serviço upstream

Desvio do cache por chave

As chaves de API podem optar por não realizar leituras do cache semântico por meio de cacheDefaultMode:

Valor	Comportamento
legacy	Comportamento normal do cache (padrão)
bypass	Ignora completamente a consulta ao cache; sempre acessa upstream

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

{ "cacheDefaultMode": "bypass" }

Desvio por solicitação

Qualquer solicitação pode ignorar o cache, independentemente das configurações da chave:

X-OmniRoute-No-Cache: true

---

Dashboard e Gerenciamento

As rotas de gerenciamento (/api/*, exceto autenticação/login públicos) não são autorizadas por chaves comuns da API de inferência. Famílias de credenciais, escopos e exemplos com curl: Autenticação de Gerenciamento.

Autenticação

Endpoint	Método	Descrição
/api/auth/login	POST	Login
/api/auth/logout	POST	Logout
/api/settings/require-login	GET/PUT	Ativar/desativar exigência de login

Gerenciamento de Provedores

Endpoint	Método	Descrição
/api/providers	GET/POST	Listar/criar provedores
/api/providers/[id]	GET/PUT/DELETE	Gerenciar um provedor
/api/providers/[id]/test	POST	Testar a conexão do provedor
/api/providers/[id]/models	GET	Listar os modelos do provedor
/api/providers/validate	POST	Validar a configuração do provedor
/api/providers/bulk	POST	Adicionar chaves de API em massa para UM provedor
/api/providers/import	POST	Importar uma LISTA heterogênea de provedores de um arquivo CSV/JSON analisado (#6836); resultados de falha parcial por linha
/api/provider-nodes*	Vários	Gerenciamento de nós de provedores
/api/provider-models	GET/POST/PATCH/DELETE	Modelos personalizados (adicionar, atualizar, ocultar/exibir, excluir)

Fluxos OAuth

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

Roteamento e Configuração

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

Uso e Análises

Endpoint	Método	Descrição
/api/usage/history	GET	Histórico de uso
/api/usage/logs	GET	Logs de uso
/api/usage/request-logs	GET	Logs no nível da solicitação
/api/usage/[connectionId]	GET	Uso por conexão
/api/usage/token-limits	GET/POST/DELETE	Orçamentos de limite de tokens por chave de API
/api/usage/model-latency-stats	GET	Agregação contínua de latência por provedor/modelo (média/p50/p95/p99, taxa de sucesso); filtros: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health	GET	Resumo da integridade do cache de prompts em call_logs — proporção entre gravações e leituras, distribuição p50/p90/p99 do tamanho das gravações, concentração de gravações intensas, divisão por modelo e um veredito healthy/degraded/thrash/no-data; parâmetros de consulta range (1h|24h|7d|30d, padrão 24h) e model opcional (#8827)

Configurações

Endpoint	Método	Descrição
/api/settings	GET/PUT/PATCH	Configurações gerais
/api/settings/proxy	GET/PUT	Configuração do proxy de rede
/api/settings/proxy/test	POST	Testar a conexão do proxy
/api/settings/ip-filter	GET/PUT	Lista de permissões/bloqueios de IPs
/api/settings/thinking-budget	GET/PUT	Modo de reescrita da solicitação de pensamento/raciocínio (encaminhamento / remoção automática / personalizado / adaptativo). Independente da compactação. Consulte THINKING_BUDGET.md.
/api/settings/system-prompt	GET/PUT	Prompt de sistema global
/api/settings/compression	GET/PUT	Configuração global de compactação
/api/settings/purge-request-history	POST	Limpar as linhas do log de solicitações e os artefatos locais do log de chamadas

Contexto e compactação

Endpoint	Método	Descrição
/api/compression/preview	POST	Visualizar compressão off/lite/standard/aggressive/ultra/RTK/stacked
/api/compression/language-packs	GET	Listar pacotes de idiomas disponíveis do Caveman
/api/compression/rules	GET	Listar metadados das regras do Caveman
/api/context/caveman/config	GET/PUT	Alias das configurações específicas do Caveman
/api/context/rtk/config	GET/PUT	Configurações específicas do RTK, incluindo filtros personalizados e retenção da saída bruta
/api/context/rtk/filters	GET	Catálogo de filtros do RTK e diagnósticos de filtros personalizados
/api/context/rtk/test	POST	Executar visualização prévia/teste do RTK com uma carga de texto
/api/context/rtk/raw-output/[id]	GET	Ler a saída bruta anonimizada retida pelo ID do ponteiro
/api/context/combos	GET/POST	Listar/criar combinações de compressão
/api/context/combos/[id]	GET/PUT/DELETE	Detalhar/atualizar/excluir combinação de compressão
/api/context/combos/[id]/assignments	GET/PUT	Atribuir combinações de compressão a combinações de roteamento
/api/context/analytics	GET	Alias das análises de compressão

Monitoramento

Endpoint	Método	Descrição
/api/sessions	GET	Rastreamento de sessões ativas
/api/rate-limits	GET	Limites de taxa por conta
/api/monitoring/health	GET	Verificação de integridade + resumo dos provedores (catalogCount, configuredCount, activeCount, monitoredCount). A visualização de gerenciamento inclui credentialHealth: valores escalares do cache de sondagens, failedConnections quando failed>0 e staleDbNonOkCount (test_status persistente do SQLite, não o medidor). Consulte MONITORING_GUIDE.md.
/api/cache/stats	GET/DELETE	Estatísticas do cache / limpar
/api/modality-bridge/stats	GET	attempts em memória, sucessos/bridged, falhas, acertos de cache, totalLatencyMs, latencySamples, averageLatencyMs baseado no número de amostras e horário do último uso (redefinidos ao reiniciar; autenticação de gerenciamento)
/api/modality-bridge/video/runtime	GET	Verificação rigorosa de loopback confiável antes da autenticação/sondagem de gerenciamento; disponibilidade e versões sanitizadas do FFmpeg/ffprobe (no-store)
/api/modality-bridge/video/extract	POST	Broker interno autenticado de bytes por loopback confiável; 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 upload

Backup e exportação/importação

Endpoint	Método	Descrição
/api/db-backups	GET	Lista os backups disponíveis
/api/db-backups	PUT	Cria um backup manual
/api/db-backups	POST	Restaura a partir de um backup específico
/api/db-backups/export	GET	Baixa o banco de dados como arquivo .sqlite
/api/db-backups/import	POST	Envia um arquivo .sqlite para substituir o banco de dados
/api/db-backups/exportAll	GET	Baixa o backup completo como arquivo .tar.gz

Sincronização com a nuvem

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

Túneis

Endpoint	Método	Descrição
/api/tunnels/cloudflared	GET	Lê o status de instalação/execução do Cloudflare Quick Tunnel para o painel
/api/tunnels/cloudflared	POST	Habilita ou desabilita o Cloudflare Quick Tunnel (action=enable/disable)
/api/tunnels/ngrok	GET	Lê o status de execução do ngrok Tunnel para o painel
/api/tunnels/ngrok	POST	Habilita ou desabilita o ngrok Tunnel (action=enable/disable)

Ferramentas de CLI

Endpoint	Método	Descrição
/api/cli-tools/claude-settings	GET	Status da CLI Claude
/api/cli-tools/codex-settings	GET	Status da CLI Codex
/api/cli-tools/droid-settings	GET	Status da CLI Droid
/api/cli-tools/openclaw-settings	GET	Status da CLI OpenClaw
/api/cli-tools/runtime/[toolId]	GET	Ambiente de execução genérico da CLI

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

Agentes ACP

Endpoint	Método	Descrição
/api/acp/agents	GET	Lista todos os agentes detectados (integrados + personalizados) com o status
/api/acp/agents	POST	Adiciona um agente personalizado ou atualiza o cache de detecção
/api/acp/agents	DELETE	Remove um agente personalizado pelo 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	Obtém/atualiza a fila de solicitações, o período de espera da conexão, o disjuntor do provedor e as configurações de espera
/api/resilience/reset	POST	Redefine os disjuntores dos provedores
/api/resilience/model-cooldowns	GET	Lista os bloqueios ativos por (provedor, conexão, modelo), ordenados pelo tempo restante
/api/resilience/model-cooldowns	DELETE	Limpa um bloqueio de modelo — corpo {provider, model} ou {all: true} para limpar tudo
/api/rate-limits	GET	Status do limite de taxa por conta
/api/rate-limit	GET	Configuração global do limite de taxa

Todas as quatro rotas /api/resilience/* exigem autenticação de gerenciamento (requireManagementAuth). Consulte Resiliência (detalhada) para obter uma explicação completa das diferenças entre o disjuntor do provedor, o período de espera da conexão e o bloqueio do modelo.

Avaliações

Endpoint	Método	Descrição
/api/evals	GET/POST	Lista conjuntos de avaliação / executa uma avaliação

Políticas

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

Conformidade

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

v1beta (compatível com Gemini)

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

Esses 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 de inicialização do aplicativo (usada na primeira execução)
/api/tags	GET	Tags de modelos compatíveis com Ollama (para clientes Ollama)
/api/restart	POST	Aciona a reinicialização normal do servidor
/api/shutdown	POST	Aciona o desligamento normal do servidor
/api/system/env/repair	POST	Repara as variáveis de ambiente do provedor OAuth

Observação: Esses endpoints são usados internamente pelo sistema ou para compatibilidade com clientes Ollama. Normalmente, eles não são chamados pelos usuários finais.

Reparo do ambiente OAuth (v3.6.1+)

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

{
  "provider": "claude-code"
}

Repara variáveis de ambiente OAuth ausentes ou corrompidas para um provedor específico. Retorna:

{
  "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 arquivos de áudio usando qualquer provedor de STT configurado. O primeiro segmento do caminho seleciona o provedor nativo (openai/…, deepgram/…). Gateways que reexportam o modelo de outro fornecedor usam um id qualificado (openrouter/deepgram/nova-3).

Requisição:

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": "Hello, this is the transcribed audio content.",
  "task": "transcribe",
  "language": "en",
  "duration": 12.5
}

Exemplos de ids de modelo: 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). Uma requisição simples para deepgram/nova-3 não usa a OpenRouter.

Formatos compatíveis: mp3, wav, m4a, flac, ogg, webm.

---

Compatibilidade com o Ollama

Para clientes que usam o formato de API do Ollama:

# Endpoint de chat (formato do Ollama)
POST /v1/api/chat

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

As requisições são convertidas automaticamente entre os formatos do Ollama e os formatos internos.

Aliases tokenizados para o VS Code / sem cabeçalho

Use estes aliases quando uma integração não puder injetar um cabeçalho Authorization e precisar que a chave de API seja incorporada à URL base.

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

# Aliases de chat no estilo da OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Aliases no estilo do 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"}]}'

Observações:

• Os aliases tokenizados reutilizam os mesmos manipuladores que /v1/* e /api/tags; os formatos das respostas permanecem idênticos.
• Prefira Authorization: Bearer ... sempre que o cliente oferecer suporte a cabeçalhos personalizados.
• Tokens baseados em URL podem aparecer em logs de proxies reversos, no histórico do navegador e em telemetria fora do OmniRoute. Trate-os como uma opção de compatibilidade, não como o modo de autenticação padrão.

---

Telemetria

# Obter o resumo da telemetria de latência (p50/p95/p99 por provedor)
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 status do orçamento de todas as chaves de 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"
}

Observações sobre o esquema (setBudgetSchema): apiKeyId é obrigatório; pelo menos um entre dailyLimitUsd, weeklyLimitUsd ou monthlyLimitUsd deve ser maior que zero. Campos opcionais: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). O formato legado {keyId, limit, period} retorna 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 caminho da solicitação: quando o uso de uma chave na janela atual atinge seu limite, as solicitações são rejeitadas com 429 Too Many Requests. Os limites podem ter como escopo um model específico, um provider ou ser aplicados globalmente à chave; quando vários limites correspondem a uma solicitação, o mais restritivo prevalece.

# Lista os limites de tokens de uma chave (inclui o uso da janela em tempo real)
GET /api/usage/token-limits?apiKeyId=key-123

# Cria ou atualiza 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
}

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

Observações 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 escopo model ou um id de provedor para o escopo provider). tokenLimit deve ser um número inteiro positivo (convertido a partir de uma string). Opcionais: id (omita para criar, forneça para atualizar), resetInterval (daily | weekly | monthly, padrão monthly), resetTime (HH:MM), enabled (padrão true). As respostas de GET enriquecem cada limite com tokensUsed, remaining, windowStart, periodStartAt e nextResetAt. Este é um endpoint da classe de gerenciamento (a autenticação é aplicada centralmente pelo pipeline de autorização).

Processamento de solicitações

1. O cliente envia uma solicitação para /v1/*
2. O manipulador da rota chama handleChat, handleEmbedding, handleAudioTranscription ou handleImageGeneration
3. O modelo é resolvido (provedor/modelo direto ou alias/combo)
4. As credenciais são selecionadas do banco de dados local com filtragem pela disponibilidade da conta
5. Para chat: handleChatCore verifica o cache semântico/de assinatura e resolve as configurações de compactação do combo
6. A compactação proativa é executada antes da tradução para o provedor quando habilitada (lite, Caveman, RTK ou empilhada)
7. O executor do provedor envia a solicitação ao serviço upstream
8. A resposta é traduzida de volta para o formato do cliente (chat) ou retornada como está (embeddings/imagens/áudio)
9. O uso, as análises de compactação e os logs de solicitações são registrados
10. O fallback é aplicado em caso de erros, de acordo com as regras do combo

Referência completa da arquitetura: ARCHITECTURE.md

---

Gerenciamento de combos

Os combos de roteamento de nível superior (já resumidos em /api/combos*) também podem ser mapeados 1:1 a partir de um padrão de id de modelo, permitindo o redirecionamento transparente de um id de modelo no estilo OpenAI para um combo.

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

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

---

Webhooks

Assinaturas de webhooks de saída para eventos do OmniRoute (conclusão de solicitações, esgotamento de cota, rotação de chaves etc.).

Método	Caminho	Descrição
GET	/api/webhooks	Lista os webhooks (os segredos são mascarados como <prefix>...)
POST	/api/webhooks	Cria um webhook — corpo: {url, events?: ["*"], secret?, description?}
GET	/api/webhooks/[id]	Recupera um webhook
PUT	/api/webhooks/[id]	Atualiza url/events/secret/description
DELETE	/api/webhooks/[id]	Remove um webhook
POST	/api/webhooks/[id]/test	Envia uma carga útil de teste para a URL do webhook e retorna o status da entrega

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

---

Chaves registradas (gerenciamento automático)

Usadas pelo subsistema de gerenciamento automático de chaves para emitir e rotacionar chaves de API em um provedor/uma conta subjacente, com cotas diárias/horárias.

Método	Caminho	Descrição
GET	/api/v1/registered-keys	Lista as chaves registradas (somente o prefixo mascarado)
POST	/api/v1/registered-keys	Emite uma nova chave registrada — corpo: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. Retorna a chave bruta uma única vez. Retorna 429 quando a solicitação é recusada por cota.
GET	/api/v1/registered-keys/[id]	Recupera os metadados de uma chave registrada (sem o material bruto)
DELETE	/api/v1/registered-keys/[id]	Revoga uma chave registrada
POST	/api/v1/registered-keys/[id]/revoke	Endpoint de revogação explícita (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 nuvem (Claude Code, Codex Cloud, OpenHands etc.) executadas remotamente em nome dos usuários do OmniRoute.

Método	Caminho	Descrição
GET	/api/v1/agents/tasks	Lista tarefas — parâmetros opcionais ?provider=, ?status=, ?limit= (1–500, padrão 50)
POST	/api/v1/agents/tasks	Cria uma tarefa — corpo validado por CreateCloudAgentTaskSchema (providerId, prompt, source, options?). Retorna 201 com o envelope da tarefa
DELETE	/api/v1/agents/tasks?id=...	Exclui uma tarefa
GET	/api/v1/agents/tasks/[id]	Consulta uma tarefa — atualiza de forma síncrona o status a partir do agente de nuvem upstream quando um 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]	Exclui uma tarefa específica por id

Autenticação: a autenticação de gerenciamento é obrigatória em todos os métodos (requireCloudAgentManagementAuth). Antes da v3.8.0, eles não exigiam autenticação — consulte o commit 588a0333 para ver a alteração incompatível.

# Criar uma tarefa na nuvem 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 Gerenciamento

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

Método	Caminho	Descrição
GET	/api/v1/management/proxies	Lista proxies (com ?id= retorna um; com ?id=&where_used=1 retorna 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	Exclui um proxy (use force=1 para desvincular atribuições)
GET	/api/v1/management/proxies/assignments	Lista atribuições — filtrável por proxy_id, scope, scope_id; informe resolve_connection_id=<id> para resolver o proxy ativo de uma conexão
PUT	/api/v1/management/proxies/assignments	Atribui — corpo validado por proxyAssignmentSchema ({scope, scopeId?, proxyId?}). Limpa o cache do dispatcher
PUT	/api/v1/management/proxies/bulk-assign	Faz atribuições em massa — corpo validado por bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?})
GET	/api/v1/management/proxies/health?hours=24	Agrega a integridade dos proxies (contagens de sucessos/falhas e latência) durante um intervalo

Autenticação: sessão de gerenciamento/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 presentes na descrição da tarefa são atendidos pelas rotas simples /assignments e /health mostradas acima — não há sub-rotas por id na base de código.

---

Resiliência (estendida)

O OmniRoute oferece três mecanismos independentes para falhas temporárias; os endpoints de gerenciamento abaixo permitem que os operadores consultem e substituam suas configurações:

Escopo	Armazenamento de estado	Consulta	Redefinição / limpeza
Disjuntor do provedor	domain_circuit_breakers + memória	/api/monitoring/health	POST /api/resilience/reset
Espera da conexão	rateLimitedUntil nas conexões com o provedor	/api/rate-limits, /api/providers/[id]	(reativa de forma tardia; limpe via PUT do provedor)
Bloqueio do modelo	Registro de disponibilidade de modelos em memória	GET /api/resilience/model-cooldowns	DELETE /api/resilience/model-cooldowns

PATCH /api/resilience aceita substituições do disjuntor do provedor em providerBreaker.oauth e providerBreaker.apikey. Cada perfil aceita degradationThreshold, failureThreshold e resetTimeoutMs; os mesmos campos estão disponíveis em Painel → Configuraçõ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 consultar a referência conceitual completa e os valores padrão dos disjuntores, consulte CLAUDE.md → "Estado de resiliência em tempo de execução".

---

Habilidades

Framework de habilidades para estender o OmniRoute com manipuladores executáveis personalizados, além de integrações com marketplaces.

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

Autenticação: sessão de gerenciamento/chave de API. As rotas de pesquisa do marketplace aceitam autenticação de gerenciamento ou uma chave de API Bearer (isAuthenticated).

---

Memória

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

Método	Caminho	Descrição
GET	/api/memory	Lista memórias — ?apiKeyId=, ?type=, ?sessionId=, ?q=, com paginação por 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]	Recupera uma memória
DELETE	/api/memory/[id]	Exclui uma memória
GET	/api/memory/health	Integridade do subsistema de memória (conectividade com o banco de dados, backend de embeddings, status do índice vetorial)

Autenticação: sessão de gerenciamento/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 escopo definido. Os endpoints do painel abaixo leem dados de status/auditoria e fazem proxy dos transportes HTTP.

Método	Caminho	Descrição
GET	/api/mcp/status	Heartbeat, transporte, estado online, última chamada, principais ferramentas, taxa de sucesso em 24 horas
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 (retorna 503 se o MCP estiver desabilitado ou houver incompatibilidade de transporte)
POST	/api/mcp/sse	Envia um quadro JSON-RPC no transporte SSE
GET	/api/mcp/stream	Abre o lado SSE do transporte Streamable HTTP (mensagens iniciadas pelo servidor)
POST	/api/mcp/stream	Envia um quadro JSON-RPC no transporte Streamable HTTP
DELETE	/api/mcp/stream	Encerra uma sessão Streamable HTTP
GET	/api/mcp/audit	Consulta o log 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, principais ferramentas)

Autenticação: os transportes sse/stream respeitam a interface de autenticação específica do MCP (chave de API Bearer com escopo mcp); as rotas status/tools/audit* podem ser lidas pelo painel (nenhuma autenticação adicional é necessária além de acessar o host do painel).

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

---

Servidor A2A

O OmniRoute expõe um endpoint A2A (Agent-to-Agent) JSON-RPC 2.0, além de um wrapper REST para uso em inspeção/painel.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # opcional, a menos que OMNIROUTE_API_KEY esteja definida
Content-Type: application/json

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

Métodos compatíveis (todos condicionados a settings.a2aEnabled):

Método	Descrição
message/send	Execução síncrona de habilidade; retorna {task, artifacts, metadata}
message/stream	Execução via streaming SSE do mesmo conjunto de habilidades
tasks/get	Busca uma tarefa por taskId
tasks/cancel	Cancela uma tarefa por taskId

Habilidades integradas: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.

Cartão do agente

GET /.well-known/agent.json

Retorna o cartão público do agente A2A (nome, descrição, recursos, catálogo de habilidades, esquema de autenticação) — armazenado em cache público por 1h. Nenhuma autenticação é necessária.

Auxiliares REST

Método	Caminho	Descrição
GET	/api/a2a/status	A2A habilitado + estatísticas de tarefas + resumo do cartão do agente armazenado 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 — crie via JSON-RPC message/send)
GET	/api/a2a/tasks/[id]	Recupera uma tarefa
POST	/api/a2a/tasks/[id]/cancel	Cancela uma tarefa

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

---

Nuvem, avaliações e análise

Método	Caminho	Descrição
POST	/api/cloud/auth	Verifica uma chave Bearer e retorna conexões mascaradas de provedores + aliases de modelos para clientes de sincronização na nuvem
POST	/api/cloud/credentials/update	Atualiza credenciais criptografadas de um provedor sincronizado com a nuvem
POST	/api/cloud/model/resolve	Resolve um ID lógico de modelo para um provedor/modelo concreto usando a tabela de roteamento local
GET	/api/cloud/models/alias	Lista os aliases de modelos expostos à sincronização na nuvem
GET	/api/assess	Lê as categorizações da avaliação mais recente (por provedor/modelo)
POST	/api/assess	Executa uma avaliação — corpo: `{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	/api/evals	Lista os conjuntos de avaliação integrados + as execuções mais recentes
POST	/api/evals	Aciona uma execução de avaliação
POST	/api/evals/suites	Cria um conjunto de avaliação personalizado — corpo validado por evalSuiteSaveSchema
GET	/api/evals/suites/[id]	Recupera um conjunto de avaliação personalizado

Autenticação: /api/cloud/auth valida diretamente uma chave Bearer; as demais rotas /api/cloud/*, /api/evals/* e /api/assess exigem uma sessão/chave de API de gerenciamento. O POST de /api/assess usa validateBody com um esquema de escopo de união discriminada.

---

Gerenciamento do ACP (Agent Client Protocol)

como processos filhos. Esses endpoints gerenciam a detecção de agentes ACP e o registro de agentes personalizados.

Método	Caminho	Descrição
GET	/api/acp/agents	Lista todos os agentes de CLI conhecidos (integrados + personalizados), incluindo status de instalação, versão e binário
POST	/api/acp/agents	Registra um agente ACP personalizado ou atualiza o 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 gerenciamento (cookie auth_token do dashboard) ou uma chave de API com escopo de gerenciamento.

Consulte Framework ACP para obter todos os detalhes.

---

Análises e observabilidade

Endpoints de análise em tempo real para monitorar o roteamento, a compactação e a diversidade de provedores. Eles alimentam as páginas /dashboard/analytics/*.

Análises de roteamento automático

Método	Caminho	Descrição
GET	/api/analytics/auto-routing	Estatísticas agregadas de roteamento automático: total de chamadas, distribuição por estratégia, nível e provedores
GET	/api/analytics/auto-routing?days=7	Estatísticas por janela de tempo (padrão: 24h)

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álises de compactação

Método	Caminho	Descrição
GET	/api/analytics/compression	Estatísticas agregadas de compactação: tokens economizados, % de economia, distribuição por modo, uso por mecanismo

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

Monitoramento da diversidade de provedores

Método	Caminho	Descrição
GET	/api/analytics/diversity	Monitoramento da diversidade baseado na entropia de Shannon: evita pontos únicos de falha medindo a distribuição entre os provedores

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": ["OpenAI accounts for 40% of traffic — consider diversifying"]
}

Autenticação: Requer uma sessão de gerenciamento ou uma chave de API com escopo de gerenciamento.

---

Operações Administrativas

Endpoints exclusivos para administradores destinados ao gerenciamento operacional.

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

Autenticação: Requer sessão de gerenciamento com escopo de administrador.

---

Gerenciamento de Ferramentas de CLI

Gerencie ferramentas de CLI que se integram ao OmniRoute (antigravity, chipotle, commandCode, devin-cli etc.). Consulte a Referência de Provedores para ver a lista completa.

Método	Caminho	Descrição
GET	/api/cli-tools/all-statuses	Status de todas as ferramentas de CLI (instalação, versão, última detecção)
GET	/api/cli-tools/status	Detalhes do status de uma ferramenta de CLI (consulta ?tool=)
POST	/api/cli-tools/apply	Grava a configuração gerada de uma ferramenta (dryRun exibe uma prévia; 422 + containerEphemeralTarget quando em contêiner; migration indica um YAML legado do Codex)
GET	/api/cli-tools/backups	Lista os backups de configuração das ferramentas de CLI
POST	/api/cli-tools/backups	Cria um backup das configurações de todas as ferramentas de CLI
POST	/api/cli-tools/backups	Restauração: o mesmo endpoint com {tool, backupId} no corpo restaura esse backup
GET	/api/cli-tools/antigravity-mitm	Status do proxy MITM do Antigravity (a ferramenta de CLI "antigravity-mitm")
POST	/api/cli-tools/antigravity-mitm/alias	Configura aliases do antigravity-mitm

Autenticação: Requer sessão de gerenciamento.

---

Habilidades de Agente

Gerencie habilidades de agentes de IA (semelhantes aos GPTs personalizados da OpenAI, mas voltadas para agentes).

Método	Caminho	Descrição
GET	/api/agent-skills	Lista todas as habilidades de agente (integradas + personalizadas)
GET	/api/agent-skills/[id]	Obtém uma habilidade de agente específica
POST	/api/agent-skills	Cria uma habilidade de agente personalizada — corpo: {name, description, prompt, model?, temperature?}
PUT	/api/agent-skills/[id]	Atualiza uma habilidade de agente personalizada
DELETE	/api/agent-skills/[id]	Exclui uma habilidade de agente personalizada
GET	/api/agent-skills/[id]/raw	Obtém o prompt bruto + metadados (sem execução)
POST	/api/agent-skills/generate	Gera, por meio de IA, uma nova habilidade a partir de uma descrição em linguagem natural

Autenticação: Requer sessão de gerenciamento ou chave de API com escopo de gerenciamento.

---

Gerenciamento de cache

Gerencie o cache semântico e o cache de raciocínio.

Método	Caminho	Descrição
GET	/api/cache	Visão geral do cache: total de entradas, taxa de acertos, tamanho em disco
GET	/api/cache/entries	Lista as entradas armazenadas em cache (com paginação)
DELETE	/api/cache/entries	Exclui entradas do cache (filtradas por parâmetros de consulta)
GET	/api/cache/stats	Estatísticas detalhadas do cache (por provedor, por modelo)
GET	/api/cache/reasoning	Status do cache de raciocínio (para reprodução de raciocínio)
DELETE	/api/cache/reasoning	Limpa o cache de raciocínio — parâmetros de consulta: ?toolCallId=<id> (único), ?provider=<p> ou nenhum parâmetro (todos)

Autenticação: Requer sessão de gerenciamento.

---

Sistema de memória

Gerencie a memória persistente (FTS5 + embeddings vetoriais).

Método	Caminho	Descrição
GET	/api/memory	Lista as entradas de memória (filtradas por escopo, tipo e consulta de pesquisa)
POST	/api/memory	Cria uma nova entrada de memória — corpo: {scope, type, content, metadata?}
GET	/api/memory/[id]	Obtém uma entrada de memória específica
PUT	/api/memory/[id]	Atualiza uma entrada de memória
DELETE	/api/memory/[id]	Exclui uma entrada de memória
GET	/api/memory?q=	Pesquisa na memória (FTS5 + vetorial) — as estatísticas são incluídas na mesma resposta

Autenticação: Requer sessão de gerenciamento ou chave de API com escopo de gerenciamento.

---

Webhooks

Gerencie assinaturas de webhooks para eventos.

Método	Caminho	Descrição
GET	/api/webhooks	Lista todas as assinaturas de webhooks
POST	/api/webhooks	Cria uma assinatura de webhook — corpo: {url, events[], secret?, active?}
GET	/api/webhooks/[id]	Obtém uma assinatura de webhook específica
PUT	/api/webhooks/[id]	Atualiza uma assinatura de webhook
DELETE	/api/webhooks/[id]	Exclui uma assinatura de webhook
GET	/api/webhooks/[id]/deliveries	Lista o histórico de entregas de um webhook (registro de sucessos/falhas)
POST	/api/webhooks/[id]/test	Envia um evento de teste para um webhook

Autenticação: Requer sessão de gerenciamento.

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

---

Framework de Skills

Gerencie Skills (o framework de extensões agênticas).

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

Autenticação: Requer uma sessão de gerenciamento ou uma chave de API com escopo de gerenciamento.

Consulte Framework de Skills para obter todos os detalhes.

---

Plugins

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

Método	Caminho	Descrição
GET	/api/plugins	Lista os plugins instalados
POST	/api/plugins/marketplace/install	Instala um plugin do marketplace
DELETE	/api/plugins/[name]	Desinstala um plugin
POST	/api/plugins/[name]/activate	Ativa um plugin
POST	/api/plugins/[name]/deactivate	Desativa um plugin
GET	/api/plugins/[name]/config	Obtém a configuração do plugin
PUT	/api/plugins/[name]/config	Atualiza a configuração do plugin

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

Consulte Framework de Plugins para obter todos os detalhes.

---

Roteamento Shadow

A comparação shadow/A-B de provedores não é uma superfície REST independente — ela é configurada por meio do roteamento combo (consulte Auto-Combo). As métricas de comparação por combo são fornecidas por GET /api/combos/metrics.

---

Guardrails

Inspecione os guardrails de runtime (detecção de PII, detecção de injeção de prompt e ponte de visão). Os guardrails são executados em todas as solicitações; a desativação por chamada é feita por meio do cabeçalho de solicitação x-omniroute-disabled-guardrails — não há uma interface persistente para habilitação/desabilitação.

Método	Caminho	Descrição
GET	/api/guardrails	Lista os guardrails registrados e seus status (nome/habilitado/prioridade)
POST	/api/guardrails/test	Executa um teste sem efeitos do pipeline de pré-chamada sobre uma entrada de exemplo — corpo: {input, disabledGuardrails?}

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

Consulte Segurança > Guardrails para obter todos os detalhes.

---

---

Autenticação

Consulte Autenticação de gerenciamento para conhecer as quatro famílias de credenciais (sessão do dashboard, token da CLI local, Token de Acesso oma_live_…, chave de API com escopo de gerenciamento) e como elas diferem das chaves de inferência.

• As rotas do dashboard (/dashboard/*) usam o cookie auth_token
• O login usa o hash de senha salvo; em caso de falha, usa INITIAL_PASSWORD
• requireLogin pode ser alternado por meio 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 gerenciamento" / "chave de API com escopo de gerenciamento" significa uma das famílias descritas nesse guia — não um tipo adicional indefinido de segredo

Alteração incompatível (v3.8.0) — /api/v1/agents/tasks/* e os endpoints de gerenciamento de cooldown agora exigem autenticação de gerenciamento (cookie auth_token do dashboard ou uma chave de API com escopo de gerenciamento). Os clientes que anteriormente chamavam essas rotas sem autenticação receberão 401 Unauthorized. Consulte o commit 588a0333 (fix(auth): exige autenticação de gerenciamento para APIs de agentes e cooldown).