Panoramica API e URL di base

beginner 🤖 Compatibile con LLM 3 min · 575 parole Aggiornato: 2026-06-27 Italiano

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

Leggi questo articolo come: 📄 Testo semplice ⚡ JSON 🤖 Formato LLM

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

https://synapse.schaefer.zone

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 Authorization:

Authorization: Bearer YOUR_MIND_KEY    # for data endpoints
Authorization: Bearer YOUR_JWT          # for account endpoints

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

?key=YOUR_MIND_KEY

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): { "key": "value", ... }
Testo semplice: /memory/recall restituisce testo ottimizzato per LLM
HTML: /, /docs, /human, /support, /playground

Busta standard di risposta

Le risposte di successo restituiscono direttamente i dati:

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

Le risposte di errore usano questo formato:

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

Il campo `docs` 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
`GET /`	Landing page (ottimizzata per LLM)
`GET /endpoints`	Lista machine-readable di tutti gli endpoint
`GET /endpoints?format=text`	Lista endpoint in testo semplice
`GET /openapi.json`	Specifica OpenAPI 3.0
`GET /help`	Documentazione API completa (HTML)
`GET /help?format=json`	Documentazione API come JSON
`GET /docs`	Sistema di documentazione (HTML)
`GET /docs?format=json`	Indice della documentazione (JSON)
`GET /docs?format=text&scope=all`	Tutta la documentazione come blocco di testo
`GET /playground`	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:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Retry-After: 30  (only when 429)

Paginazione

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

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

Limite predefinito: 100. Limite massimo: 500.

CORS

Tutti gli endpoint supportano CORS per client basati su browser:

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

SDK e client

SDK Node.js: npm install synapse-memory-sdk (repo)
Server MCP: npx -y synapse-mcp-api@latest (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