{"title":"FAQ da API","slug":"api-faq","category":"faq","summary":"Perguntas comuns sobre a API — autenticação, limites de taxa, tratamento de erros, descoberta de endpoints.","audience":["human","llm"],"tags":["faq","api","troubleshooting"],"difficulty":"beginner","updated":"2026-06-27","word_count":412,"read_minutes":2,"lang":"pt","translated":true,"requested_lang":"pt","content_markdown":"\n# FAQ da API\n\nPerguntas comuns sobre a API do Synapse.\n\n## Como faço para autenticar?\n\nDois métodos:\n\n1. **Mind Key** (para endpoints de dados): `Authorization: Bearer mk_...`\n2. **JWT** (para endpoints de conta): `Authorization: Bearer eyJ...`\n\nOu via parâmetro de consulta (limite de 60 req/min): `?key=mk_...`\n\nConsulte [Autenticação](/docs/getting-started/authentication).\n\n## Qual a diferença entre Mind Key e JWT?\n\n- **Mind Key**: escopo de tenant, nunca expira, para dados de memória/chat/tarefas\n- **JWT**: escopo de usuário, expira em 7 dias, para gerenciamento de conta/mind\n\nConsulte [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt).\n\n## Por que estou recebendo 401 Unauthorized?\n\nCausas comuns:\n\n1. Cabeçalho `Authorization` ausente\n2. Mind Key inválida (verifique se começa com `mk_`)\n3. Usando JWT onde Mind Key é necessária (ou vice-versa)\n4. Mind Key foi revogada\n\n**Correção:** Verifique seu token. Consulte [Autenticação](/docs/getting-started/authentication).\n\n## Por que estou recebendo 404 Not Found?\n\nVocê usou um caminho de endpoint errado. O Synapse só tem os caminhos listados\nem `GET /endpoints`.\n\n**Correção:** Chame `GET /endpoints` para ver todos os caminhos válidos. Não\nadivinhe.\n\n## Por que estou recebendo 429 Too Many Requests?\n\nVocê está usando auth via parâmetro de consulta `?key=`, que é limitada a 60/min.\n\n**Correção:** Mude para o cabeçalho `Authorization: Bearer` (sem limite de\ntaxa).\n\nConsulte [Limites de taxa](/docs/api/rate-limits).\n\n## Como listo todos os endpoints?\n\n```bash\ncurl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text\n```\n\n## Como encontro o endpoint certo?\n\n1. Confira `GET /endpoints` para a lista legível por máquina\n2. Confira `GET /help` para a documentação completa da API\n3. Navegue em `GET /docs` para o sistema de documentação\n4. Use `GET /openapi.json` para a especificação OpenAPI 3.0\n\n## Posso usar GET em vez de POST?\n\nAlguns endpoints POST têm equivalentes GET para ferramentas somente-URL:\n\n- `POST /memory` ↔ `GET /memory/store?content=...`\n- `POST /mind/task` ↔ `GET /mind/task?title=...`\n- `POST /chat/reply` ↔ `GET /chat/reply?content=...`\n\nConfira `GET /endpoints` para variantes GET disponíveis.\n\n## Como trato erros?\n\nTodos os erros retornam JSON:\n\n```json\n{\n \"statusCode\": 401,\n \"error\": \"Unauthorized\",\n \"message\": \"Mind Key fehlt oder ungültig.\",\n \"docs\": \"https://synapse.schaefer.zone/docs/getting-started/authentication\"\n}\n```\n\nConsulte [Erros e tratamento de erros](/docs/api/errors).\n\n## Qual o limite do corpo da requisição?\n\n10 MB. Para payloads maiores (ex.: upload de arquivos), use os endpoints\nmultipart.\n\n## A API suporta CORS?\n\nSim. Todos os endpoints retornam:\n\n```\nAccess-Control-Allow-Origin: *\nAccess-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS\nAccess-Control-Allow-Headers: Authorization, Content-Type, X-Synapse-JWT\n```\n\n## Existe um SDK?\n\nSim:\n\n- **Node.js**: `npm install synapse-memory-sdk`\n- **MCP**: `npx -y synapse-mcp-api@latest`\n\nConsulte [Visão geral da API](/docs/api/overview) para detalhes.\n\n## Como faço paginação?\n\nUse `?limit=` e `?offset=`:\n\n```bash\ncurl \".../memory?limit=50&offset=100\"\n```\n\nLimite padrão: 100. Máximo: 500.\n\n## Posso filtrar memórias por categoria ou tag?\n\nSim:\n\n```bash\ncurl \".../memory?category=project\"\ncurl \".../memory?tag=docker\"\ncurl \".../memory/by-tag?tag=production\"\n```\n\n## Como faço busca de memórias?\n\nDe duas formas:\n\n1. **Busca por palavras-chave FTS5**: `GET /memory/search?q=docker+swarm`\n2. **Busca semântica**: `GET /memory/semantic-search?q=container+orchestration`\n\nConsulte [Busca FTS5](/docs/concepts/fts5-search) e [Busca semântica](/docs/concepts/semantic-search).\n\n## Como atualizo uma memória?\n\nFaça POST `/memory` com a mesma `category` + `key` — a memória existente é\natualizada, não duplicada.\n\n```bash\n# Initial store\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael\"}'\n\n# Update (same key)\ncurl -X POST .../memory -d '{\"category\":\"fact\",\"key\":\"user_name\",\"content\":\"Michael Schäfer\"}'\n```\n\n## Como excluo uma memória?\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer $KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## Posso excluir em massa?\n\nSim:\n\n```bash\ncurl -X POST .../memory/bulk-delete \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n## Próximos passos\n\n- [Visão geral da API](/docs/api/overview)\n- [Erros e tratamento de erros](/docs/api/errors)\n- [Autenticação](/docs/getting-started/authentication)\n","content_html":"

FAQ da API

\n

Perguntas comuns sobre a API do Synapse.

\n

Como faço para autenticar?

\n

Dois métodos:

\n
    \n
  1. Mind Key (para endpoints de dados): Authorization: Bearer mk_...
    2. \n
  2. JWT (para endpoints de conta): Authorization: Bearer eyJ...
    3. \n
\n

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

\n

Consulte Autenticação.

\n

Qual a diferença entre Mind Key e JWT?

\n\n

Consulte Mind Key vs JWT.

\n

Por que estou recebendo 401 Unauthorized?

\n

Causas comuns:

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

Correção: Verifique seu token. Consulte Autenticação.

\n

Por que estou recebendo 404 Not Found?

\n

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

\n

Correção: Chame GET /endpoints para ver todos os caminhos válidos. Não\nadivinhe.

\n

Por que estou recebendo 429 Too Many Requests?

\n

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

\n

Correção: Mude para o cabeçalho Authorization: Bearer (sem limite de\ntaxa).

\n

Consulte Limites de taxa.

\n

Como listo todos os endpoints?

\n
curl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text

Como encontro o endpoint certo?

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

Posso usar GET em vez de POST?

\n

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

\n\n

Confira GET /endpoints para variantes GET disponíveis.

\n

Como trato erros?

\n

Todos os erros retornam JSON:

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

Consulte Erros e tratamento de erros.

\n

Qual o limite do corpo da requisição?

\n

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

\n

A API suporta CORS?

\n

Sim. Todos os endpoints retornam:

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

Existe um SDK?

\n

Sim:

\n\n

Consulte Visão geral da API para detalhes.

\n

Como faço paginação?

\n

Use ?limit= e ?offset=:

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

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

\n

Posso filtrar memórias por categoria ou tag?

\n

Sim:

\n
curl ".../memory?category=project"\ncurl ".../memory?tag=docker"\ncurl ".../memory/by-tag?tag=production"

Como faço busca de memórias?

\n

De duas formas:

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

Consulte Busca FTS5 e Busca semântica.

\n

Como atualizo uma memória?

\n

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

\n
# Initial store\ncurl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael"}'\n\n# Update (same key)\ncurl -X POST .../memory -d '{"category":"fact","key":"user_name","content":"Michael Schäfer"}'

Como excluo uma memória?

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

Posso excluir em massa?

\n

Sim:

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

Próximos passos

\n\n","urls":{"html":"/docs/faq/api-faq","text":"/docs/faq/api-faq?format=text","json":"/docs/faq/api-faq?format=json","llm":"/docs/faq/api-faq?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}