DocumentaçãoAPI Reference

Morvix API v1

API REST para acesso a modelos de linguagem, agentes IA, embeddings e análise financeira especializada. Compatível com OpenAI SDK — basta trocar a base URL.

Operacional

Base URL: https://app.morvix.com.br/api/v1

Autenticação

Bearer token em todas as requisições

Inclua o header Authorization: Bearer mvx_live_... em todas as requisições. Gere suas chaves no Portal Developer.

Formato

mvx_live_<hash>

Header

Authorization: Bearer

Rate limit

100 req/min

bash

curl https://app.morvix.com.br/api/v1/chat \
  -H "Authorization: Bearer mvx_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "model": "gemini-2.0-flash", "messages": [{ "role": "user", "content": "Olá!" }] }'

A chave raw é exibida uma única vez na criação. Armazene imediatamente como variável de ambiente — nunca no código-fonte.

Modelos disponíveis

Múltiplos providers com uma única API

Model ID	Provider	Input /1M tok	Endpoint
gemini-2.0-flash	Google	$0.10	chat, completions
gemini-1.5-pro	Google	$1.25	chat, completions
gpt-4o	OpenAI	$2.50	chat, completions
gpt-4o-mini	OpenAI	$0.15	chat, completions
claude-sonnet-4-6	Anthropic	$3.00	chat, completions
claude-haiku-4-5	Anthropic	$0.25	chat, completions
llama-3.3-70b	Groq	$0.59	chat, completions
mixtral-8x7b	Groq	$0.27	chat, completions
text-embedding-3-small	OpenAI	$0.02	embeddings
text-embedding-3-large	OpenAI	$0.13	embeddings
text-embedding-004	Google	grátis	embeddings

Chat

Conversação multi-turno com qualquer modelo

POST/api/v1/chatCriar mensagem

Envia mensagens para o modelo e retorna a resposta do assistente. Suporta streaming SSE quando stream: true. Retorna formato compatível com OpenAI.

Parâmetros

Campo	Tipo	Req.	Descrição
model	string	sim	ID do modelo (ex: gemini-2.0-flash, gpt-4o-mini)
messages	Message[]	sim	Array [{role: 'user'\|'assistant'\|'system', content: string}]
stream	boolean	não	Streaming SSE (text/event-stream)
temperature	number	não	Criatividade 0–2 (padrão: 0.7)
max_tokens	number	não	Limite de tokens na resposta
system	string	não	Prompt de sistema (alternativa ao role system)

Exemplo de body

json

{
  "model": "gemini-2.0-flash",
  "messages": [
    { "role": "system", "content": "Você é um analista de FIIs." },
    { "role": "user",   "content": "Como funciona o MXRF11?" }
  ],
  "temperature": 0.7,
  "max_tokens": 1024
}

Resposta de sucesso

json

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "gemini-2.0-flash",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "MXRF11 é um FII de papel que..." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 28, "completion_tokens": 312, "total_tokens": 340 }
}

Código de exemplo

curl -X POST https://app.morvix.com.br/api/v1/chat \
  -H "Authorization: Bearer mvx_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.0-flash",
    "messages": [{ "role": "user", "content": "Explique FIIs" }]
  }'

Completions

Geração de texto a partir de prompt simples

POST/api/v1/completionsCriar completion

Gera texto a partir de um prompt sem histórico de conversa. Ideal para automações, templates e geração de conteúdo.

Parâmetros

Campo	Tipo	Req.	Descrição
model	string	sim	ID do modelo
prompt	string	sim	Texto de entrada
max_tokens	number	não	Máximo de tokens (padrão: 1024)
temperature	number	não	Criatividade 0–2
stream	boolean	não	Streaming SSE

Exemplo de body

json

{
  "model": "gpt-4o-mini",
  "prompt": "Escreva um resumo sobre FIIs de papel:",
  "max_tokens": 512,
  "temperature": 0.5
}

Resposta de sucesso

json

{
  "id": "cmpl-abc123",
  "object": "text_completion",
  "model": "gpt-4o-mini",
  "choices": [{
    "text": "FIIs de papel são fundos que investem em títulos...",
    "index": 0,
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 12, "completion_tokens": 128, "total_tokens": 140 }
}

Código de exemplo

curl -X POST https://app.morvix.com.br/api/v1/completions \
  -H "Authorization: Bearer mvx_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "model": "gpt-4o-mini", "prompt": "Resumo sobre FIIs:" }'

Embeddings

Vetores semânticos para busca e RAG

POST/api/v1/embeddingsGerar embeddings

Converte textos em vetores de alta dimensão para busca semântica, clustering, RAG ou similaridade de documentos.

Parâmetros

Campo	Tipo	Req.	Descrição
model	string	sim	text-embedding-3-small \| text-embedding-3-large \| text-embedding-004
input	string[]	sim	Array de textos (máx. 100 itens)

Exemplo de body

json

{
  "model": "text-embedding-3-small",
  "input": [
    "MXRF11 apresentou crescimento de dividendos",
    "HGLG11 vacância abaixo de 5%"
  ]
}

Resposta de sucesso

json

{
  "object": "list",
  "model": "text-embedding-3-small",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0023, -0.0041, ...] },
    { "object": "embedding", "index": 1, "embedding": [0.0071,  0.0032, ...] }
  ],
  "usage": { "prompt_tokens": 18, "total_tokens": 18 }
}

Código de exemplo

const result = await morvix.embed({
  model: "text-embedding-3-small",
  input: ["MXRF11 pagou R$0,10/cota", "HGLG11 vacância baixa"],
});

const [v1, v2] = result.data.map(d => d.embedding);
const similarity = v1.reduce((sum, v, i) => sum + v * v2[i], 0);
console.log("Similaridade coseno:", similarity);

Análise Financeira

IA especializada no mercado brasileiro — exclusivo Morvix

Prompts especializados para FIIs, ações, ETFs e portfólios. Usa gemini-2.0-flash com temperature 0.3 para respostas precisas e técnicas.

POST/api/v1/analyze-financial-dataAnálise financeira

Analisa ativos e portfólios com contexto especializado do mercado brasileiro. Suporta 6 tipos de análise diferentes.

Parâmetros

Campo	Tipo	Req.	Descrição
type	string	sim	fii \| stock \| etf \| portfolio \| cashflow \| compare
ticker	string	não	Ticker do ativo (ex: MXRF11, PETR4, IVVB11)
data	object	não	Dados do ativo (dy, p_vp, vacância, etc.)
question	string	não	Pergunta específica sobre o ativo
tickers	string[]	não	Para type: compare — lista de tickers

Exemplo de body

json

// Análise de FII
{
  "type": "fii",
  "ticker": "MXRF11",
  "data": { "dividend_yield": "12.5%", "p_vp": 0.92, "vacancia": "3.2%" },
  "question": "Vale a pena comprar agora? Qual o risco?"
}

// Comparar ativos
{
  "type": "compare",
  "tickers": ["HGLG11", "VISC11", "MXRF11"],
  "question": "Qual tem melhor risco/retorno para 2025?"
}

Resposta de sucesso

json

{
  "success": true,
  "data": {
    "analysis": "Com base nos dados fornecidos, MXRF11 apresenta...",
    "type": "fii",
    "ticker": "MXRF11",
    "usage": { "promptTokens": 412, "completionTokens": 680, "totalTokens": 1092 }
  }
}

Código de exemplo

const res = await morvix.analyzeFinancial({
  type: "fii",
  ticker: "MXRF11",
  data: { dividend_yield: "12.5%", p_vp: 0.92 },
  question: "Vale a pena comprar agora?",
});
console.log(res.data.analysis);

Agentes

Execute agentes com memória e sessões persistentes

POST/api/v1/agentsExecutar agente

Executa um agente configurado. Cria ou retoma sessões com memória. O agente tem system prompt, knowledge base e ferramentas configuradas no portal.

Parâmetros

Campo	Tipo	Req.	Descrição
agentId	string	sim	ID do agente (veja /agents no portal)
message	string	sim	Mensagem do usuário
sessionId	string	não	ID de sessão existente para continuar a conversa

Exemplo de body

json

{
  "agentId": "agent_abc123",
  "message": "Analise minha carteira de FIIs",
  "sessionId": "session_xyz789"
}

Resposta de sucesso

json

{
  "success": true,
  "data": {
    "response": "Com base no histórico, sua carteira apresenta...",
    "sessionId": "session_xyz789",
    "agentId": "agent_abc123",
    "usage": { "promptTokens": 1240, "completionTokens": 380 }
  }
}

Código de exemplo

const res = await morvix.runAgent({
  agentId: "agent_abc123",
  message: "Analise minha carteira de FIIs",
  sessionId: savedSessionId, // undefined na primeira mensagem
});

console.log(res.data.response);
// Salvar para próximas mensagens:
savedSessionId = res.data.sessionId;

Gerenciar API Keys

Criar, listar e revogar chaves — autenticação por sessão

Esses endpoints usam sessão web (cookie, não Bearer token). Máximo de 10 chaves ativas por usuário.

GET/api/v1/keysListar keys

Retorna todas as API keys do usuário autenticado. Nunca retorna o valor completo — apenas o prefixo.

Resposta de sucesso

json

{
  "success": true,
  "data": [{
    "id": "key_abc",
    "name": "Produção",
    "keyPrefix": "mvx_live_a1b2c3d4",
    "status": "active",
    "environment": "live",
    "rateLimit": 100,
    "monthlyLimit": 10000,
    "totalRequests": 1240,
    "lastUsedAt": "2026-06-14T10:30:00Z",
    "createdAt": "2026-06-01T00:00:00Z"
  }]
}

POST/api/v1/keysCriar key

Cria uma nova API key. O valor raw é retornado UMA ÚNICA VEZ — armazene imediatamente.

Parâmetros

Campo	Tipo	Req.	Descrição
name	string	sim	Nome descritivo
environment	string	não	live \| test (padrão: live)
rateLimit	number	não	Req/min (padrão: 100)
monthlyLimit	number	não	Req/mês (padrão: 10000)
allowedOrigins	string[]	não	Origens CORS permitidas
expiresAt	string	não	Data de expiração ISO 8601

Resposta de sucesso

json

{
  "success": true,
  "data": {
    "id": "key_newxxx",
    "name": "Produção",
    "key": "mvx_live_a1b2c3d4e5f6...",
    "keyPrefix": "mvx_live_a1b2c3d4",
    "status": "active"
  }
}

DELETE/api/v1/keysRevogar key

Revoga (desativa) permanentemente uma API key pelo ID. Requisições futuras com essa key receberão 401.

Parâmetros

Campo	Tipo	Req.	Descrição
id	string	sim	ID da key

Resposta de sucesso

json

{ "success": true, "message": "Key revogada com sucesso" }

Usage Analytics

Monitorar consumo e custos

GET/api/developer/usageResumo de uso

Retorna métricas agregadas de uso da API. Custo calculado em micro-centavos internamente, retornado em centavos.

Parâmetros

Campo	Tipo	Req.	Descrição
period	query	não	today \| 7d \| 30d (padrão: 30d)

Resposta de sucesso

json

{
  "success": true,
  "data": {
    "totalRequests": 3240,
    "totalTokens": 4200000,
    "totalCostCents": 840,
    "avgLatencyMs": 1240,
    "byEndpoint": [
      { "endpoint": "/api/v1/chat",   "count": 2100 },
      { "endpoint": "/api/v1/agents", "count": 840  }
    ],
    "byModel": [
      { "model": "gemini-2.0-flash", "count": 1800, "tokens": 2400000 },
      { "model": "gpt-4o-mini",      "count": 440,  "tokens": 800000  }
    ]
  }
}

SDK TypeScript

Cliente oficial com tipagem completa

Localizado em src/sdk/index.ts. Importe diretamente ou publique como pacote npm.

import { Morvix } from "@/sdk";

const morvix = new Morvix({
  apiKey: process.env.MORVIX_API_KEY!,
  baseUrl: "https://app.morvix.com.br", // opcional
});

Erros

Formato de erro e códigos HTTP

json

{
  "error": {
    "message": "Rate limit exceeded",
    "code": "RATE_LIMIT_EXCEEDED",
    "status": 429
  }
}

Status	Code	Descrição
400	MISSING_FIELD	Campo obrigatório ausente
400	INVALID_MODEL	Model ID não suportado
400	INVALID_INPUT	Parâmetro com valor inválido
401	MISSING_API_KEY	Header Authorization ausente
401	INVALID_API_KEY	Chave inválida, revogada ou expirada
429	RATE_LIMIT_EXCEEDED	Limite de req/min atingido
429	MONTHLY_LIMIT_EXCEEDED	Limite mensal da key atingido
500	AI_PROVIDER_ERROR	Erro no provider de IA
500	INTERNAL_ERROR	Erro interno inesperado

Headers de rate limit (todas as respostas)

X-RateLimit-LimitLimite de req/min da key

X-RateLimit-RemainingRequisições restantes na janela atual

X-RateLimit-ResetUnix timestamp de reset