> ## Documentation Index
> Fetch the complete documentation index at: https://strattumai.mintlify.site/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:

<CardGroup cols={2}>
  <Card title="Memory API" icon="brain" href="/api-reference/memory/introduction" color="#6D28D9">
    Perfis de entidades, timeline de eventos, grafo de relações e contexto formatado para agentes. Porta 8002.
  </Card>

  <Card title="Knowledge API" icon="book-open" href="/api-reference/knowledge/introduction" color="#6D28D9">
    Busca semântica sobre documentos indexados e gerenciamento de chunks. Porta 8003.
  </Card>

  <Card title="Catalog API" icon="table" href="/api-reference/catalog/overview" color="#3730A3">
    Árvore do data lake, prévia de dados, contagem de linhas e lineage de pipelines. Porta 8001.
  </Card>

  <Card title="Connectors API" icon="plug" href="/api-reference/connectors/overview" color="#3730A3">
    Gerenciamento do ciclo de vida de conectores: criar, testar, listar, atualizar e remover. Porta 8001.
  </Card>

  <Card title="Skills API" icon="wand-magic-sparkles" href="/api-reference/skills/overview" color="#6D28D9">
    Execução de receitas analíticas (skills), gerenciamento de segredos e perguntas sugeridas. Porta 8007.
  </Card>

  <Card title="MCP Server" icon="server" href="/api-reference/mcp/overview" color="#0D9488">
    Endpoint SSE de transporte MCP para integração com Claude, Microsoft Copilot e ChatGPT. Porta 8005.
  </Card>
</CardGroup>

***

## 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).
</Note>

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`