Conhecimento da sua organização,
pronto para humanos e agentes de IA.

Começar em três passos

Todas as chamadas são JSON. Use uma chave de API no cabeçalho Authorization.

curl "https://SEU-HOST/api/knowledge/search?query=deploy+pnpm&limit=5" \
  -H "Authorization: Key SUA_CHAVE"

curl -X POST "https://SEU-HOST/api/knowledge/classify" \
  -H "Authorization: Key SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"title":"Como corrigir CORS","content":"Adicione o header e reinicie o express.","source_system":"vertal"}'

Endpoints

Todos ficam sob /api/knowledge e exigem autenticação. Os endpoints públicos são / e /health.

Formato de respostas e erros

Erros de validação retornam 400 com error: "Invalid request" e uma lista em details.

Busca

A busca roda sobre o mesmo índice nos quatro modos. Os resultados vêm sempre com a mesma forma.

Exemplo de resposta

{
  "query": "deploy",
  "count": 1,
  "results": [{
    "id": "d9a13b67-2b81-4751-aa04-a51760a2243d",
    "title": "Deploy pnpm",
    "description": "How to",
    "source_system": "vertal",
    "knowledge_type": "PROCEDURE",
    "confidence_level": "HIGH",
    "relevance_score": 0.4
  }]
}

Validação e confiança

Cada voto em /validate pode trazer confidence_vote (increase, decrease ou maintain). A confiança do item é a média dos votos, e um voto por revisor é substituído se ele votar de novo.

Servidor MCP

Para agentes de IA. Expõe as mesmas capacidades da API como ferramentas. Pode ser usado remotamente por HTTP ou localmente por stdio.

Cada ferramenta valida a entrada com um esquema. Entrada inválida retorna erro de ferramenta, sem chamar a API. Erros da API viram isError com a mensagem original.

Local (stdio)

Depois do build, o pacote vertal-mcp instala o executável vertal-mcp (dist/stdio.js). Ele lê VERTAL_API_URL e VERTAL_API_KEY.

{
  "mcpServers": {
    "vertal": {
      "command": "vertal-mcp",
      "env": {
        "VERTAL_API_URL": "https://SEU-HOST",
        "VERTAL_API_KEY": "SUA_CHAVE"
      }
    }
  }
}

CLI vertal

Para operar a base direto do terminal, com acesso ao banco. Os comandos pedem --org-id e, quando aplicável, --user-id.

Fontes de ingestão

gitmoom documentation deployment_logs github · configuração em GITMOOM_API_URL, GITMOOM_API_KEY, GITHUB_OWNER, GITHUB_REPO, GITHUB_TOKEN.

Modelo de dados

Definido nas migrações SQL de infrastructure/supabase/migrations.

Configuração

Variáveis de ambiente lidas pelo serviço.

Status do projeto

O que já está pronto e o que vem a seguir.