{"title":"Panoramica API e URL di base","slug":"overview","category":"api","summary":"Tutti gli endpoint dell'API Synapse, URL di base, modelli di autenticazione e formati di risposta a colpo d'occhio.","audience":["human","llm"],"tags":["api","overview","endpoints"],"difficulty":"beginner","updated":"2026-06-27","word_count":575,"read_minutes":3,"llm_context":"Base URL: https://synapse.schaefer.zone\nAuth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)\n OR ?key=YOUR_MIND_KEY (query, 60 req/min)\nAll responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)\nAll 404 responses mean the path does not exist — do NOT guess paths.\nGET /endpoints returns machine-readable list of all valid endpoints.\n","lang":"it","translated":true,"requested_lang":"it","content_markdown":"\n# Panoramica API e URL di base\n\nL'API di Synapse è un'API HTTP RESTful. Tutti gli endpoint restituiscono JSON\n( salvo dove indicato). Questa pagina tratta gli elementi essenziali necessari\nprima di addentrarsi negli endpoint specifici.\n\n## URL di base\n\n```\nhttps://synapse.schaefer.zone\n```\n\nTutti i percorsi in questa documentazione sono relativi a questo URL di base.\nPer istanze self-hosted, sostituisca con il proprio URL.\n\n## Autenticazione\n\nDue metodi, entrambi inviati tramite header `Authorization`:\n\n```\nAuthorization: Bearer YOUR_MIND_KEY # for data endpoints\nAuthorization: Bearer YOUR_JWT # for account endpoints\n```\n\nOppure tramite parametro query (limitato a 60/min):\n\n```\n?key=YOUR_MIND_KEY\n```\n\nVeda [Autenticazione](/docs/getting-started/authentication) per i dettagli.\n\n## Gruppi di endpoint\n\n| Gruppo | Auth | Descrizione |\n|-------|------|-------------|\n| Pubblico | Nessuna | Landing page, health, OpenAPI, docs |\n| Memory | Mind Key | CRUD, ricerca, sync, embedding |\n| Chat | Mind Key / JWT | Messaggistica asincrona tra umano e agente |\n| Tasks | Mind Key | Gestione attività |\n| Scripts | Mind Key / JWT | Archivio script persistente |\n| Scheduler | Mind Key | Cron job + variabili |\n| Webhooks | Mind Key | Callback HTTP su eventi |\n| Computers | Mind Key / JWT | Controllo computer remoto |\n| User/Minds | JWT | Account + gestione mente |\n| Sharing | JWT | Condivisione menti tra utenti |\n| Push | JWT | Sottoscrizioni Web Push |\n| Tools | Nessuna | Time, calc, random (utility pubbliche) |\n\n## Formati di risposta\n\n- **JSON** (predefinito): `{ \"key\": \"value\", ... }`\n- **Testo semplice**: `/memory/recall` restituisce testo ottimizzato per LLM\n- **HTML**: `/`, `/docs`, `/human`, `/support`, `/playground`\n\n## Busta standard di risposta\n\nLe risposte di successo restituiscono direttamente i dati:\n\n```json\n{ \"id\": \"mem_001\", \"status\": \"stored\" }\n```\n\nLe risposte di errore usano questo formato:\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\n> [!NOTE]\n> Il campo `docs` linka alla documentazione pertinente per gli errori comuni.\n\n## Codici di stato HTTP\n\n| Codice | Significato |\n|------|---------|\n| 200 | Successo (GET, PUT) |\n| 201 | Creato (POST) |\n| 204 | Nessun contenuto (DELETE) |\n| 400 | Richiesta errata (errore di validazione) |\n| 401 | Non autorizzato (token mancante/non valido) |\n| 403 | Vietato (tipo di token errato) |\n| 404 | Non trovato (percorso inesistente) |\n| 409 | Conflitto (duplicato) |\n| 429 | Troppe richieste (rate limit) |\n| 500 | Errore del server |\n\n## Endpoint di scoperta\n\n| Endpoint | Scopo |\n|----------|---------|\n| `GET /` | Landing page (ottimizzata per LLM) |\n| `GET /endpoints` | Lista machine-readable di tutti gli endpoint |\n| `GET /endpoints?format=text` | Lista endpoint in testo semplice |\n| `GET /openapi.json` | Specifica OpenAPI 3.0 |\n| `GET /help` | Documentazione API completa (HTML) |\n| `GET /help?format=json` | Documentazione API come JSON |\n| `GET /docs` | Sistema di documentazione (HTML) |\n| `GET /docs?format=json` | Indice della documentazione (JSON) |\n| `GET /docs?format=text&scope=all` | Tutta la documentazione come blocco di testo |\n| `GET /playground` | Playground API interattivo |\n\n## Limiti di traffico\n\n| Metodo di auth | Limite |\n|-------------|-------|\n| Mind Key (header) | Nessuno |\n| Mind Key (?key=) | 60/min per IP |\n| JWT (header) | Nessuno |\n| Endpoint pubblici | Nessuno |\n\nLe risposte con limiti di traffico includono:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30 (only when 429)\n```\n\n## Paginazione\n\nGli endpoint di elenco supportano `?limit=` e `?offset=`:\n\n```\nGET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending\n```\n\nLimite predefinito: 100. Limite massimo: 500.\n\n## CORS\n\nTutti gli endpoint supportano CORS per client basati su browser:\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, Mcp-Session-Id, Mcp-Tool-Profile\n```\n\n## SDK e client\n\n- **SDK Node.js**: `npm install synapse-memory-sdk` ([repo](https://gitlab.com/schaefer-services/synapse-sdk-js))\n- **Server MCP**: `npx -y synapse-mcp-api@latest` ([repo](https://gitlab.com/schaefer-services/synapse-mcp))\n- **Client HTTP**: qualsiasi libreria HTTP (curl, fetch, axios, ecc.)\n\n## Prossimi passi\n\n- [Memory API](/docs/api/memory) — gli endpoint più importanti\n- [Chat API](/docs/api/chat) — comunicazione asincrona umano-agente\n- [Errori e gestione degli errori](/docs/api/errors)\n","content_html":"

Panoramica API e URL di base

\n

L'API di Synapse è un'API HTTP RESTful. Tutti gli endpoint restituiscono JSON\n( salvo dove indicato). Questa pagina tratta gli elementi essenziali necessari\nprima di addentrarsi negli endpoint specifici.

\n

URL di base

\n
https://synapse.schaefer.zone

Tutti i percorsi in questa documentazione sono relativi a questo URL di base.\nPer istanze self-hosted, sostituisca con il proprio URL.

\n

Autenticazione

\n

Due metodi, entrambi inviati tramite header Authorization:

\n
Authorization: Bearer YOUR_MIND_KEY    # for data endpoints\nAuthorization: Bearer YOUR_JWT          # for account endpoints

Oppure tramite parametro query (limitato a 60/min):

\n
?key=YOUR_MIND_KEY

Veda Autenticazione per i dettagli.

\n

Gruppi di endpoint

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
GruppoAuthDescrizione
PubblicoNessunaLanding page, health, OpenAPI, docs
MemoryMind KeyCRUD, ricerca, sync, embedding
ChatMind Key / JWTMessaggistica asincrona tra umano e agente
TasksMind KeyGestione attività
ScriptsMind Key / JWTArchivio script persistente
SchedulerMind KeyCron job + variabili
WebhooksMind KeyCallback HTTP su eventi
ComputersMind Key / JWTControllo computer remoto
User/MindsJWTAccount + gestione mente
SharingJWTCondivisione menti tra utenti
PushJWTSottoscrizioni Web Push
ToolsNessunaTime, calc, random (utility pubbliche)
\n

Formati di risposta

\n\n

Busta standard di risposta

\n

Le risposte di successo restituiscono direttamente i dati:

\n
{ "id": "mem_001", "status": "stored" }

Le risposte di errore usano questo formato:

\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}
Il campo `docs` linka alla documentazione pertinente per gli errori comuni.

Codici di stato HTTP

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CodiceSignificato
200Successo (GET, PUT)
201Creato (POST)
204Nessun contenuto (DELETE)
400Richiesta errata (errore di validazione)
401Non autorizzato (token mancante/non valido)
403Vietato (tipo di token errato)
404Non trovato (percorso inesistente)
409Conflitto (duplicato)
429Troppe richieste (rate limit)
500Errore del server
\n

Endpoint di scoperta

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointScopo
GET /Landing page (ottimizzata per LLM)
GET /endpointsLista machine-readable di tutti gli endpoint
GET /endpoints?format=textLista endpoint in testo semplice
GET /openapi.jsonSpecifica OpenAPI 3.0
GET /helpDocumentazione API completa (HTML)
GET /help?format=jsonDocumentazione API come JSON
GET /docsSistema di documentazione (HTML)
GET /docs?format=jsonIndice della documentazione (JSON)
GET /docs?format=text&scope=allTutta la documentazione come blocco di testo
GET /playgroundPlayground API interattivo
\n

Limiti di traffico

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Metodo di authLimite
Mind Key (header)Nessuno
Mind Key (?key=)60/min per IP
JWT (header)Nessuno
Endpoint pubbliciNessuno
\n

Le risposte con limiti di traffico includono:

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nRetry-After: 30  (only when 429)

Paginazione

\n

Gli endpoint di elenco supportano ?limit= e ?offset=:

\n
GET /memory?limit=50&offset=100\nGET /mind/tasks?status=pending

Limite predefinito: 100. Limite massimo: 500.

\n

CORS

\n

Tutti gli endpoint supportano CORS per client basati su browser:

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

SDK e client

\n\n

Prossimi passi

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