FAQ API

Domande comuni sull'API di Synapse.

Come mi autentico?

Due metodi:

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

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

Veda Autenticazione.

Qual è la differenza tra Mind Key e JWT?

• Mind Key: scope tenant, non scade mai, per dati memory/chat/tasks
• JWT: scope utente, scadenza 7 giorni, per gestione account/menti

Veda Mind Key vs JWT.

Perché ricevo 401 Unauthorized?

Cause comuni:

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

Soluzione: Verifichi il suo token. Veda Autenticazione.

Perché ricevo 404 Not Found?

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

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

Perché ricevo 429 Too Many Requests?

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

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

Veda Limiti di traffico.

Come elenco tutti gli endpoint?

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

Come trovo l'endpoint giusto?

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

Posso usare GET invece di POST?

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

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

Verifichi GET /endpoints per le varianti GET disponibili.

Come gestisco gli errori?

Tutti gli errori restituiscono JSON:

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

Veda Errori e gestione degli errori.

Qual è il limite del corpo della richiesta?

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

L'API supporta CORS?

Sì. Tutti gli endpoint restituiscono:

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

C'è un SDK?

Sì:

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

Veda Panoramica API per i dettagli.

Come faccio la paginazione?

Usi ?limit= e ?offset=:

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

Limite predefinito: 100. Massimo: 500.

Posso filtrare le memorie per categoria o tag?

Sì:

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

Come cerco nelle memorie?

In due modi:

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

Veda Ricerca FTS5 e Ricerca semantica.

Come aggiorno una memoria?

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

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

Come elimino una memoria?

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

Posso fare eliminazione bulk?

Sì:

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

Prossimi passi

• Panoramica API
• Errori e gestione degli errori
• Autenticazione