API Reference (Português (Brasil))

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 de Sessão Gerenciadas Exclusivas

O aluguel de sessão gerenciada exclusiva é um contrato de roteamento opcional e neutro para o cliente: um proprietário ativo detém uma conexão OmniRoute elegível. Ele não aluga 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 de 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 impõe ambos os campos juntos na criação da chave e em atualizações parciais.

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

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

Respostas bem-sucedidas de aquisição, renovação e liberação expõem carimbos de data/hora, state e a generation positiva exata, mas nunca a conexão ou credenciais selecionadas. 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" }

Um proprietário de concessão ativo pode solicitar explicitamente metadados de exibição seguros para a privacidade de 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"
  }
}

Esta 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 da conexão configurada e truncado; é null quando não existe um nome configurado seguro. O OmniRoute nunca substitui um e-mail ou uma identidade de conta gerada. O valor do provedor é um rótulo de exibição não sensível e nunca um identificador de provedor compatível gerado. Credenciais, tokens, cookies, IDs de conexão bruta ou de chave de API, hashes de proprietário, segredos de proteção e dados de roteamento internos são excluídos.

Consultas com chave errada, proprietário errado, geração obsoleta, ausentes, expiradas, liberadas e invalidadas retornam o mesmo erro 409 LEASE_FENCE_STALE sem metadados de conexão. Um cliente que recebeu a resposta de espera de capacidade não tem nenhuma vinculação ativa para inspecionar. Quando o roteamento transiciona 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 suas formas anteriores.

Este contrato de servidor não altera o /status padrão do OpenAI Codex. O Codex padrão atualmente relata seu provedor de modelo e o estado de autenticação/conta integrado, mas não renderiza metadados arbitrários de conta de provedor personalizado; uma integração de cliente posterior deve chamar esta 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 protegidos imediatamente antes de cada tentativa upstream suportada. Repetir proprietário e geração com outra chave falha mesmo quando essa chave permite a mesma conexão. Proprietários brutos não são persistidos, registrados, retidos no snapshot da solicitação ou encaminhados 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
}

Esta resposta significa apenas que o conjunto elegível comum não estava vazio e que cada candidato livre estava sendo mantido por uma concessão ativa estrangeira. Modelos/provedores não suportados, incompatibilidade de política, tempo de espera (cooldown), cota, saúde e outras falhas comuns de elegibilidade mantêm suas respostas OmniRoute existentes.

`x-omniroute-compression`

Sobrescrita por solicitação do plano de compressão. Precedência mais alta — supera a sobrescrita do combo de roteamento, o perfil ativo, o gatilho automático e o Padrão do painel. Valores:

Valor	Efeito
`off`	Nenhuma compressão para esta solicitação.
`default`	O perfil Padrão derivado do painel (ignora o perfil ativo). Motores com perda são desativados.
`safe`	Apenas deduplicação e dobramento de espaços em branco.
`allow-lossy`	Mantém o plano do operador para esta solicitação, incluindo resumos e reescritas de estilo.
`engine:<id>`	Um único motor quando ativado, por exemplo, `engine:rtk`. Ativação opcional por solicitação para esse motor.
`<combo>`	Um combo nomeado, correspondido primeiro pelo nome (sem distinção entre maiúsculas e minúsculas), depois pelo ID.

Observações:

Valores desconhecidos são ignorados (a solicitação nunca é rejeitada); a resolução segue a precedência normal do operador.
Se vários combos compartilharem um nome, passe o ID do combo para uma correspondência determinística.
Um combo cujo nome é off ou default não pode ser selecionado pelo nome (essas palavras-chave são interpretadas primeiro); referencie tal combo pelo seu ID.
O interruptor mestre de compressão é um portão rígido: quando a compressão é desativada globalmente, este cabeçalho não pode ativá-la.

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

X-OmniRoute-Compression: &lt;mode&gt;; source=<source>

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

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/&lt;provider&gt;/&lt;model&gt;

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`	Respostas OpenAI
POST	`/v1/embeddings`	OpenAI
POST	`/v1/images/generations`	Imagens OpenAI
POST	`/v1/images/edits`	Imagens OpenAI (edição/inpaint)
POST	`/v1/videos/generations`	Geração de vídeo estilo OpenAI
POST	`/v1/music/generations`	Geração de música estilo OpenAI
POST	`/v1/audio/transcriptions`	Áudio OpenAI (STT)
POST	`/v1/audio/speech`	TTS OpenAI (retorna corpo de áudio)
POST	`/v1/rerank`	Rerank estilo Cohere/Voyage
POST	`/v1/classify`	Classificação Jina (`api.jina.ai`)
POST	`/v1/segment`	Segmentador Jina (`segment.jina.ai`)
POST	`/v1/moderations`	Moderações OpenAI
GET	`/v1/models`	OpenAI
POST	`/v1/messages/count_tokens`	Anthropic
GET	`/v1beta/models`	Gemini
POST	`/v1beta/models/{...path}`	Gemini generateContent
POST	`/v1/api/chat`	Ollama
GET	`/api/v1/vscode/{token}/`	Alias de catálogo OpenAI
GET	`/api/v1/vscode/{token}/models`	Alias de modelos OpenAI
POST	`/api/v1/vscode/{token}/chat/completions`	Alias tokenizado OpenAI
POST	`/api/v1/vscode/{token}/responses`	Alias tokenizado de Respostas OpenAI
POST	`/api/v1/vscode/{token}/api/chat`	Alias tokenizado Ollama
GET	`/api/v1/vscode/{token}/api/tags`	Alias tokenizado de tags Ollama

Todas as rotas POST seguem o mesmo formato: Bearer your-api-key + corpo JSON validado por Zod (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema, etc., veja src/shared/validation/schemas.ts). Um erro 4xx é retornado em caso de falha de esquema.

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

# Rerank (cloud registry provider, or an OpenAI-compatible provider node as "&lt;prefix&gt;/&lt;model&gt;")
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

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

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

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

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

# TTS — returns audio/mpeg (or requested format) body
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

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

# Video / music generation (provider-prefixed model id)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "kie/suno-v4.0",   "prompt": "..." }

Nós provedores de Rerank: POST /v1/rerank também roteia para nós provedores compatíveis com OpenAI (oMLX, vLLM, Infinity, TEI por trás de um gateway, …) endereçados como <node-prefix>/<model>. Nós de loopback (localhost, 127.0.0.1, 172.16.0.0/12) são sempre elegíveis. Nós em qualquer outro host — uma caixa LAN ou peer Tailscale — são elegíveis apenas quando o operador habilita a flag de recurso RERANK_REMOTE_PROVIDER_NODES e a URL base do nó passa pela política de URL de saída do provedor (OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS / OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS); hosts de metadados de nuvem nunca são roteados. A etapa de rerank do motor de memória chama esta rota via loopback, então a mesma regra governa rerankProviderModel nas configurações de Memória.

Formatos de servidor local: o nó é chamado em <base>/v1/rerank e, em caso de 404, em <base>/rerank (Infinity, TEI). O corpo upstream carrega tanto a grafia Cohere/OpenAI (documents, return_documents) quanto a grafia TEI (texts, return_text), e a resposta upstream é normalizada para o envelope Cohere: [{index, score, text}] puro do TEI, {results: [{index, score}]} de gateways finos, e {data: [...]} estilo Voyage, todos retornam ao cliente como {results: [{index, relevance_score, document?}]}, ordenados por pontuação e limitados a top_n.

Descoberta de nós provedores: modelos em um nó provedor compatível com OpenAI aparecem em GET /v1/models sob o prefixo do nó. Linhas que não contêm metadados de endpoint (típico para listagens locais de /v1/models) herdam o apiType do nó, então os modelos de um nó de embeddings são type: "embedding" e os modelos de um nó de rerank são type: "rerank" em vez de usar o padrão de chat; um supportedEndpoints explícito em uma linha sincronizada ou adicionada manualmente ainda tem precedência.

Rotas Dedicadas do Provedor

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

O prefixo do provedor é adicionado automaticamente se estiver faltando. 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 &lt;sua-chave-de-api&gt;" \
  http://localhost:20128/api/usage/om-usage

# Formato estruturado — o que uma interface de usuário consome
curl -H "Authorization: Bearer &lt;sua-chave-de-api&gt;" \
  "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

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

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, 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 (instalada, 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` fornece 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 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 uma 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).

Código-fonte do OmniRoute (a58000c7685f)

HagiCode

HagiCode é um ambiente de programação com agentes, fluxos estruturados, execução multiagente e visualizações Hero Dungeon.

Transforme ideias em software útil com um fluxo de trabalho com agentes mais inteligente, rápido e agradável.

Interface principal do HagiCode no tema claro

SmartFluxos estruturados transformam intenções em um caminho executável da ideia à entrega.
EfficientFluxos multiagente mantêm pesquisa, implementação e revisão em andamento simultaneamente.
FunO Hero Dungeon torna longas sessões de programação mais visuais e colaborativas.

Acessar HagiCode

API Reference (Português (Brasil))

Sumário

Conclusões de Chat

Cabeçalhos Personalizados

Concessões de Sessão Gerenciadas Exclusivas

x-omniroute-compression

Embeddings

Geração de imagens

OCR de documentos

Fluxo de sondagem do Azure Document Intelligence

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

Listar modelos

Prefixos de ID de modelo (?prefix=)

Variantes de modelo sem raciocínio

Manifesto do Plugin de Provedor

Endpoints de Compatibilidade

Rotas Dedicadas do Provedor

API de Arquivos

API de Lotes

API de Busca

API de Busca de Conteúdo Web

Streaming via WebSocket

API Responses via WebSocket (somente codex)

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

Configuração da Codex CLI da OpenAI

Relatórios de cotas e problemas

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

Cache semântico

Impacto na latência

Desvio do cache por chave

Desvio por solicitação

Dashboard e Gerenciamento

Autenticação

Gerenciamento de Provedores

Fluxos OAuth

Roteamento e Configuração

Uso e Análises

Configurações

Contexto e compactação

Monitoramento

Backup e exportação/importação

Sincronização com a nuvem

Túneis

Ferramentas de CLI

Agentes ACP

Resiliência e limites de taxa

Avaliações

Políticas

Conformidade

v1beta (compatível com Gemini)

APIs internas/do sistema

Reparo do ambiente OAuth (v3.6.1+)

Transcrição de áudio

Compatibilidade com o Ollama

Aliases tokenizados para o VS Code / sem cabeçalho

Telemetria

Orçamento

Limites de tokens

Processamento de solicitações

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

JSON-RPC

Cartão do agente

Auxiliares REST

Nuvem, avaliações e análise

Gerenciamento do ACP (Agent Client Protocol)

Análises e observabilidade

Análises de roteamento automático

Análises de compactação

Monitoramento da diversidade de provedores

Operações Administrativas

Gerenciamento de ferramentas de CLI

`x-omniroute-compression`

Prefixos de ID de modelo (`?prefix=`)

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

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