{"title":"FAQ API","slug":"api-faq","category":"faq","summary":"Domande comuni sull'API — auth, rate limit, gestione errori, scoperta endpoint.","audience":["human","llm"],"tags":["faq","api","troubleshooting"],"difficulty":"beginner","updated":"2026-06-27","word_count":389,"read_minutes":2,"lang":"it","translated":true,"requested_lang":"it","content_markdown":"\n# FAQ API\n\nDomande comuni sull'API di Synapse.\n\n## Come mi autentico?\n\nDue metodi:\n\n1. **Mind Key** (per endpoint dati): `Authorization: Bearer mk_...`\n2. **JWT** (per endpoint account): `Authorization: Bearer eyJ...`\n\nOppure tramite parametro query (limite 60 req/min): `?key=mk_...`\n\nVeda [Autenticazione](/docs/getting-started/authentication).\n\n## Qual è la differenza tra Mind Key e JWT?\n\n- **Mind Key**: scope tenant, non scade mai, per dati memory/chat/tasks\n- **JWT**: scope utente, scadenza 7 giorni, per gestione account/menti\n\nVeda [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt).\n\n## Perché ricevo 401 Unauthorized?\n\nCause comuni:\n\n1. Header `Authorization` mancante\n2. Mind Key non valida (verifichi che inizi con `mk_`)\n3. Uso di un JWT dove è richiesta una Mind Key (o viceversa)\n4. La Mind Key è stata revocata\n\n**Soluzione:** Verifichi il suo token. Veda [Autenticazione](/docs/getting-started/authentication).\n\n## Perché ricevo 404 Not Found?\n\nHa usato un percorso endpoint errato. Synapse ha solo i percorsi elencati in\n`GET /endpoints`.\n\n**Soluzione:** Chiami `GET /endpoints` per vedere tutti i percorsi validi. Non\nindovini.\n\n## Perché ricevo 429 Too Many Requests?\n\nSta usando l'autenticazione tramite parametro query `?key=`, che è limitata a\n60/min.\n\n**Soluzione:** Passi all'header `Authorization: Bearer` (nessun rate limit).\n\nVeda [Limiti di traffico](/docs/api/rate-limits).\n\n## Come elenco tutti gli endpoint?\n\n```bash\ncurl https://synapse.schaefer.zone/endpoints\ncurl https://synapse.schaefer.zone/endpoints?format=text\n```\n\n## Come trovo l'endpoint giusto?\n\n1. Verifichi `GET /endpoints` per la lista machine-readable\n2. Verifichi `GET /help` per la documentazione API completa\n3. Navigi `GET /docs` per il sistema di documentazione\n4. Usi `GET /openapi.json` per la specifica OpenAPI 3.0\n\n## Posso usare GET invece di POST?\n\nAlcuni endpoint POST hanno equivalenti GET per strumenti solo-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\nVerifichi `GET /endpoints` per le varianti GET disponibili.\n\n## Come gestisco gli errori?\n\nTutti gli errori restituiscono 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\nVeda [Errori e gestione degli errori](/docs/api/errors).\n\n## Qual è il limite del corpo della richiesta?\n\n10 MB. Per payload più grandi (es. caricamento file), usi gli endpoint\nmultipart.\n\n## L'API supporta CORS?\n\nSì. Tutti gli endpoint restituiscono:\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## C'è un SDK?\n\nSì:\n\n- **Node.js**: `npm install synapse-memory-sdk`\n- **MCP**: `npx -y synapse-mcp-api@latest`\n\nVeda [Panoramica API](/docs/api/overview) per i dettagli.\n\n## Come faccio la paginazione?\n\nUsi `?limit=` e `?offset=`:\n\n```bash\ncurl \".../memory?limit=50&offset=100\"\n```\n\nLimite predefinito: 100. Massimo: 500.\n\n## Posso filtrare le memorie per categoria o tag?\n\nSì:\n\n```bash\ncurl \".../memory?category=project\"\ncurl \".../memory?tag=docker\"\ncurl \".../memory/by-tag?tag=production\"\n```\n\n## Come cerco nelle memorie?\n\nIn due modi:\n\n1. **Ricerca per parola chiave FTS5**: `GET /memory/search?q=docker+swarm`\n2. **Ricerca semantica**: `GET /memory/semantic-search?q=container+orchestration`\n\nVeda [Ricerca FTS5](/docs/concepts/fts5-search) e [Ricerca semantica](/docs/concepts/semantic-search).\n\n## Come aggiorno una memoria?\n\nPOST `/memory` con la stessa `category` + `key` — la memoria esistente viene\naggiornata, non duplicata.\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## Come elimino una memoria?\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer $KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## Posso fare eliminazione bulk?\n\nSì:\n\n```bash\ncurl -X POST .../memory/bulk-delete \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n## Prossimi passi\n\n- [Panoramica API](/docs/api/overview)\n- [Errori e gestione degli errori](/docs/api/errors)\n- [Autenticazione](/docs/getting-started/authentication)\n","content_html":"

FAQ API

\n

Domande comuni sull'API di Synapse.

\n

Come mi autentico?

\n

Due metodi:

\n
    \n
  1. Mind Key (per endpoint dati): Authorization: Bearer mk_...
    2. \n
  2. JWT (per endpoint account): Authorization: Bearer eyJ...
    3. \n
\n

Oppure tramite parametro query (limite 60 req/min): ?key=mk_...

\n

Veda Autenticazione.

\n

Qual è la differenza tra Mind Key e JWT?

\n\n

Veda Mind Key vs JWT.

\n

Perché ricevo 401 Unauthorized?

\n

Cause comuni:

\n
    \n
  1. Header Authorization mancante
    2. \n
  2. Mind Key non valida (verifichi che inizi con mk_)
    3. \n
  3. Uso di un JWT dove è richiesta una Mind Key (o viceversa)
    4. \n
  4. La Mind Key è stata revocata
    5. \n
\n

Soluzione: Verifichi il suo token. Veda Autenticazione.

\n

Perché ricevo 404 Not Found?

\n

Ha usato un percorso endpoint errato. Synapse ha solo i percorsi elencati in\nGET /endpoints.

\n

Soluzione: Chiami GET /endpoints per vedere tutti i percorsi validi. Non\nindovini.

\n

Perché ricevo 429 Too Many Requests?

\n

Sta usando l'autenticazione tramite parametro query ?key=, che è limitata a\n60/min.

\n

Soluzione: Passi all'header Authorization: Bearer (nessun rate limit).

\n

Veda Limiti di traffico.

\n

Come elenco tutti gli endpoint?

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

Come trovo l'endpoint giusto?

\n
    \n
  1. Verifichi GET /endpoints per la lista machine-readable
    2. \n
  2. Verifichi GET /help per la documentazione API completa
    3. \n
  3. Navigi GET /docs per il sistema di documentazione
    4. \n
  4. Usi GET /openapi.json per la specifica OpenAPI 3.0
    5. \n
\n

Posso usare GET invece di POST?

\n

Alcuni endpoint POST hanno equivalenti GET per strumenti solo-URL:

\n\n

Verifichi GET /endpoints per le varianti GET disponibili.

\n

Come gestisco gli errori?

\n

Tutti gli errori restituiscono 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}

Veda Errori e gestione degli errori.

\n

Qual è il limite del corpo della richiesta?

\n

10 MB. Per payload più grandi (es. caricamento file), usi gli endpoint\nmultipart.

\n

L'API supporta CORS?

\n

Sì. Tutti gli endpoint restituiscono:

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

C'è un SDK?

\n

Sì:

\n\n

Veda Panoramica API per i dettagli.

\n

Come faccio la paginazione?

\n

Usi ?limit= e ?offset=:

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

Limite predefinito: 100. Massimo: 500.

\n

Posso filtrare le memorie per categoria o tag?

\n

Sì:

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

Come cerco nelle memorie?

\n

In due modi:

\n
    \n
  1. Ricerca per parola chiave FTS5: GET /memory/search?q=docker+swarm
    2. \n
  2. Ricerca semantica: GET /memory/semantic-search?q=container+orchestration
    3. \n
\n

Veda Ricerca FTS5 e Ricerca semantica.

\n

Come aggiorno una memoria?

\n

POST /memory con la stessa category + key — la memoria esistente viene\naggiornata, non duplicata.

\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"}'

Come elimino una memoria?

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

Posso fare eliminazione bulk?

\n

Sì:

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

Prossimi passi

\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"]}