# 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](/docs/getting-started/authentication) 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:

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

Le risposte di errore usano questo formato:

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

> [!NOTE]
> 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](https://gitlab.com/schaefer-services/synapse-sdk-js))
- **Server MCP**: `npx -y synapse-mcp-api@latest` ([repo](https://gitlab.com/schaefer-services/synapse-mcp))
- **Client HTTP**: qualsiasi libreria HTTP (curl, fetch, axios, ecc.)

## Prossimi passi

- [Memory API](/docs/api/memory) — gli endpoint più importanti
- [Chat API](/docs/api/chat) — comunicazione asincrona umano-agente
- [Errori e gestione degli errori](/docs/api/errors)