Visão Geral da API - strattum.ai

A strattum.ai expõe quatro grupos de API REST, cada um mapeado a uma camada da plataforma:

Memory API

Perfis de entidades, timeline de eventos, grafo de relações e contexto formatado para agentes. Porta 8002.

Knowledge API

Busca semântica sobre documentos indexados e gerenciamento de chunks. Porta 8003.

Catalog API

Árvore do data lake, prévia de dados, contagem de linhas e lineage de pipelines. Porta 8001.

Connectors API

Gerenciamento do ciclo de vida de conectores: criar, testar, listar, atualizar e remover. Porta 8001.

Skills API

Execução de receitas analíticas (skills), gerenciamento de segredos e perguntas sugeridas. Porta 8007.

MCP Server

Endpoint SSE de transporte MCP para integração com Claude, Microsoft Copilot e ChatGPT. Porta 8005.

Base URLs

Serviço	Porta local	Hostname Docker Compose
Catalog API	`http://localhost:8001`	`http://strattum-catalog-api:8001`
Memory API	`http://localhost:8002`	`http://strattum-memory-api:8002`
Knowledge API	`http://localhost:8003`	`http://strattum-knowledge-api:8003`
MCP Server	`http://localhost:8005`	`http://strattum-mcp-server:8005`
Skills API	`http://localhost:8007`	`http://strattum-skills-api:8007`

Em produção (BYOC), os endereços são configurados nas variáveis de ambiente do deployment do cliente.

Autenticação

As APIs Memory, Knowledge e Catalog da versão 1.0 não exigem autenticação — o acesso é controlado pela rede privada do cliente (VPC/VLAN). Autenticação via API key está prevista no roadmap (v4).

O MCP Server é a exceção: ele exige autenticação via Bearer token no endpoint SSE.

Authorization: Bearer <MCP_API_KEY>

A chave é configurada pela variável de ambiente MCP_API_KEY no servidor.

Erros comuns

Todas as APIs seguem as convenções HTTP padrão e retornam erros no formato abaixo:

{
  "detail": "Mensagem descritiva do erro"
}

Para erros de validação (422), o formato inclui o caminho do campo inválido:

{
  "detail": [
    {
      "loc": ["body", "query"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Código	Significado	Causa comum
`400`	Bad Request	Parâmetro inválido ou conflito de estado
`401`	Unauthorized	Token Bearer ausente ou inválido (MCP Server)
`403`	Forbidden	Sem permissão para o recurso
`404`	Not Found	Entidade, documento ou conector não encontrado
`422`	Unprocessable Entity	Validação de campos falhou (FastAPI/Pydantic)
`503`	Service Unavailable	Banco de dados ou serviço de infraestrutura indisponível

Convenções

Todos os timestamps são em ISO-8601 UTC (2026-01-15T09:30:00Z)
IDs de entidades são UUID v4 (3fa85f64-5717-4562-b3fc-2c963f66afa6)
Paginação usa limit + offset (Knowledge e Catalog) ou limit único (Memory)
Respostas são sempre application/json

Memory API

Knowledge API

Catalog API

Connectors API

Skills API

MCP Server

​Base URLs

​Autenticação

​Erros comuns

​Convenções

Base URLs

Autenticação

Erros comuns

Convenções