> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strattum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.strattum.ai/api-reference/memory/introduction.md)**
>
> Perfis de entidades, timeline de eventos, grafo de relações e contexto formatado para agentes. Porta 8002.

> **[Knowledge API](https://docs.strattum.ai/api-reference/knowledge/introduction.md)**
>
> Busca semântica sobre documentos indexados e gerenciamento de chunks. Porta 8003.

> **[Catalog API](https://docs.strattum.ai/api-reference/catalog/overview.md)**
>
> Árvore do data lake, prévia de dados, contagem de linhas e lineage de pipelines. Porta 8001.

> **[Connectors API](https://docs.strattum.ai/api-reference/connectors/overview)**
>
> Gerenciamento do ciclo de vida de conectores: criar, testar, listar, atualizar e remover. Porta 8001.

> **[Skills API](https://docs.strattum.ai/api-reference/skills/overview.md)**
>
> Execução de receitas analíticas (skills), gerenciamento de segredos e perguntas sugeridas. Porta 8007.

> **[MCP Server](https://docs.strattum.ai/api-reference/mcp/overview.md)**
>
> 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

> [!NOTE]
>
> 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.

```http theme={null}
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:

```json theme={null}
{
  "detail": "Mensagem descritiva do erro"
}
```

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

```json theme={null}
{
  "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`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.