Visão Geral da API

Base URLs, autenticação, códigos de erro e convenções de todas as APIs da 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