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

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

## 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](/docs/api/rate-limits).

## Come elenco tutti gli endpoint?

```bash
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:

```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](/docs/api/errors).

## 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](/docs/api/overview) per i dettagli.

## Come faccio la paginazione?

Usi `?limit=` e `?offset=`:

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

Limite predefinito: 100. Massimo: 500.

## Posso filtrare le memorie per categoria o tag?

Sì:

```bash
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](/docs/concepts/fts5-search) e [Ricerca semantica](/docs/concepts/semantic-search).

## Come aggiorno una memoria?

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

```bash
# 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?

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

## Posso fare eliminazione bulk?

Sì:

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

## Prossimi passi

- [Panoramica API](/docs/api/overview)
- [Errori e gestione degli errori](/docs/api/errors)
- [Autenticazione](/docs/getting-started/authentication)