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.

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.

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.

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.

Como listo todos os endpoints?

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:

{
  "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.

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 para detalhes.

Como faço paginação?

Use ?limit= e ?offset=:

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

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

Posso filtrar memórias por categoria ou tag?

Sim:

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 e Busca semântica.

Como atualizo uma memória?

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

# 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?

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

Posso excluir em massa?

Sim:

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

Próximos passos

• Visão geral da API
• Erros e tratamento de erros
• Autenticação