# FAQ da API

Perguntas comuns sobre a API do Synapse.

## Como faço para autenticar?

Dois métodos:

1. **Mind Key** (para endpoints de dados): `Authorization: Bearer mk_...`
2. **JWT** (para endpoints de conta): `Authorization: Bearer eyJ...`

Ou via parâmetro de consulta (limite de 60 req/min): `?key=mk_...`

Consulte [Autenticação](/docs/getting-started/authentication).

## Qual a diferença entre Mind Key e JWT?

- **Mind Key**: escopo de tenant, nunca expira, para dados de memória/chat/tarefas
- **JWT**: escopo de usuário, expira em 7 dias, para gerenciamento de conta/mind

Consulte [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt).

## Por que estou recebendo 401 Unauthorized?

Causas comuns:

1. Cabeçalho `Authorization` ausente
2. Mind Key inválida (verifique se começa com `mk_`)
3. Usando JWT onde Mind Key é necessária (ou vice-versa)
4. Mind Key foi revogada

**Correção:** Verifique seu token. Consulte [Autenticação](/docs/getting-started/authentication).

## Por que estou recebendo 404 Not Found?

Você usou um caminho de endpoint errado. O Synapse só tem os caminhos listados
em `GET /endpoints`.

**Correção:** Chame `GET /endpoints` para ver todos os caminhos válidos. Não
adivinhe.

## Por que estou recebendo 429 Too Many Requests?

Você está usando auth via parâmetro de consulta `?key=`, que é limitada a 60/min.

**Correção:** Mude para o cabeçalho `Authorization: Bearer` (sem limite de
taxa).

Consulte [Limites de taxa](/docs/api/rate-limits).

## Como listo todos os endpoints?

```bash
curl https://synapse.schaefer.zone/endpoints
curl https://synapse.schaefer.zone/endpoints?format=text
```

## Como encontro o endpoint certo?

1. Confira `GET /endpoints` para a lista legível por máquina
2. Confira `GET /help` para a documentação completa da API
3. Navegue em `GET /docs` para o sistema de documentação
4. Use `GET /openapi.json` para a especificação OpenAPI 3.0

## Posso usar GET em vez de POST?

Alguns endpoints POST têm equivalentes GET para ferramentas somente-URL:

- `POST /memory` ↔ `GET /memory/store?content=...`
- `POST /mind/task` ↔ `GET /mind/task?title=...`
- `POST /chat/reply` ↔ `GET /chat/reply?content=...`

Confira `GET /endpoints` para variantes GET disponíveis.

## Como trato erros?

Todos os erros retornam JSON:

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}
```

Consulte [Erros e tratamento de erros](/docs/api/errors).

## Qual o limite do corpo da requisição?

10 MB. Para payloads maiores (ex.: upload de arquivos), use os endpoints
multipart.

## A API suporta CORS?

Sim. Todos os endpoints retornam:

```
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Synapse-JWT
```

## Existe um SDK?

Sim:

- **Node.js**: `npm install synapse-memory-sdk`
- **MCP**: `npx -y synapse-mcp-api@latest`

Consulte [Visão geral da API](/docs/api/overview) para detalhes.

## Como faço paginação?

Use `?limit=` e `?offset=`:

```bash
curl ".../memory?limit=50&offset=100"
```

Limite padrão: 100. Máximo: 500.

## Posso filtrar memórias por categoria ou tag?

Sim:

```bash
curl ".../memory?category=project"
curl ".../memory?tag=docker"
curl ".../memory/by-tag?tag=production"
```

## Como faço busca de memórias?

De duas formas:

1. **Busca por palavras-chave FTS5**: `GET /memory/search?q=docker+swarm`
2. **Busca semântica**: `GET /memory/semantic-search?q=container+orchestration`

Consulte [Busca FTS5](/docs/concepts/fts5-search) e [Busca semântica](/docs/concepts/semantic-search).

## Como atualizo uma memória?

Faça POST `/memory` com a mesma `category` + `key` — a memória existente é
atualizada, não duplicada.

```bash
# Initial store
curl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael"}'

# Update (same key)
curl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael Schäfer"}'
```

## Como excluo uma memória?

```bash
curl -X DELETE -H "Authorization: Bearer $KEY" \
     https://synapse.schaefer.zone/memory/mem_001
```

## Posso excluir em massa?

Sim:

```bash
curl -X POST .../memory/bulk-delete \
  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'
```

## Próximos passos

- [Visão geral da API](/docs/api/overview)
- [Erros e tratamento de erros](/docs/api/errors)
- [Autenticação](/docs/getting-started/authentication)