# Panoramica API e URL di base
SUMMARY: Tutti gli endpoint dell'API Synapse, URL di base, modelli di autenticazione e formati di risposta a colpo d'occhio.

KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)
      OR ?key=YOUR_MIND_KEY (query, 60 req/min)
All responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)
All 404 responses mean the path does not exist — do NOT guess paths.
GET /endpoints returns machine-readable list of all valid endpoints.

Panoramica API e URL di base
L'API di Synapse è un'API HTTP RESTful. Tutti gli endpoint restituiscono JSON
( salvo dove indicato). Questa pagina tratta gli elementi essenziali necessari
prima di addentrarsi negli endpoint specifici.
URL di base
[CODE BLOCK]
Tutti i percorsi in questa documentazione sono relativi a questo URL di base.
Per istanze self-hosted, sostituisca con il proprio URL.
Autenticazione
Due metodi, entrambi inviati tramite header :
[CODE BLOCK]
Oppure tramite parametro query (limitato a 60/min):
[CODE BLOCK]
Veda Autenticazione per i dettagli.
Gruppi di endpoint
| Gruppo | Auth | Descrizione |
|-------|------|-------------|
| Pubblico | Nessuna | Landing page, health, OpenAPI, docs |
| Memory | Mind Key | CRUD, ricerca, sync, embedding |
| Chat | Mind Key / JWT | Messaggistica asincrona tra umano e agente |
| Tasks | Mind Key | Gestione attività |
| Scripts | Mind Key / JWT | Archivio script persistente |
| Scheduler | Mind Key | Cron job + variabili |
| Webhooks | Mind Key | Callback HTTP su eventi |
| Computers | Mind Key / JWT | Controllo computer remoto |
| User/Minds | JWT | Account + gestione mente |
| Sharing | JWT | Condivisione menti tra utenti |
| Push | JWT | Sottoscrizioni Web Push |
| Tools | Nessuna | Time, calc, random (utility pubbliche) |
Formati di risposta
- JSON (predefinito): 
- Testo semplice:  restituisce testo ottimizzato per LLM
- HTML: , , , , 
Busta standard di risposta
Le risposte di successo restituiscono direttamente i dati:
[CODE BLOCK]
Le risposte di errore usano questo formato:
[CODE BLOCK]
> [!NOTE]
> Il campo  linka alla documentazione pertinente per gli errori comuni.
Codici di stato HTTP
| Codice | Significato |
|------|---------|
| 200 | Successo (GET, PUT) |
| 201 | Creato (POST) |
| 204 | Nessun contenuto (DELETE) |
| 400 | Richiesta errata (errore di validazione) |
| 401 | Non autorizzato (token mancante/non valido) |
| 403 | Vietato (tipo di token errato) |
| 404 | Non trovato (percorso inesistente) |
| 409 | Conflitto (duplicato) |
| 429 | Troppe richieste (rate limit) |
| 500 | Errore del server |
Endpoint di scoperta
| Endpoint | Scopo |
|----------|---------|
|  | Landing page (ottimizzata per LLM) |
|  | Lista machine-readable di tutti gli endpoint |
|  | Lista endpoint in testo semplice |
|  | Specifica OpenAPI 3.0 |
|  | Documentazione API completa (HTML) |
|  | Documentazione API come JSON |
|  | Sistema di documentazione (HTML) |
|  | Indice della documentazione (JSON) |
|  | Tutta la documentazione come blocco di testo |
|  | Playground API interattivo |
Limiti di traffico
| Metodo di auth | Limite |
|-------------|-------|
| Mind Key (header) | Nessuno |
| Mind Key (?key=) | 60/min per IP |
| JWT (header) | Nessuno |
| Endpoint pubblici | Nessuno |
Le risposte con limiti di traffico includono:
[CODE BLOCK]
Paginazione
Gli endpoint di elenco supportano  e :
[CODE BLOCK]
Limite predefinito: 100. Limite massimo: 500.
CORS
Tutti gli endpoint supportano CORS per client basati su browser:
[CODE BLOCK]
SDK e client
- SDK Node.js:  (repo)
- Server MCP:  (repo)
- Client HTTP: qualsiasi libreria HTTP (curl, fetch, axios, ecc.)
Prossimi passi
- Memory API — gli endpoint più importanti
- Chat API — comunicazione asincrona umano-agente
- Errori e gestione degli errori